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

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

Fixes #1269: Biomaterial batch importers should use alphanumeric coordinate system for wells

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