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

Last change on this file since 4135 was 4135, checked in by Nicklas Nordborg, 15 years ago

Fixes #868: Support for chips with multiple arrays

Found an incompatibility issue in the web client

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 15.5 KB
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">
6  $Id: incompatible.xml 4135 2008-02-08 14:03:25Z nicklas $
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg
10  This file is part of BASE - BioArray Software Environment.
11  Available at
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 2
16  of the License, or (at your option) any later version.
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  GNU General Public License for more details.
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
29<appendix id="appendix.incompatible">
30  <title>API changes that may affect backwards compatibility</title>
31  <para>
32    In this document we list all changes to code in the <emphasis>Public API</emphasis>
33    that may be backwards incompatible with existing client applications
34    and or plug-ins. See <xref linkend="api_overview.public_api" /> for more
35    information about what we mean with the <emphasis>Public API</emphasis>
36    and backwards compatible.
37  </para>
39  <note>
40    <para>
41    There is no history for releases prior to BASE 2.2 because
42    we did not actively keep track of them. We believe that if such
43    changes exists, they are minor and does not affect many plug-ins
44    since in those days very few 3rd-party plug-ins existed.
45    </para>
46  </note>
48  <sect1 id="appendix.incompatible.2.6">
49    <title>BASE 2.6 release</title>
51    <bridgehead>Feature identification methods</bridgehead>
52    <para>
53      Array design features can now be identified by three different methods:
54      COORDINATES, POSITION and FEATURE_ID. The coordinates method was the
55      only one supported earlier.
56    </para>
58    <itemizedlist>
59    <listitem>
60      <para>
61      Client and plug-in code that depends on features having unique COORDINATES
62      may no longer work if used with an array design using a different identification method.
63      Code that is, directly or indirectly, using a
64      <classname docapi="net.sf.basedb.core">FeatureBatcher</classname> or
65      <classname docapi="net.sf.basedb.core">RawDataBatcher</classname> are
66      probably affected by this. For example, a raw data importer which
67      doesn't know how to set the position or the feature ID can't import data to
68      an array design that is using one of the new identification methods.
69      </para>
70    </listitem>
72    <listitem>
73      <para>
74      The POSITION identification method will require a unqiue position number.
75      This value used to be an auto-generated sequence starting at 1. The other
76      identification methods will still do that, but when using the POSITION identification
77      method the only requirement is that the position value is a unique positive integer.
78      Client or plug-in code that depends on the position beeing a number between
79      1 and the number of features may fail if used with an array design using
80      the POSITION identification method.
81      </para>
82    </listitem>   
83    </itemizedlist>
85    <bridgehead>Data file types</bridgehead>
86    <para>
87      The <methodname>DataFileType.setValidatorClass()</methodname> and
88      <methodname>DataFileType.setMetadataReaderClass()</methodname> no longer
89      verifies that the specified class names exists and implements the required interfaces.
90      This validation will instead happen at commit time. The reason for this change is
91      the added support for having the validator/meta data reader in external JAR files.
92      This means that the validation can't happen until both the class names and JAR paths
93      has been set. If a client application need validation before commit time it should use
94      <methodname>DataFileType.getValidator()</methodname> and
95      <methodname>DataFileType.getMetadataReader()</methodname> after the class names and JAR
96      paths has been set.
97    </para>
99    <bridgehead>Job.Status.ABORTING</bridgehead>
100    <para>
101      Added the <constant>ABORTING</constant> option to the <classname>Job.Status</classname>
102      enumeration. This option is used when the <constant>ABORT</constant> signal has been
103      sent to an executing job, but the job has not yet responded to it.
104      Code that uses the job's status to decide what action to take may fail
105      since this is a new option. In most cases, it should be handled in the same way
106      as if the job is <constant>EXECUTING</constant>.
107    </para>
109    <bridgehead>Hybridization to Labeled extracts link</bridgehead>
110    <para>
111      This link can now hold information about which sub-array a labeled
112      extract belongs to on a multi-array hybridization. Code that is
113      unaware of the concept of sub-arrays may find hybridizations
114      where the number of labeled extracts doesn't match the number
115      channels in the platform used, and that more than one labeled
116      extract has the same label. This was previously considered as
117      an error condition by the experiment validator. With the
118      new scheme the validation has to be done on a sub-array basis instead
119      of on the complete hybridization.
120    </para>
122    <para>
123      A similar issue arises when inheriting annotations to a raw bioassay
124      which stems from a specific sub-array on a mutli-array hybridization.
125      This raw bioassay should only inherit annotations from the labeled
126      extracts that are part of the same sub-array. For API compatibility
127      reasons the <methodname>Hybridization.getAnnotatableParents()</methodname>
128      will still return <emphasis>all</emphasis> labeled extracts. Code
129      that is calling this method in order to find the parents to
130      a raw bioassay should instead call the new method,
131      <methodname>Hybridizations.getAnnotatableParents(int)</methodname>,
132      where the <code>int</code> is the sub-array index value for
133      the raw bioassay.
134    </para>
136    <para>
137      A related issue ariese when querying labeled extracts and joining
138      the source events collection to use the linked hybridizations in
139      the query. Here is an example:
140    </para>
142    <programlisting language="java">
144// Find all labeled extracts on a given hybridization
145Hybridization current = ...
146ItemQuery<LabeledExtract> labeledExtractQuery = LabeledExtract.getQuery();
148// This no longer works
149// labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "evt"));
151// Replace the above line with these two line
152labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "srcevt"));
153labeledExtractQuery.join(Hql.innerJoin("srcevt", "event", "evt"));
156  Restrictions.eq(
157"evt", "hybridization"),
158    Expressions.integer(current.getId())
159  )
164    <para>
165      The good new is that the modifcations makes it possible to filter
166      the query on used quantity and sub-array. See the javadoc for
167      <classname docapi="net.sf.basedb.core">Hybridization</classname>
168      to get more information.
169    </para>
171  </sect1> 
173  <sect1 id="appendix.incompatible.2.5">
174    <title>BASE 2.5 release</title>
176    <bridgehead>Raw data types</bridgehead>
177    <para>
178      The <sgmltag class="attribute">storage</sgmltag> attribute of the
179      <sgmltag class="starttag">raw-data-type</sgmltag> has been deprecated
180      for the <filename>raw-data-types.xml</filename> file. BASE will refuse
181      to start if it finds this attribute. Raw data types which doesn't use
182      the database for storing data should be registered as <classname docapi="net.sf.basedb.core">Platform</classname>:s
183      instead.
184    </para>
186    <para>
187      Applications or plug-ins that filters on the <property>rawDataType</property>
188      property for <classname docapi="net.sf.basedb.core">RawBioAssay</classname> or <classname docapi="net.sf.basedb.core">Experiment</classname>
189      may need to change. The ID given to raw data types that doesn't use the
190      database for storing data are prefixed with "<constant>platform.</constant>".
191      The ID for the Affymetrix platform has changed from <constant>affymetrix</constant>
192      to <constant>platform.affymetrix</constant>.
193    </para>
195    <bridgehead>Raw bioassays</bridgehead>
196    <para>
197      The property <property>spots</property> which used to hold the number
198      of spots in the database OR in the file(s) has been split into two
199      properties:
200    </para>
201    <itemizedlist>
202    <listitem>
203      <para>
204      <property>spots</property>: Now only holds the number of database spots
205      </para>
206    </listitem>
207    <listitem>
208      <para>
209      <property>numFileSpots</property>: Holds the number of spots that are stored in files
210      </para>
211    </listitem>
212    </itemizedlist>
214    <para>
215      Applications or plug-ins that filters on the <property>spots</property> property
216      may no longer work as expected for file-only platforms, since this value is now
217      always 0. They should use the <property>numFileSpots</property> property instead.
218    </para>
220    <bridgehead>Array designs</bridgehead>
221    <para>
222      The <methodname>ArrayDesign.isAffyChip()</methodname> method has
223      been deprecated. Applications or plug-ins that filter on the <property>affyChip</property>
224      property may no longer work as expected. The applications should
225      instead filter on the <property>platform.externalId</property> and
226      look for the value given by the constant <constant>Platform.AFFYMETRIX</constant>.
227    </para>
229    <programlisting language="java">
230// This may no longer work
232   Restrictions.eq(
234      Expressions.parameter("affyChip", true, Type.BOOLEAN)
235   )
238// Use this instead
240   Restrictions.eq(
242      Expressions.string(Platform.AFFYMETRIX)
243   )
248  </sect1>
250  <sect1 id="appendix.incompatible.2.4">
251    <title>BASE 2.4 release</title>
253    <bridgehead>Plug-in API</bridgehead>
254    <para>
255      The <methodname>InteractivePlugin.isInContext()</methodname>
256      method may now throw exceptions to indicate error-level
257      messages. Messages that are returned by the method are
258      considered as a warning message and are by default no longer
259      shown to the users.
260      See <xref linkend="plugin_developer.api.interfaces.interactive" />
261      and <xref linkend="webclient.configuration.preferences.plugins" />.
262    </para>
264    <bridgehead>Custom JSP pages for plug-ins</bridgehead>
265    <para>
266      Plug-ins using custom JSP pages for parameter input are recommended
267      to pass along the <varname>requestId</varname> parameter. The parameter
268      is optional, but if used it will prevent data from two different
269      plug-ins configurations to get mixed up. See
270      <xref linkend="plugin_developer.api.jspparameters" />.
271    </para>
273    <bridgehead>JEP parser</bridgehead>
274    <para>
275      The <methodname>Jep.nodeToExpression()</methodname>
276      and <methodname>Jep.nodeToString()</methodname> methods
277      return <constant>NULL</constant> if they find an unqouted
278      <constant>NULL</constant> string in the expression. This
279      allows JEP to convert expressions like <code>ch(1) == NULL</code>
280      into a Query API expression testing for null. To get the
281      old behaviour use <code>ch(1) == 'NULL'</code>.
282    </para>
284    <bridgehead>Parsing strings into numeric values</bridgehead>
285    <para>
286      The <methodname>Type.parseString(String)</methodname> method for
287      <constant>Type.FLOAT</constant> and <constant>Type.DOUBLE</constant>
288      has changed it's behaviour for <constant>NaN</constant>
289      and <constant>Infinity</constant> values. The methods used to
290      return <constant>Float.NaN</constant>, <constant>Float.NEGATIVE_INFINITY</constant>,
291      <constant>Float.POSITIVE_INFINITY</constant> or the corresponding
292      <classname>Double</classname> values. Since databases doesn't like
293      these special values and eventually most values will go into the database,
294      the <methodname>parseString</methodname> method now returns <constant>null</constant> 
295      instead.
296    </para>
298    <bridgehead>Extended properties and raw data types</bridgehead>
299    <para>
300      We have added validation code to check for invalid values. If you
301      have modified the <filename>extended-properties.xml</filename>
302      or the <filename>raw-data-types.xml</filename> file and they
303      contain invalid values, you may not be able to start BASE until
304      they are fixed. The validation is rather strict and things that may
305      have worked before (because you were lucky or the because the database
306      has been forgiving) may no longer work. Here is an overview of the most
307      important validation rules:
308    </para>
310    <itemizedlist>
311    <listitem>
312      <para>
313      Names and identifiers for extended properties and raw data type
314      can only contain letters, digits and underscores. They must not
315      start with a digit.
316      </para>
317    </listitem>
318    <listitem>
319      <para>
320      Names of database tables and columns can only contain letters,
321      digits and underscores. They must not start with a digit.
322      </para>
323    </listitem>
324    <listitem>
325      <para>
326      There mustn't be any duplicate tables, columns, properties, etc.
327      for a given context. For example, no duplicate tables in the
328      database, no duplicate columns in a table, and no duplicate
329      properties for a raw data type.
330      </para>
331    </listitem>
332    </itemizedlist>
334  </sect1>
336  <sect1 id="appendix.incompatible.2.3">
337    <title>BASE 2.3 release</title>
339    <bridgehead>FlatFileParser</bridgehead>
340    <para>
341      The <methodname>hasMoreData()</methodname> method has changed the
342      order of checks made to determine the line type. The checks are
343      now made in the following order:
345      <orderedlist>
346      <listitem>
347        <para>
348        Check if the line should be ignored.
349        </para>
350      </listitem>
351      <listitem>
352        <para>
353        Check if the line is a data footer.
354        </para>
355      </listitem>
356      <listitem>
357        <para>
358        Check if the line is the start of a new section.
359        </para>
360      </listitem>
361      <listitem>
362        <para>
363        Check if the line is a data line.
364        </para>
365      </listitem>
366      </orderedlist>
367      The data line check has been moved to the last since it was difficult
368      to create settings that made sure section and data footer lines where
369      matched correctly.
370    </para>
372    <bridgehead>BASE 1 Plug-in executer</bridgehead>
374    <para>
375      Changed to store information about plug-in parameters as XML in the
376      database instead of in the orignal BASE 1 plug-in definition file.
377      Existing BASE 1 plug-ins must be re-configured before they can be
378      used. To do this:
379    </para>
381    <orderedlist>
382    <listitem>
383      <para>
384      Go to
385      <menuchoice>
386        <guimenu>Administrate</guimenu>
387        <guisubmenu>Plugins</guisubmenu>
388        <guimenuitem>Configurations</guimenuitem>
389      </menuchoice>
390      </para>
391    </listitem>
392    <listitem>
393      <para>
394      Step through the configuration wizard for all BASE 1 plug-in
395      configurations. You do not need to change any parameters.
396      Just click on the <guibutton>Next</guibutton> button
397      until the configuration is complete.
398      </para>
399    </listitem>
400    </orderedlist>
401  </sect1>
403  <sect1 id="appendix.incompatible.2.2">
404    <title>BASE 2.2 release</title>
406    <bridgehead>BASE 1 Plug-in executer</bridgehead>
408    <para>
409      No longer provides a default mapping between BASE 1 and BASE 2
410      raw data columns. To solve this add a <guilabel>Formula</guilabel>
411      item with the same name as the BASE 1 column name and an expression
412      that picks the BASE 2 raw data property. For example:
413    </para>
416<guilabel>Name</guilabel>          BCh1Mean
417<guilabel>Type</guilabel>          Column expression
418<guilabel>Raw data type</guilabel> GenePix
419<guilabel>Channels</guilabel>      2
420<guilabel>Expressions</guilabel>   1: raw('ch1BgMean')
423  </sect1>
Note: See TracBrowser for help on using the repository browser.