source: trunk/doc/src/docbook/appendix/incompatible.xml @ 4920

Last change on this file since 4920 was 4920, checked in by Nicklas Nordborg, 13 years ago

Fixes #1120: The dynamic part of BASE should keep track whether intensity data is in log space or not

Updated documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 21.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: incompatible.xml 4920 2009-05-04 09:33:49Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<appendix id="appendix.incompatible">
28  <title>API changes that may affect backwards compatibility</title>
29  <para>
30    In this document we list all changes to code in the <emphasis>Public API</emphasis>
31    that may be backwards incompatible with existing client applications
32    and or plug-ins. See <xref linkend="api_overview.public_api" /> for more
33    information about what we mean with the <emphasis>Public API</emphasis>
34    and backwards compatible.
35  </para>
36 
37  <note>
38    <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  <sect1 id="appendix.incompatible.2.12">
47    <title>BASE 2.12 release</title>
48   
49    <bridgehead>
50      Log-2 and log-10 transformed spot intensity data is now allowed
51    </bridgehead>
52    <para>
53      Prior versions of BASE only allowed unlogged spot intensity values.
54      Analysis plug-ins that operate on spot data should be updated to
55      check the kind of values that are present in the source bioassay set
56      and either:
57    </para>
58    <itemizedlist>
59    <listitem>
60      <para>
61      Use an appropriate algorithm if it encounters logged data
62      </para>
63    </listitem>
64    <listitem>
65      <para>
66      Give an error message that says that it requires unlogged data
67      </para>
68    </listitem>
69    </itemizedlist>
70   
71    <para>
72      Plug-ins that are not aware of the type of data may produce unexpected
73      results if they are applied on logged data. The core plug-ins that are
74      shipped with BASE has been fixed and they should work with any kind
75      of data. The <classname>Base1PluginExecuter</classname> that is used
76      for executing BASE 1 plug-ins can be configured to work with only
77      a specific kind of data. After upgrading to BASE 2.12 a server admin
78      should manually update the configuration of all registered BASE 1 plug-ins
79      with information about what kind of source data that is required and
80      what kind of result data the plug-in produces. The default setting is that
81      a plug-in works with any kind of data and produces the same kind of data
82      used as source.
83    </para>
84   
85    <para>
86      This change also affects formulas, which now has two additional properties:
87      source and result intensity transform. The source intensity transform property
88      tells BASE what kind of source data that the formula can be used with. If this
89      property is not specified the formula can be used with any kind of data. The
90      result intensity transform property tells BASE what kind of result the forumla
91      generates. If this property is not specified the formula is expected to
92      generate the same kind of data as the source data. All existing user-defined
93      forumlas will not have any of the properties set. After upgrading to BASE 2.12
94      user should check their formulas and set appropriate values for the source
95      and result intensity transform attributes.
96    </para>
97   
98    <note>
99      <title>The ch() function automatically converts logged intensities to unlogged</title>
100      <para>
101      In order to maintain as much backwards compatibility as possible the ch() function
102      will automatically convert logged data back to unlogged. This means that many formulas
103      will continue to work unmodified, but some may create unneccesary complex formulas.
104      Consider, for example, the log-ratio formula: <code>log2(ch(1) / ch(2))</code>, which
105      will be converted to: <code>log2(2 ^ rawCh(1) / 2 ^ rawCh(2))</code> if it is applied on
106      logged values. A better re-write is: <code>rawCh(1) - rawCh(2)</code>.
107      </para>
108    </note>
109  </sect1>
110
111  <sect1 id="appendix.incompatible.2.11">
112    <title>BASE 2.11 release</title>
113   
114    <bridgehead>
115      Biomaterial batch importers uses a different coordinate system
116      to target biowells
117    </bridgehead>
118    <para>
119      The batch importers previously used the same coordinate system
120      for locating biowells on a plate that BASE uses internally. A
121      0-based numerical coordinate pair. This has now been changed to use
122      the more logical alphanumeric 1-based coordinate system typically found on plates.
123      As an example files should now specify A1, B2, C3 instead of [0,0],
124      [1,1] or [2,2]. Files that use the "old" coordinate system must
125      be updated to the new coordinate system, or the imported data will
126      end up in incorrect wells or in no well at all. The change affects three
127      batch importers:
128    </para>
129    <itemizedlist>
130      <listitem>
131      <para><classname docapi="net.sf.basedb.plugins.batchimport">SampleImporter</classname></para>
132      </listitem>
133      <listitem>
134      <para><classname docapi="net.sf.basedb.plugins.batchimport">ExtractImporter</classname></para>
135      </listitem>
136      <listitem>
137      <para><classname docapi="net.sf.basedb.plugins.batchimport">LabeledExtractImporter</classname></para>
138      </listitem>
139    </itemizedlist>
140   
141    <note>
142      It is still possible to use purely numerical coordinates, but they must
143      be 1-based and not 0-based as before!
144    </note>
145   
146    <warning>
147      The new coordinate system only affects the batch importers. The BASE
148      web client will still display the internal 0-based coordinate values.
149      BASE users should be aware of this, particularly if they use the table
150      exporter to generate template files intended for import at a later
151      time. In this case the coordinates in the template file needs to be
152      edited before importing.
153    </warning>
154  </sect1>
155 
156  <sect1 id="appendix.incompatible.2.10">
157    <title>BASE 2.10 release</title>
158   
159    <bridgehead>Added 'entryDate' property to a lot of items</bridgehead>
160    <para>
161      Including reporters and users. Since those two items are extendable
162      by the server admin this addition may break a custom property with
163      the same name.
164    </para>
165  </sect1>
166 
167  <sect1 id="appendix.incompatible.2.9">
168    <title>BASE 2.9 release</title>
169   
170    <bridgehead>Must use a database that supports UTF-8</bridgehead>
171    <para>
172      If you have been running BASE on a database that is not using
173      UTF-8 as the character set you need to convert the database
174      as part of the update. Read <xref linkend="update.useUTF8" />
175      for more information.
176    </para>
177  </sect1>
178 
179 
180  <sect1 id="appendix.incompatible.2.7.1">
181    <title>BASE 2.7.1 release</title>
182   
183    <bridgehead>Type.BOOLEAN.parseString()</bridgehead>
184    <para>
185      This method now converts the empty string, "no", "0", and "false" (ignoring case)
186      to boolean <constant>false</constant>. A <constant>null</constant>
187      value as input still returns <constant>null</constant> as output.
188      All other values are converted to <constant>true</constant>.
189      Previously, all values except <constant>null</constant> and the string
190      "true", was converted to <constant>false</constant>. The change was made
191      to make this method behave the same as other string conversion methods.
192    </para>
193  </sect1>
194 
195  <sect1 id="appendix.incompatible.2.7">
196    <title>BASE 2.7 release</title>
197   
198    <bridgehead>Tomcat 6 or higher is required</bridgehead>
199    <para>
200      If you have been running BASE with Tomcat 5.5 you need
201      to upgrade your Tomcat installation before installing
202      BASE 2.7.
203    </para>
204  </sect1>
205 
206  <sect1 id="appendix.incompatible.2.6">
207    <title>BASE 2.6 release</title>
208   
209    <bridgehead>Feature identification methods</bridgehead>
210    <para>
211      Array design features can now be identified by three different methods:
212      COORDINATES, POSITION and FEATURE_ID. The coordinates method was the
213      only one supported earlier.
214    </para>
215   
216    <itemizedlist>
217    <listitem>
218      <para>
219      Client and plug-in code that depends on features having unique COORDINATES
220      may no longer work if used with an array design using a different identification method.
221      Code that is, directly or indirectly, using a
222      <classname docapi="net.sf.basedb.core">FeatureBatcher</classname> or
223      <classname docapi="net.sf.basedb.core">RawDataBatcher</classname> are
224      probably affected by this. For example, a raw data importer which
225      doesn't know how to set the position or the feature ID can't import data to
226      an array design that is using one of the new identification methods.
227      </para>
228    </listitem>
229   
230    <listitem>
231      <para>
232      The POSITION identification method will require a unique position number.
233      This value used to be an auto-generated sequence starting at 1. The other
234      identification methods will still do that, but when using the POSITION identification
235      method the only requirement is that the position value is a unique positive integer.
236      Client or plug-in code that depends on the position being a number between
237      1 and the number of features may fail if used with an array design using
238      the POSITION identification method.
239      </para>
240    </listitem>   
241    </itemizedlist>
242   
243    <bridgehead>Data file types</bridgehead>
244    <para>
245      The <methodname>DataFileType.setValidatorClass()</methodname> and
246      <methodname>DataFileType.setMetadataReaderClass()</methodname> no longer
247      verifies that the specified class names exists and implements the required interfaces.
248      This validation will instead happen at commit time. The reason for this change is
249      the added support for having the validator/meta data reader in external JAR files.
250      This means that the validation can't happen until both the class names and JAR paths
251      has been set. If a client application need validation before commit time it should use
252      <methodname>DataFileType.getValidator()</methodname> and
253      <methodname>DataFileType.getMetadataReader()</methodname> after the class names and JAR
254      paths has been set.
255    </para>
256
257    <bridgehead>Job.Status.ABORTING</bridgehead>
258    <para>
259      Added the <constant>ABORTING</constant> option to the <classname>Job.Status</classname>
260      enumeration. This option is used when the <constant>ABORT</constant> signal has been
261      sent to an executing job, but the job has not yet responded to it.
262      Code that uses the job's status to decide what action to take may fail
263      since this is a new option. In most cases, it should be handled in the same way
264      as if the job is <constant>EXECUTING</constant>.
265    </para>
266   
267    <bridgehead>Hybridization to Labeled extracts link</bridgehead>
268    <para>
269      This link can now hold information about which sub-array a labeled
270      extract belongs to on a multi-array hybridization. Code that is
271      unaware of the concept of sub-arrays may find hybridizations
272      where the number of labeled extracts doesn't match the number
273      channels in the platform used, and that more than one labeled
274      extract has the same label. This was previously considered as
275      an error condition by the experiment validator. With the
276      new scheme the validation has to be done on a sub-array basis instead
277      of on the complete hybridization.
278    </para>
279   
280    <para>
281      A similar issue arises when inheriting annotations to a raw bioassay
282      which stems from a specific sub-array on a multi-array hybridization.
283      This raw bioassay should only inherit annotations from the labeled
284      extracts that are part of the same sub-array. For API compatibility
285      reasons the <methodname>Hybridization.getAnnotatableParents()</methodname>
286      will still return <emphasis>all</emphasis> labeled extracts. Code
287      that is calling this method in order to find the parents to
288      a raw bioassay should instead call the new method,
289      <methodname>Hybridizations.getAnnotatableParents(int)</methodname>,
290      where the <code>int</code> is the sub-array index value for
291      the raw bioassay.
292    </para>
293   
294    <para>
295      A related issue arise when querying labeled extracts and joining
296      the source events collection to use the linked hybridizations in
297      the query. Here is an example:
298    </para>
299   
300    <programlisting language="java">
301<![CDATA[
302// Find all labeled extracts on a given hybridization
303Hybridization current = ...
304ItemQuery<LabeledExtract> labeledExtractQuery = LabeledExtract.getQuery();
305
306// This no longer works
307// labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "evt"));
308
309// Replace the above line with these two line
310labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "srcevt"));
311labeledExtractQuery.join(Hql.innerJoin("srcevt", "event", "evt"));
312
313labeledExtractQuery.restrict(
314  Restrictions.eq(
315    Hql.property("evt", "hybridization"),
316    Expressions.integer(current.getId())
317  )
318);
319]]>
320</programlisting>
321
322    <para>
323      The good new is that the modifications makes it possible to filter
324      the query on used quantity and sub-array. See the Javadoc for
325      <classname docapi="net.sf.basedb.core">Hybridization</classname>
326      to get more information.
327    </para>
328   
329  </sect1> 
330 
331  <sect1 id="appendix.incompatible.2.5">
332    <title>BASE 2.5 release</title>
333   
334    <bridgehead>Raw data types</bridgehead>
335    <para>
336      The <sgmltag class="attribute">storage</sgmltag> attribute of the
337      <sgmltag class="starttag">raw-data-type</sgmltag> has been deprecated
338      for the <filename>raw-data-types.xml</filename> file. BASE will refuse
339      to start if it finds this attribute. Raw data types which doesn't use
340      the database for storing data should be registered as <classname docapi="net.sf.basedb.core">Platform</classname>:s
341      instead.
342    </para>
343   
344    <para>
345      Applications or plug-ins that filters on the <property>rawDataType</property>
346      property for <classname docapi="net.sf.basedb.core">RawBioAssay</classname> or <classname docapi="net.sf.basedb.core">Experiment</classname>
347      may need to change. The ID given to raw data types that doesn't use the
348      database for storing data are prefixed with "<constant>platform.</constant>".
349      The ID for the Affymetrix platform has changed from <constant>affymetrix</constant>
350      to <constant>platform.affymetrix</constant>.
351    </para>
352   
353    <bridgehead>Raw bioassays</bridgehead>
354    <para>
355      The property <property>spots</property> which used to hold the number
356      of spots in the database OR in the file(s) has been split into two
357      properties:
358    </para>
359    <itemizedlist>
360    <listitem>
361      <para>
362      <property>spots</property>: Now only holds the number of database spots
363      </para>
364    </listitem>
365    <listitem>
366      <para>
367      <property>numFileSpots</property>: Holds the number of spots that are stored in files
368      </para>
369    </listitem>
370    </itemizedlist>
371   
372    <para>
373      Applications or plug-ins that filters on the <property>spots</property> property
374      may no longer work as expected for file-only platforms, since this value is now
375      always 0. They should use the <property>numFileSpots</property> property instead.
376    </para>
377   
378    <bridgehead>Array designs</bridgehead>
379    <para>
380      The <methodname>ArrayDesign.isAffyChip()</methodname> method has
381      been deprecated. Applications or plug-ins that filter on the <property>affyChip</property>
382      property may no longer work as expected. The applications should
383      instead filter on the <property>platform.externalId</property> and
384      look for the value given by the constant <constant>Platform.AFFYMETRIX</constant>.
385    </para>
386   
387    <programlisting language="java">
388// This may no longer work
389query.restrict(
390   Restrictions.eq(
391      Hql.property("affyChip"),
392      Expressions.parameter("affyChip", true, Type.BOOLEAN)
393   )
394);
395
396// Use this instead
397query.restrict(
398   Restrictions.eq(
399      Hql.property("platform.externalId"),
400      Expressions.string(Platform.AFFYMETRIX)
401   )
402);
403</programlisting>
404   
405   
406  </sect1>
407 
408  <sect1 id="appendix.incompatible.2.4">
409    <title>BASE 2.4 release</title>
410   
411    <bridgehead>Plug-in API</bridgehead>
412    <para>
413      The <methodname>InteractivePlugin.isInContext()</methodname>
414      method may now throw exceptions to indicate error-level
415      messages. Messages that are returned by the method are
416      considered as a warning message and are by default no longer
417      shown to the users.
418      See <xref linkend="plugin_developer.api.interfaces.interactive" />
419      and <xref linkend="webclient.configuration.preferences.plugins" />.
420    </para>
421   
422    <bridgehead>Custom JSP pages for plug-ins</bridgehead>
423    <para>
424      Plug-ins using custom JSP pages for parameter input are recommended
425      to pass along the <varname>requestId</varname> parameter. The parameter
426      is optional, but if used it will prevent data from two different
427      plug-ins configurations to get mixed up. See
428      <xref linkend="plugin_developer.api.jspparameters" />.
429    </para>
430   
431    <bridgehead>JEP parser</bridgehead>
432    <para>
433      The <methodname>Jep.nodeToExpression()</methodname>
434      and <methodname>Jep.nodeToString()</methodname> methods
435      return <constant>NULL</constant> if they find an unqouted
436      <constant>NULL</constant> string in the expression. This
437      allows JEP to convert expressions like <code>ch(1) == NULL</code>
438      into a Query API expression testing for null. To get the
439      old behaviour use <code>ch(1) == 'NULL'</code>.
440    </para>
441   
442    <bridgehead>Parsing strings into numeric values</bridgehead>
443    <para>
444      The <methodname>Type.parseString(String)</methodname> method for
445      <constant>Type.FLOAT</constant> and <constant>Type.DOUBLE</constant>
446      has changed it's behaviour for <constant>NaN</constant>
447      and <constant>Infinity</constant> values. The methods used to
448      return <constant>Float.NaN</constant>, <constant>Float.NEGATIVE_INFINITY</constant>,
449      <constant>Float.POSITIVE_INFINITY</constant> or the corresponding
450      <classname>Double</classname> values. Since databases doesn't like
451      these special values and eventually most values will go into the database,
452      the <methodname>parseString</methodname> method now returns <constant>null</constant> 
453      instead.
454    </para>
455   
456    <bridgehead>Extended properties and raw data types</bridgehead>
457    <para>
458      We have added validation code to check for invalid values. If you
459      have modified the <filename>extended-properties.xml</filename>
460      or the <filename>raw-data-types.xml</filename> file and they
461      contain invalid values, you may not be able to start BASE until
462      they are fixed. The validation is rather strict and things that may
463      have worked before (because you were lucky or the because the database
464      has been forgiving) may no longer work. Here is an overview of the most
465      important validation rules:
466    </para>
467   
468    <itemizedlist>
469    <listitem>
470      <para>
471      Names and identifiers for extended properties and raw data type
472      can only contain letters, digits and underscores. They must not
473      start with a digit.
474      </para>
475    </listitem>
476    <listitem>
477      <para>
478      Names of database tables and columns can only contain letters,
479      digits and underscores. They must not start with a digit.
480      </para>
481    </listitem>
482    <listitem>
483      <para>
484      There mustn't be any duplicate tables, columns, properties, etc.
485      for a given context. For example, no duplicate tables in the
486      database, no duplicate columns in a table, and no duplicate
487      properties for a raw data type.
488      </para>
489    </listitem>
490    </itemizedlist>
491   
492  </sect1>
493 
494  <sect1 id="appendix.incompatible.2.3">
495    <title>BASE 2.3 release</title>
496   
497    <bridgehead>FlatFileParser</bridgehead>
498    <para>
499      The <methodname>hasMoreData()</methodname> method has changed the
500      order of checks made to determine the line type. The checks are
501      now made in the following order:
502     
503      <orderedlist>
504      <listitem>
505        <para>
506        Check if the line should be ignored.
507        </para>
508      </listitem>
509      <listitem>
510        <para>
511        Check if the line is a data footer.
512        </para>
513      </listitem>
514      <listitem>
515        <para>
516        Check if the line is the start of a new section.
517        </para>
518      </listitem>
519      <listitem>
520        <para>
521        Check if the line is a data line.
522        </para>
523      </listitem>
524      </orderedlist>
525      The data line check has been moved to the last since it was difficult
526      to create settings that made sure section and data footer lines where
527      matched correctly.
528    </para>
529
530    <bridgehead>BASE 1 Plug-in executer</bridgehead>
531   
532    <para>
533      Changed to store information about plug-in parameters as XML in the
534      database instead of in the original BASE version 1 plug-in definition file.
535      Existing BASE version 1 plug-ins must be re-configured before they can be
536      used. To do this:
537    </para>
538   
539    <orderedlist>
540    <listitem>
541      <para>
542      Go to
543      <menuchoice>
544        <guimenu>Administrate</guimenu>
545        <guisubmenu>Plugins</guisubmenu>
546        <guimenuitem>Configurations</guimenuitem>
547      </menuchoice>
548      </para>
549    </listitem>
550    <listitem>
551      <para>
552      Step through the configuration wizard for all BASE version 1 plug-in
553      configurations. You do not need to change any parameters.
554      Just click on the <guibutton>Next</guibutton> button
555      until the configuration is complete.
556      </para>
557    </listitem>
558    </orderedlist>
559  </sect1>
560
561  <sect1 id="appendix.incompatible.2.2">
562    <title>BASE 2.2 release</title>
563   
564    <bridgehead>BASE 1 Plug-in executer</bridgehead>
565   
566    <para>
567      No longer provides a default mapping between BASE version 1 and
568      BASE version 2 raw data columns. To solve this add
569      a <guilabel>Formula</guilabel> item with the same name as the
570      BASE version 1 column name and an expression that picks the BASE
571      version 2 raw data property. For example:
572    </para>
573   
574<literallayout>
575<guilabel>Name</guilabel>          BCh1Mean
576<guilabel>Type</guilabel>          Column expression
577<guilabel>Raw data type</guilabel> GenePix
578<guilabel>Channels</guilabel>      2
579<guilabel>Expressions</guilabel>   1: raw('ch1BgMean')
580</literallayout>
581
582  </sect1>
583
584</appendix>
585
Note: See TracBrowser for help on using the repository browser.