Changeset 5677


Ignore:
Timestamp:
Jun 29, 2011, 10:28:02 AM (12 years ago)
Author:
Nicklas Nordborg
Message:

References #1590: Documentation cleanup

  • Removed migration-related information from the appendix
  • Removed "Appendix: Menu guide".
  • Removed BASE 2.x-related information from the appendix (API changes that may affect backwards compatibility and Things to consider when updating an existing BASE installation).
Location:
trunk/doc/src/docbook/appendix
Files:
2 deleted
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/appendix/incompatible.xml

    r5560 r5677  
    3535  </para>
    3636 
    37   <note>
     37  <sect1 id="appendix.incompatible.3.0">
     38    <title>BASE 3.0 release</title>
     39
    3840    <para>
    39     There is no history for releases prior to BASE 2.2 because
    40     we did not actively keep track of them. We believe that if such
    41     changes exists, they are minor and does not affect many plug-ins
    42     since in those days very few 3rd-party plug-ins existed.
    43     </para>
    44   </note>
    45 
    46 
    47   <sect1 id="appendix.incompatible.2.17">
    48     <title>BASE 2.17 release</title>
    49 
    50     <bridgehead>Type.getHibernateType() and VirtualColumn.getType()</bridgehead>
    51     <para>
    52       Due to internal changes in Hibernate 3.6 the two methods have been
    53       removed from the BASE API. Existing code should be use
    54       <code>Type.getTypeWrapper()</code> and <code>VirtualColumn.getTypeWrapper()</code>
    55       instead. Since the new methods may not provide the same information as the old
    56       methods developers are encouraged to discuss any problems and workarounds
    57       with the BASE team on the developer mailing list.
     41      There are a lot incompatible changes between BASE 3 and any of the BASE 2.x
     42      versions. We do not list list those changes here since we do not expect existing
     43      plug-ins, extensions or other client application to work with BASE 3 without
     44      modification. See <xref linkend="migrate_2_3" /> for more information.
    5845    </para>
    5946  </sect1>
    6047 
    61   <sect1 id="appendix.incompatible.2.16">
    62     <title>BASE 2.16 release</title>
    63 
    64     <bridgehead>
    65       Location.EXTERNAL, File.getSize() and ProgressReporter.display()
    66     </bridgehead>
    67    
    68     <para>
    69       We have added support for file items that are stored externally by
    70       adding a <code>File.getUrl()</code> method. This is mostly invisible
    71       and methods such as <code>File.download()</code> will work as expected.
    72       The <classname docapi="net.sf.basedb.core">Location</classname> enumeration
    73       has a new option, <code>Location.EXTERNAL</code>. This may cause problems with
    74       code that doesn't know about it assumes that <code>Location.PRIMARY</code>
    75       is the only location when a file can be used. Another issue is that the
    76       size for external files is not always known. The <code>File.getSize()</code>
    77       method is now allowed to return -1 to indicate that the file size is not known.
    78       This may be a problem for code that is unprepared to handle it. For example,
    79       many plug-ins rely on the file size for progress reporting. For the same reason
    80       <interfacename docapi="net.sf.basedb.core">ProgressReporter</interfacename>
    81       implementations should also accept -1 as a valid value indicating unknown
    82       progress.
    83     </para>
    84    
    85     <bridgehead>Type.getHibernateType() and VirtualColumn.getType()</bridgehead>
    86     <para>
    87       Due to internal changes in Hibernate 3.5.2 the two methods have been
    88       deprecated. We expect more changes in the future (Hibernate 3.6) that
    89       may force us to remove the two methods from the BASE API. Existing code
    90       should be updated to use <code>Type.getTypeWrapper()</code> and
    91       <code>VirtualColumn.getTypeWrapper()</code>
    92       instead. Since the new methods may not provide the same information as the old
    93       methods developers are encouraged to discuss any problems and workarounds
    94       with the BASE team on the developer mailing list. Under all circumstances
    95       it is important to stop using the deprecated methods.
    96     </para>
    97    
    98     <bridgehead>Date annotations and plug-in parameters</bridgehead>
    99     <para>
    100       The underlying table used to store date annotation values was actually using a timestamp
    101       column type. With default settings this was not an issue since the time part
    102       of a date was removed before being saved. However, it was possible to write
    103       code or configure BASE so that the time part also was saved. While this
    104       worked fine in some cases, it also caused trouble in others (eg. in the Query API
    105       and in the table exporter). The BASE 2.16 update changes the underlying
    106       database column to a date-only column. All time information that has been stored in
    107       it will be lost. The update also introduces the <code>Type.TIMESTAMP</code>
    108       data type that can be used with annotations and uses a timestamp column in the
    109       database. Most of BASE has been updated to work with the new data type
    110       with some exceptions:
    111     </para>
    112    
    113     <itemizedlist>
    114       <listitem>
    115         <para>
    116           The importer plug-ins for reporters and raw data will only work if
    117           timestamps are written as <code>yyyy-MM-dd HH:mm:ss</code>.
    118         </para>
    119       </listitem>
    120     </itemizedlist>
     48  <sect1 id="appendix.incompatible.2.x">
     49    <title>All BASE 2.x releases</title>
    12150
    12251    <para>
    123       For more information see ticket <ulink url="http://base.thep.lu.se/ticket/1512">1512
    124       (Add support for datetime annotation types)</ulink>.
     52      The list of changes made in the various BASE 2.x releases can be found
     53      in the <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
     54      >BASE 2.17 documentation</ulink>.
    12555    </para>
    126 
    127   </sect1>
    128  
    129  
    130   <sect1 id="appendix.incompatible.2.15">
    131     <title>BASE 2.15 release</title>
    132 
    133     <bridgehead>
    134       Base1PluginExecuter and enumerated parameters
    135     </bridgehead>
    136    
    137     <para>
    138       Enumerated parameters as handled by the Base1PluginExecuter consists
    139       of key/value pairs, for example 0=No, 1=Yes. The 'value' is what the user
    140       sees in the GUI while running jobs and the 'key' is what is sent to
    141       the plug-in in the parameter file. Starting with BASE 2.15 the 'value'
    142       is saved in the database instead of the 'key'. At runtime, a reverse
    143       lookup is used to convert the 'value' into the 'key' that is written
    144       to the parameters file. <emphasis>The reverse lookup only works
    145       if all values are unique.</emphasis> BASE will check for this at
    146       configuration time and throw an exception if this is not the
    147       case. To solve this problem the plug-in should be reconfigured.
    148     </para>
    149    
    150     <bridgehead>
    151       ReporterFlatFileImporter store file parser settings as job parameters
    152     </bridgehead>
    153     <para>
    154       This change was introduced since it should be possible to run the plug-in
    155       without a configuration. Existing code that uses this plug-in outside the
    156       web client, may fail due to not setting required parameter values as job
    157       parameters.
    158     </para>
    159   </sect1>
    160  
    161   <sect1 id="appendix.incompatible.2.13">
    162     <title>BASE 2.13 release</title>
    163 
    164     <bridgehead>
    165       Reporters, Raw data, Features and Array design blocks are now proxied
    166     </bridgehead>
    167    
    168     <para>
    169       This was previously not possible due to a Hibernate problem with
    170       stateless sessions. See <ulink
    171       url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-3528"
    172       >http://opensource.atlassian.com/projects/hibernate/browse/HHH-3528</ulink>
    173       for more information about this problem.
    174     </para>
    175    
    176     <para>
    177       This change means that items linking to reporter, raw data, feature or array design
    178       blocks will no longer load the linked items automatically. This is usually
    179       not a problem since the proxies will be initialised if needed. The exception
    180       is when a stateless session was used to create the proxy since the stateless
    181       can't initialise proxies. In BASE, stateless sessions are only used by <classname
    182       docapi="net.sf.based.core">DataQuery</classname> instances, eg. queries that
    183       returns reporter, raw data or features. When this type of query is used and
    184       when linked items are used in a way that causes proxy initialization the linked
    185       item must be explicitely FETCH JOIN-ed by the query. Here is an example:
    186     </para>
    187    
    188     <programlisting language="java"><![CDATA[
    189 RawBioAssay rba = ...
    190 DataQuery<RawData> rawQuery = rba.getRawData();
    191 rawQuery.join(
    192   Hql.leftJoin(null, "reporter", Item.REPORTER.getAlias(), null, true));
    193 // NOTE! Last parameter is 'true' to FETCH JOIN the reporter!!
    194 ...
    195 DbControl dc = ...
    196 DataResultIterator<RawData> rawData = rawQuery.iterate(dc);
    197 while (rawData.hasNext())
    198 {
    199   RawData rd = rawData.next();
    200   ReporterData reporter = rd.getReporter();
    201   int reporterId = reporter.getId();
    202   // Always safe since getId() doesn't cause proxy initialization
    203 
    204   reporter.getName();
    205   // The above statement will fail in BASE 2.13 if
    206   // the FETCH JOIN is no included
    207   ....
    208 }]]>
    209 </programlisting>
    210  
    211     <para>
    212       The error message to look out for is:
    213       <code>
    214       org.hibernate.SessionException: proxies cannot be fetched by a stateless session
    215       </code>
    216     </para>
    217 
    218     <bridgehead>
    219       Re-attaching a detached item no longer assumes that it has been modified
    220     </bridgehead>
    221    
    222     <para>
    223       The <code>DbControl.reattachItem(BasicItem)</code> method has been deprected
    224       and replaced with <code>DbControl.reattachItem(BasicItem, boolean)</code>.
    225       The boolean parameter is used to tell BASE if the item has been modified
    226       or not while it was detached from the session. The previous behaviour of
    227       <code>DbControl.reattachItem(BasicItem)</code> was equivalent to
    228       <code>DbControl.reattachItem(BasicItem, true)</code>, but this is now
    229       changed to <code>DbControl.reattachItem(BasicItem, false)</code> since
    230       in most cases there are really no changes to the item. The problem with
    231       the old behaviour was seen in the new (in BASE 2.13) change history
    232       functionality which would create UPDATE events even when there was no
    233       change.
    234     </para>
    235 
    236   </sect1>
    237  
    238   <sect1 id="appendix.incompatible.2.12">
    239     <title>BASE 2.12 release</title>
    240    
    241     <bridgehead>
    242       Log-2 and log-10 transformed spot intensity data is now allowed
    243     </bridgehead>
    244     <para>
    245       Prior versions of BASE only allowed unlogged spot intensity values.
    246       Analysis plug-ins that operate on spot data should be updated to
    247       check the kind of values that are present in the source bioassay set
    248       and either:
    249     </para>
    250     <itemizedlist>
    251     <listitem>
    252       <para>
    253       Use an appropriate algorithm if it encounters logged data
    254       </para>
    255     </listitem>
    256     <listitem>
    257       <para>
    258       Give an error message that says that it requires unlogged data
    259       </para>
    260     </listitem>
    261     </itemizedlist>
    262    
    263     <para>
    264       Plug-ins that are not aware of the type of data may produce unexpected
    265       results if they are applied on logged data. The core plug-ins that are
    266       shipped with BASE has been fixed and they should work with any kind
    267       of data. The <classname>Base1PluginExecuter</classname> that is used
    268       for executing BASE 1 plug-ins can be configured to work with only
    269       a specific kind of data. After upgrading to BASE 2.12 a server admin
    270       should manually update the configuration of all registered BASE 1 plug-ins
    271       with information about what kind of source data that is required and
    272       what kind of result data the plug-in produces. The default setting is that
    273       a plug-in works with any kind of data and produces the same kind of data
    274       used as source.
    275     </para>
    276    
    277     <para>
    278       This change also affects formulas, which now has two additional properties:
    279       source and result intensity transform. The source intensity transform property
    280       tells BASE what kind of source data that the formula can be used with. If this
    281       property is not specified the formula can be used with any kind of data. The
    282       result intensity transform property tells BASE what kind of result the forumla
    283       generates. If this property is not specified the formula is expected to
    284       generate the same kind of data as the source data. All existing user-defined
    285       forumlas will not have any of the properties set. After upgrading to BASE 2.12
    286       user should check their formulas and set appropriate values for the source
    287       and result intensity transform attributes.
    288     </para>
    289    
    290     <note>
    291       <title>The ch() function automatically converts logged intensities to unlogged</title>
    292       <para>
    293       In order to maintain as much backwards compatibility as possible the ch() function
    294       will automatically convert logged data back to unlogged. This means that many formulas
    295       will continue to work unmodified, but some may create unneccesary complex formulas.
    296       Consider, for example, the log-ratio formula: <code>log2(ch(1) / ch(2))</code>, which
    297       will be converted to: <code>log2(2 ^ rawCh(1) / 2 ^ rawCh(2))</code> if it is applied on
    298       logged values. A better re-write is: <code>rawCh(1) - rawCh(2)</code>.
    299       </para>
    300     </note>
    301   </sect1>
    302 
    303   <sect1 id="appendix.incompatible.2.11">
    304     <title>BASE 2.11 release</title>
    305    
    306     <bridgehead>
    307       Biomaterial batch importers uses a different coordinate system
    308       to target biowells
    309     </bridgehead>
    310     <para>
    311       The batch importers previously used the same coordinate system
    312       for locating biowells on a plate that BASE uses internally. A
    313       0-based numerical coordinate pair. This has now been changed to use
    314       the more logical alphanumeric 1-based coordinate system typically found on plates.
    315       As an example files should now specify A1, B2, C3 instead of [0,0],
    316       [1,1] or [2,2]. Files that use the "old" coordinate system must
    317       be updated to the new coordinate system, or the imported data will
    318       end up in incorrect wells or in no well at all. The change affects three
    319       batch importers:
    320     </para>
    321     <itemizedlist>
    322       <listitem>
    323       <para><classname docapi="net.sf.basedb.plugins.batchimport">SampleImporter</classname></para>
    324       </listitem>
    325       <listitem>
    326       <para><classname docapi="net.sf.basedb.plugins.batchimport">ExtractImporter</classname></para>
    327       </listitem>
    328       <listitem>
    329       <para><classname docapi="net.sf.basedb.plugins.batchimport">LabeledExtractImporter</classname></para>
    330       </listitem>
    331     </itemizedlist>
    332    
    333     <note>
    334       It is still possible to use purely numerical coordinates, but they must
    335       be 1-based and not 0-based as before!
    336     </note>
    337    
    338     <warning>
    339       The new coordinate system only affects the batch importers. The BASE
    340       web client will still display the internal 0-based coordinate values.
    341       BASE users should be aware of this, particularly if they use the table
    342       exporter to generate template files intended for import at a later
    343       time. In this case the coordinates in the template file needs to be
    344       edited before importing.
    345     </warning>
    346   </sect1>
    347  
    348   <sect1 id="appendix.incompatible.2.10">
    349     <title>BASE 2.10 release</title>
    350    
    351     <bridgehead>Added 'entryDate' property to a lot of items</bridgehead>
    352     <para>
    353       Including reporters and users. Since those two items are extendable
    354       by the server admin this addition may break a custom property with
    355       the same name.
    356     </para>
    357   </sect1>
    358  
    359   <sect1 id="appendix.incompatible.2.9">
    360     <title>BASE 2.9 release</title>
    361    
    362     <bridgehead>Must use a database that supports UTF-8</bridgehead>
    363     <para>
    364       If you have been running BASE on a database that is not using
    365       UTF-8 as the character set you need to convert the database
    366       as part of the update. Read <xref linkend="update.useUTF8" />
    367       for more information.
    368     </para>
    369   </sect1>
    370  
    371  
    372   <sect1 id="appendix.incompatible.2.7.1">
    373     <title>BASE 2.7.1 release</title>
    374    
    375     <bridgehead>Type.BOOLEAN.parseString()</bridgehead>
    376     <para>
    377       This method now converts the empty string, "no", "0", and "false" (ignoring case)
    378       to boolean <constant>false</constant>. A <constant>null</constant>
    379       value as input still returns <constant>null</constant> as output.
    380       All other values are converted to <constant>true</constant>.
    381       Previously, all values except <constant>null</constant> and the string
    382       "true", was converted to <constant>false</constant>. The change was made
    383       to make this method behave the same as other string conversion methods.
    384     </para>
    385   </sect1>
    386  
    387   <sect1 id="appendix.incompatible.2.7">
    388     <title>BASE 2.7 release</title>
    389    
    390     <bridgehead>Tomcat 6 or higher is required</bridgehead>
    391     <para>
    392       If you have been running BASE with Tomcat 5.5 you need
    393       to upgrade your Tomcat installation before installing
    394       BASE 2.7.
    395     </para>
    396   </sect1>
    397  
    398   <sect1 id="appendix.incompatible.2.6">
    399     <title>BASE 2.6 release</title>
    400    
    401     <bridgehead>Feature identification methods</bridgehead>
    402     <para>
    403       Array design features can now be identified by three different methods:
    404       COORDINATES, POSITION and FEATURE_ID. The coordinates method was the
    405       only one supported earlier.
    406     </para>
    407    
    408     <itemizedlist>
    409     <listitem>
    410       <para>
    411       Client and plug-in code that depends on features having unique COORDINATES
    412       may no longer work if used with an array design using a different identification method.
    413       Code that is, directly or indirectly, using a
    414       <classname docapi="net.sf.basedb.core">FeatureBatcher</classname> or
    415       <classname docapi="net.sf.basedb.core">RawDataBatcher</classname> are
    416       probably affected by this. For example, a raw data importer which
    417       doesn't know how to set the position or the feature ID can't import data to
    418       an array design that is using one of the new identification methods.
    419       </para>
    420     </listitem>
    421    
    422     <listitem>
    423       <para>
    424       The POSITION identification method will require a unique position number.
    425       This value used to be an auto-generated sequence starting at 1. The other
    426       identification methods will still do that, but when using the POSITION identification
    427       method the only requirement is that the position value is a unique positive integer.
    428       Client or plug-in code that depends on the position being a number between
    429       1 and the number of features may fail if used with an array design using
    430       the POSITION identification method.
    431       </para>
    432     </listitem>   
    433     </itemizedlist>
    434    
    435     <bridgehead>Data file types</bridgehead>
    436     <para>
    437       The <methodname>DataFileType.setValidatorClass()</methodname> and
    438       <methodname>DataFileType.setMetadataReaderClass()</methodname> no longer
    439       verifies that the specified class names exists and implements the required interfaces.
    440       This validation will instead happen at commit time. The reason for this change is
    441       the added support for having the validator/meta data reader in external JAR files.
    442       This means that the validation can't happen until both the class names and JAR paths
    443       has been set. If a client application need validation before commit time it should use
    444       <methodname>DataFileType.getValidator()</methodname> and
    445       <methodname>DataFileType.getMetadataReader()</methodname> after the class names and JAR
    446       paths has been set.
    447     </para>
    448 
    449     <bridgehead>Job.Status.ABORTING</bridgehead>
    450     <para>
    451       Added the <constant>ABORTING</constant> option to the <classname>Job.Status</classname>
    452       enumeration. This option is used when the <constant>ABORT</constant> signal has been
    453       sent to an executing job, but the job has not yet responded to it.
    454       Code that uses the job's status to decide what action to take may fail
    455       since this is a new option. In most cases, it should be handled in the same way
    456       as if the job is <constant>EXECUTING</constant>.
    457     </para>
    458    
    459     <bridgehead>Hybridization to Labeled extracts link</bridgehead>
    460     <para>
    461       This link can now hold information about which sub-array a labeled
    462       extract belongs to on a multi-array hybridization. Code that is
    463       unaware of the concept of sub-arrays may find hybridizations
    464       where the number of labeled extracts doesn't match the number
    465       channels in the platform used, and that more than one labeled
    466       extract has the same label. This was previously considered as
    467       an error condition by the experiment validator. With the
    468       new scheme the validation has to be done on a sub-array basis instead
    469       of on the complete hybridization.
    470     </para>
    471    
    472     <para>
    473       A similar issue arises when inheriting annotations to a raw bioassay
    474       which stems from a specific sub-array on a multi-array hybridization.
    475       This raw bioassay should only inherit annotations from the labeled
    476       extracts that are part of the same sub-array. For API compatibility
    477       reasons the <methodname>Hybridization.getAnnotatableParents()</methodname>
    478       will still return <emphasis>all</emphasis> labeled extracts. Code
    479       that is calling this method in order to find the parents to
    480       a raw bioassay should instead call the new method,
    481       <methodname>Hybridizations.getAnnotatableParents(int)</methodname>,
    482       where the <code>int</code> is the sub-array index value for
    483       the raw bioassay.
    484     </para>
    485    
    486     <para>
    487       A related issue arise when querying labeled extracts and joining
    488       the source events collection to use the linked hybridizations in
    489       the query. Here is an example:
    490     </para>
    491    
    492     <programlisting language="java">
    493 <![CDATA[
    494 // Find all labeled extracts on a given hybridization
    495 Hybridization current = ...
    496 ItemQuery<LabeledExtract> labeledExtractQuery = LabeledExtract.getQuery();
    497 
    498 // This no longer works
    499 // labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "evt"));
    500 
    501 // Replace the above line with these two line
    502 labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "srcevt"));
    503 labeledExtractQuery.join(Hql.innerJoin("srcevt", "event", "evt"));
    504 
    505 labeledExtractQuery.restrict(
    506   Restrictions.eq(
    507     Hql.property("evt", "hybridization"),
    508     Expressions.integer(current.getId())
    509   )
    510 );
    511 ]]>
    512 </programlisting>
    513 
    514     <para>
    515       The good new is that the modifications makes it possible to filter
    516       the query on used quantity and sub-array. See the Javadoc for
    517       <classname docapi="net.sf.basedb.core">Hybridization</classname>
    518       to get more information.
    519     </para>
    520    
    521   </sect1> 
    522  
    523   <sect1 id="appendix.incompatible.2.5">
    524     <title>BASE 2.5 release</title>
    525    
    526     <bridgehead>Raw data types</bridgehead>
    527     <para>
    528       The <sgmltag class="attribute">storage</sgmltag> attribute of the
    529       <sgmltag class="starttag">raw-data-type</sgmltag> has been deprecated
    530       for the <filename>raw-data-types.xml</filename> file. BASE will refuse
    531       to start if it finds this attribute. Raw data types which doesn't use
    532       the database for storing data should be registered as <classname docapi="net.sf.basedb.core">Platform</classname>:s
    533       instead.
    534     </para>
    535    
    536     <para>
    537       Applications or plug-ins that filters on the <property>rawDataType</property>
    538       property for <classname docapi="net.sf.basedb.core">RawBioAssay</classname> or <classname docapi="net.sf.basedb.core">Experiment</classname>
    539       may need to change. The ID given to raw data types that doesn't use the
    540       database for storing data are prefixed with "<constant>platform.</constant>".
    541       The ID for the Affymetrix platform has changed from <constant>affymetrix</constant>
    542       to <constant>platform.affymetrix</constant>.
    543     </para>
    544    
    545     <bridgehead>Raw bioassays</bridgehead>
    546     <para>
    547       The property <property>spots</property> which used to hold the number
    548       of spots in the database OR in the file(s) has been split into two
    549       properties:
    550     </para>
    551     <itemizedlist>
    552     <listitem>
    553       <para>
    554       <property>spots</property>: Now only holds the number of database spots
    555       </para>
    556     </listitem>
    557     <listitem>
    558       <para>
    559       <property>numFileSpots</property>: Holds the number of spots that are stored in files
    560       </para>
    561     </listitem>
    562     </itemizedlist>
    563    
    564     <para>
    565       Applications or plug-ins that filters on the <property>spots</property> property
    566       may no longer work as expected for file-only platforms, since this value is now
    567       always 0. They should use the <property>numFileSpots</property> property instead.
    568     </para>
    569    
    570     <bridgehead>Array designs</bridgehead>
    571     <para>
    572       The <methodname>ArrayDesign.isAffyChip()</methodname> method has
    573       been deprecated. Applications or plug-ins that filter on the <property>affyChip</property>
    574       property may no longer work as expected. The applications should
    575       instead filter on the <property>platform.externalId</property> and
    576       look for the value given by the constant <constant>Platform.AFFYMETRIX</constant>.
    577     </para>
    578    
    579     <programlisting language="java">
    580 // This may no longer work
    581 query.restrict(
    582    Restrictions.eq(
    583       Hql.property("affyChip"),
    584       Expressions.parameter("affyChip", true, Type.BOOLEAN)
    585    )
    586 );
    587 
    588 // Use this instead
    589 query.restrict(
    590    Restrictions.eq(
    591       Hql.property("platform.externalId"),
    592       Expressions.string(Platform.AFFYMETRIX)
    593    )
    594 );
    595 </programlisting>
    596    
    59756   
    59857  </sect1>
    59958 
    600   <sect1 id="appendix.incompatible.2.4">
    601     <title>BASE 2.4 release</title>
    602    
    603     <bridgehead>Plug-in API</bridgehead>
    604     <para>
    605       The <methodname>InteractivePlugin.isInContext()</methodname>
    606       method may now throw exceptions to indicate error-level
    607       messages. Messages that are returned by the method are
    608       considered as a warning message and are by default no longer
    609       shown to the users.
    610       See <xref linkend="plugin_developer.api.interfaces.interactive" />
    611       and <xref linkend="webclient.configuration.preferences.plugins" />.
    612     </para>
    613    
    614     <bridgehead>Custom JSP pages for plug-ins</bridgehead>
    615     <para>
    616       Plug-ins using custom JSP pages for parameter input are recommended
    617       to pass along the <varname>requestId</varname> parameter. The parameter
    618       is optional, but if used it will prevent data from two different
    619       plug-ins configurations to get mixed up. See
    620       <xref linkend="plugin_developer.api.jspparameters" />.
    621     </para>
    622    
    623     <bridgehead>JEP parser</bridgehead>
    624     <para>
    625       The <methodname>Jep.nodeToExpression()</methodname>
    626       and <methodname>Jep.nodeToString()</methodname> methods
    627       return <constant>NULL</constant> if they find an unqouted
    628       <constant>NULL</constant> string in the expression. This
    629       allows JEP to convert expressions like <code>ch(1) == NULL</code>
    630       into a Query API expression testing for null. To get the
    631       old behaviour use <code>ch(1) == 'NULL'</code>.
    632     </para>
    633    
    634     <bridgehead>Parsing strings into numeric values</bridgehead>
    635     <para>
    636       The <methodname>Type.parseString(String)</methodname> method for
    637       <constant>Type.FLOAT</constant> and <constant>Type.DOUBLE</constant>
    638       has changed it's behaviour for <constant>NaN</constant>
    639       and <constant>Infinity</constant> values. The methods used to
    640       return <constant>Float.NaN</constant>, <constant>Float.NEGATIVE_INFINITY</constant>,
    641       <constant>Float.POSITIVE_INFINITY</constant> or the corresponding
    642       <classname>Double</classname> values. Since databases doesn't like
    643       these special values and eventually most values will go into the database,
    644       the <methodname>parseString</methodname> method now returns <constant>null</constant>
    645       instead.
    646     </para>
    647    
    648     <bridgehead>Extended properties and raw data types</bridgehead>
    649     <para>
    650       We have added validation code to check for invalid values. If you
    651       have modified the <filename>extended-properties.xml</filename>
    652       or the <filename>raw-data-types.xml</filename> file and they
    653       contain invalid values, you may not be able to start BASE until
    654       they are fixed. The validation is rather strict and things that may
    655       have worked before (because you were lucky or the because the database
    656       has been forgiving) may no longer work. Here is an overview of the most
    657       important validation rules:
    658     </para>
    659    
    660     <itemizedlist>
    661     <listitem>
    662       <para>
    663       Names and identifiers for extended properties and raw data type
    664       can only contain letters, digits and underscores. They must not
    665       start with a digit.
    666       </para>
    667     </listitem>
    668     <listitem>
    669       <para>
    670       Names of database tables and columns can only contain letters,
    671       digits and underscores. They must not start with a digit.
    672       </para>
    673     </listitem>
    674     <listitem>
    675       <para>
    676       There mustn't be any duplicate tables, columns, properties, etc.
    677       for a given context. For example, no duplicate tables in the
    678       database, no duplicate columns in a table, and no duplicate
    679       properties for a raw data type.
    680       </para>
    681     </listitem>
    682     </itemizedlist>
    683    
    684   </sect1>
    685  
    686   <sect1 id="appendix.incompatible.2.3">
    687     <title>BASE 2.3 release</title>
    688    
    689     <bridgehead>FlatFileParser</bridgehead>
    690     <para>
    691       The <methodname>hasMoreData()</methodname> method has changed the
    692       order of checks made to determine the line type. The checks are
    693       now made in the following order:
    694      
    695       <orderedlist>
    696       <listitem>
    697         <para>
    698         Check if the line should be ignored.
    699         </para>
    700       </listitem>
    701       <listitem>
    702         <para>
    703         Check if the line is a data footer.
    704         </para>
    705       </listitem>
    706       <listitem>
    707         <para>
    708         Check if the line is the start of a new section.
    709         </para>
    710       </listitem>
    711       <listitem>
    712         <para>
    713         Check if the line is a data line.
    714         </para>
    715       </listitem>
    716       </orderedlist>
    717       The data line check has been moved to the last since it was difficult
    718       to create settings that made sure section and data footer lines where
    719       matched correctly.
    720     </para>
    721 
    722     <bridgehead>BASE 1 Plug-in executer</bridgehead>
    723    
    724     <para>
    725       Changed to store information about plug-in parameters as XML in the
    726       database instead of in the original BASE version 1 plug-in definition file.
    727       Existing BASE version 1 plug-ins must be re-configured before they can be
    728       used. To do this:
    729     </para>
    730    
    731     <orderedlist>
    732     <listitem>
    733       <para>
    734       Go to
    735       <menuchoice>
    736         <guimenu>Administrate</guimenu>
    737         <guisubmenu>Plugins</guisubmenu>
    738         <guimenuitem>Configurations</guimenuitem>
    739       </menuchoice>
    740       </para>
    741     </listitem>
    742     <listitem>
    743       <para>
    744       Step through the configuration wizard for all BASE version 1 plug-in
    745       configurations. You do not need to change any parameters.
    746       Just click on the <guibutton>Next</guibutton> button
    747       until the configuration is complete.
    748       </para>
    749     </listitem>
    750     </orderedlist>
    751   </sect1>
    752 
    753   <sect1 id="appendix.incompatible.2.2">
    754     <title>BASE 2.2 release</title>
    755    
    756     <bridgehead>BASE 1 Plug-in executer</bridgehead>
    757    
    758     <para>
    759       No longer provides a default mapping between BASE version 1 and
    760       BASE version 2 raw data columns. To solve this add
    761       a <guilabel>Formula</guilabel> item with the same name as the
    762       BASE version 1 column name and an expression that picks the BASE
    763       version 2 raw data property. For example:
    764     </para>
    765    
    766 <literallayout>
    767 <guilabel>Name</guilabel>          BCh1Mean
    768 <guilabel>Type</guilabel>          Column expression
    769 <guilabel>Raw data type</guilabel> GenePix
    770 <guilabel>Channels</guilabel>      2
    771 <guilabel>Expressions</guilabel>   1: raw('ch1BgMean')
    772 </literallayout>
    773 
    774   </sect1>
    77559
    77660</appendix>

  • trunk/doc/src/docbook/appendix/index.xml

    r5244 r5677  
    2727  <?dbhtml dir="appendix"?>
    2828  <title>Appendix</title>
    29   <include file="menuguide.xml" />
    3029  <include file="coreplugins.xml" />
    3130  <include file="base.config.xml" />
    … …  
    3534  <include file="jobagent.properties.xml" />
    3635  <include file="jobagent.sh.xml" />
    37   <include file="migrate.properties.xml" />
    3836  <include file="other_config.xml" />
    3937  <include file="incompatible.xml" />

  • trunk/doc/src/docbook/appendix/other_config.xml

    r4509 r5677  
    3636    <title>log4.properties</title>
    3737    <para>TODO</para>
    38     <sect2 id="appendix.otherconfig.log4j.migration">
    39       <title>Migration logger</title>
    40       <para>
    41         The migration logger is by default set to <constant>warn</constant> and
    42         the output will be put in a file called <filename>migration.log</filename>, located
    43         in the same directory as the migration is executed from (normaly
    44         <filename class="directory">base2root/bin/</filename>).
    45       </para>
    46       <para>
    47         The common logger for the migration is called
    48         <classname>log4j.logger.net.sf.basedb.clients.migrate</classname>
    49         and sets general properties for the whole migration logging, but each class/item
    50         transfer can also have separate levels of logging. Logging for a separate class is set by
    51         defining the level for the class logger to use. Setting the level for a sublogger
    52         is done like this:
    53         <classname>
    54           log4j.logger.net.sf.basedb.clients.migrate.<replaceable>Classname</replaceable>
    55         </classname>
    56         =
    57         <replaceable>level</replaceable>
    58       </para>
    59     </sect2>
    6038  </sect1>
    6139

  • trunk/doc/src/docbook/appendix/update_warnings.xml

    r4638 r5677  
    2828  <title>Things to consider when updating an existing BASE installation</title>
    2929  <para>
    30     This document is a complete list of things that may have to be considered
     30    This document is a list of things that may have to be considered
    3131    when updating a BASE installation to a newer version. The <xref
    3232    linkend="installation_upgrade.upgrade" /> section only include the most
    … …  
    3535  </para>
    3636 
    37   <sect1 id="appendix.update_warnings.2.9">
    38     <title>BASE 2.9 release</title>
     37  <sect1 id="appendix.update_warnings.2.x">
     38    <title>All BASE 2.x releases</title>
    3939   
    40     <bridgehead id="update.useUTF8">BASE 2.9 must use a database that supports UTF-8</bridgehead>
    4140    <para>
    42       If you are upgrading from BASE 2.8 or lower and your existing
    43       database is not using UTF-8 you must convert the database to
    44       UTF-8 <emphasis>before you execute the <code>./updatedb.sh</code></emphasis>
    45       script.
    46     </para>
    47     <para>
    48       BASE 2.9 includes a utility that can convert an existing MySQL
    49       database. After installing the BASE 2.9 files, but <emphasis>before</emphasis>
    50       running the <code>./updatedb.sh</code> script, execute the following
    51       on the command line:
    52     </para>
    53     <programlisting>
    54 <![CDATA[
    55 cd <base-dir>/bin
    56 ./onetimefix.sh utf8 -x
    57 ]]>
    58 </programlisting>
    59  
    60     <para>
    61       The <code>-x</code> option makes the script update the database immediately.
    62       You can leave this option out to have it generate a SQL script file
    63       (<filename>convert-to-utf8.sql</filename>) instead. The script will by default
    64       not try to convert tables that it already thinks are using UTF-8. If the script
    65       for some reason is incorrect when detecting this, you can use the option
    66       <code>-f</code> to force conversion of all tables.
     41      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
     42      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
     43      BASE 2.17 can be downloaded from the <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
     44      download page</ulink>. Documentation for BASE 2.17 is available as part of the
     45      download and at <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
     46      >http://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>.
    6747    </para>
    6848
    69     <para>
    70       The conversion utility only works with MySQL. PostgreSQL users should
    71       instead use a backup and restore using as described in the
    72       <ulink url="http://www.postgresql.org/docs/8.1/static/backup.html">PostgreSQL manual</ulink>.
    73       Eg. dump the existing BASE database, create a new database that uses UTF8 and
    74       restore the backup into the new database.
    75     </para>
    7649  </sect1>
    7750 
    78   <sect1 id="appendix.update_warnings.2.7.2">
    79     <title>BASE 2.7.2 release</title>
    80    
    81     <bridgehead id="update.lowess_bug">Bug in the LOWESS plug-in affecting BASE version 2.0 -- 2.7.1</bridgehead>
    82     <para>
    83       BASE 2.7.2 fixes a serious bug in the LOWESS plug-in shipped
    84       as a part of the BASE package. The bug is found in all
    85       BASE versions between 2.0 and 2.7.1, and has caused incorrect normalization values to be
    86       calculated. All data that has been normalized with the LOWESS plug-in prior
    87       to BASE 2.7.2 should be considered invalid and needs to be re-normalized with
    88       the fixed version. Downstream analysis steps that has used the incorrectly
    89       normalized data also needs to be redone. For more information about the bug see
    90       <ulink url="http://base.thep.lu.se/ticket/1077">http://base.thep.lu.se/ticket/1077</ulink>
    91     </para>
    92     <para>
    93       BASE 2.7.2 includes a utility for finding all experiments/bioassay sets that
    94       includes data normalized with the LOWESS plug-in. An administrator can use
    95       this utility to extract a list of all experiments/bioassay sets that needs to be fixed.
    96       The utility can also tag the name of the found experiments/bioassay sets with
    97       <code>FIX LOWESS</code> to make it easier to find data that needs to be fixed.
    98     </para>
    99     <para>
    100       The utility can't see any difference between data normalized with the
    101       old version and the fixed version. It will simply report all data that
    102       has been normalized with the LOWESS plug-in. Only use the utility a single
    103       time right after the upgrade to BASE 2.7.2.
    104     </para>
    105     <para>
    106       The utility is a command line program that should be executed on the BASE
    107       application (web) server.
    108     </para>   
    109     <programlisting>
    110 <![CDATA[
    111 cd <base-dir>/bin
    112 ./onetimefix.sh lowess_warn -u <login> -p <password> -f
    113 ]]>
    114 </programlisting>
    115     <para>
    116       We recommend running the utility as the root user. The <option>-f</option>
    117       option is optional. If it is included the found experiments/bioassay sets
    118       are tagged with <code>FIX LOWESS</code>, otherwise only a list with the
    119       information is generated.
    120     </para>
    121   </sect1>
    122      
    123   <sect1 id="appendix.update_warnings.2.7">
    124     <title>BASE 2.7 release</title>
    125    
    126     <bridgehead id="update.tomcat6">BASE 2.7 requires Tomcat 6 or higher</bridgehead>
    127     <para>
    128       If you are upgrading from older BASE versions to BASE 2.7 or higher
    129       you must also make sure that you are running Tomcat 6 or higher.
    130       Earlier BASE versions only required Tomcat 5.5. If you are not
    131       already running Tomcat 6 you need to upgrade. Other servlet
    132       engines may work if they implement the Servlet 2.5 and JSP
    133       2.1 specifications.
    134     </para>
    135   </sect1>
    136 
    137 
    138   <sect1 id="appendix.update_warnings.2.4.4">
    139     <title>BASE 2.4.4 release</title>
    140  
    141     <bridgehead id="update.dropindexes">Upgrading from BASE 2.4.3 or lower to 2.4.4 or higher</bridgehead>
    142     <para>
    143       Older releases of BASE 2 used to create indexes for many columns
    144       in the dynamic database. The same columns are part of the primary
    145       key for the tables so the indexes are not really needed. The
    146       result is very bad performance since the database engine sometimes
    147       get stuck in "index update" mode making the entire server
    148       very slow. BASE 2.4.4 no longer creates the indexes. Indexes on
    149       existing tables should be dropped to increase the performance.
    150       Tests have shown a 50-90% decrease in execution time for some
    151       plug-ins
    152       (<ulink url="http://base.thep.lu.se/ticket/294">http://base.thep.lu.se/ticket/294</ulink>).
    153     </para>
    154     <para>
    155       Removing the indexes is very simple. <emphasis>After the server
    156       has been upgraded</emphasis> following the usual instructions below, issue the
    157       the following commands:
    158     </para>
    159  
    160     <programlisting>
    161 cd &lt;basedir&gt;/bin
    162 ./dynamicdb.sh -v -dropindexes
    163 </programlisting>
    164 
    165     <para>
    166       Skip the <option>-dropindexes</option> option to do a dry
    167       run without actually deleting the indexes.
    168     </para>
    169   </sect1>
    170 
    17151</appendix>
    17252
Note: See TracChangeset for help on using the changeset viewer.