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

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

Fixes #868: Support for chips with multiple arrays

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 14.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 4131 2008-02-08 08:55:48Z 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  </sect1> 
138  <sect1 id="appendix.incompatible.2.5">
139    <title>BASE 2.5 release</title>
141    <bridgehead>Raw data types</bridgehead>
142    <para>
143      The <sgmltag class="attribute">storage</sgmltag> attribute of the
144      <sgmltag class="starttag">raw-data-type</sgmltag> has been deprecated
145      for the <filename>raw-data-types.xml</filename> file. BASE will refuse
146      to start if it finds this attribute. Raw data types which doesn't use
147      the database for storing data should be registered as <classname docapi="net.sf.basedb.core">Platform</classname>:s
148      instead.
149    </para>
151    <para>
152      Applications or plug-ins that filters on the <property>rawDataType</property>
153      property for <classname docapi="net.sf.basedb.core">RawBioAssay</classname> or <classname docapi="net.sf.basedb.core">Experiment</classname>
154      may need to change. The ID given to raw data types that doesn't use the
155      database for storing data are prefixed with "<constant>platform.</constant>".
156      The ID for the Affymetrix platform has changed from <constant>affymetrix</constant>
157      to <constant>platform.affymetrix</constant>.
158    </para>
160    <bridgehead>Raw bioassays</bridgehead>
161    <para>
162      The property <property>spots</property> which used to hold the number
163      of spots in the database OR in the file(s) has been split into two
164      properties:
165    </para>
166    <itemizedlist>
167    <listitem>
168      <para>
169      <property>spots</property>: Now only holds the number of database spots
170      </para>
171    </listitem>
172    <listitem>
173      <para>
174      <property>numFileSpots</property>: Holds the number of spots that are stored in files
175      </para>
176    </listitem>
177    </itemizedlist>
179    <para>
180      Applications or plug-ins that filters on the <property>spots</property> property
181      may no longer work as expected for file-only platforms, since this value is now
182      always 0. They should use the <property>numFileSpots</property> property instead.
183    </para>
185    <bridgehead>Array designs</bridgehead>
186    <para>
187      The <methodname>ArrayDesign.isAffyChip()</methodname> method has
188      been deprecated. Applications or plug-ins that filter on the <property>affyChip</property>
189      property may no longer work as expected. The applications should
190      instead filter on the <property>platform.externalId</property> and
191      look for the value given by the constant <constant>Platform.AFFYMETRIX</constant>.
192    </para>
194    <programlisting language="java">
195// This may no longer work
197   Restrictions.eq(
199      Expressions.parameter("affyChip", true, Type.BOOLEAN)
200   )
203// Use this instead
205   Restrictions.eq(
207      Expressions.string(Platform.AFFYMETRIX)
208   )
213  </sect1>
215  <sect1 id="appendix.incompatible.2.4">
216    <title>BASE 2.4 release</title>
218    <bridgehead>Plug-in API</bridgehead>
219    <para>
220      The <methodname>InteractivePlugin.isInContext()</methodname>
221      method may now throw exceptions to indicate error-level
222      messages. Messages that are returned by the method are
223      considered as a warning message and are by default no longer
224      shown to the users.
225      See <xref linkend="plugin_developer.api.interfaces.interactive" />
226      and <xref linkend="webclient.configuration.preferences.plugins" />.
227    </para>
229    <bridgehead>Custom JSP pages for plug-ins</bridgehead>
230    <para>
231      Plug-ins using custom JSP pages for parameter input are recommended
232      to pass along the <varname>requestId</varname> parameter. The parameter
233      is optional, but if used it will prevent data from two different
234      plug-ins configurations to get mixed up. See
235      <xref linkend="plugin_developer.api.jspparameters" />.
236    </para>
238    <bridgehead>JEP parser</bridgehead>
239    <para>
240      The <methodname>Jep.nodeToExpression()</methodname>
241      and <methodname>Jep.nodeToString()</methodname> methods
242      return <constant>NULL</constant> if they find an unqouted
243      <constant>NULL</constant> string in the expression. This
244      allows JEP to convert expressions like <code>ch(1) == NULL</code>
245      into a Query API expression testing for null. To get the
246      old behaviour use <code>ch(1) == 'NULL'</code>.
247    </para>
249    <bridgehead>Parsing strings into numeric values</bridgehead>
250    <para>
251      The <methodname>Type.parseString(String)</methodname> method for
252      <constant>Type.FLOAT</constant> and <constant>Type.DOUBLE</constant>
253      has changed it's behaviour for <constant>NaN</constant>
254      and <constant>Infinity</constant> values. The methods used to
255      return <constant>Float.NaN</constant>, <constant>Float.NEGATIVE_INFINITY</constant>,
256      <constant>Float.POSITIVE_INFINITY</constant> or the corresponding
257      <classname>Double</classname> values. Since databases doesn't like
258      these special values and eventually most values will go into the database,
259      the <methodname>parseString</methodname> method now returns <constant>null</constant> 
260      instead.
261    </para>
263    <bridgehead>Extended properties and raw data types</bridgehead>
264    <para>
265      We have added validation code to check for invalid values. If you
266      have modified the <filename>extended-properties.xml</filename>
267      or the <filename>raw-data-types.xml</filename> file and they
268      contain invalid values, you may not be able to start BASE until
269      they are fixed. The validation is rather strict and things that may
270      have worked before (because you were lucky or the because the database
271      has been forgiving) may no longer work. Here is an overview of the most
272      important validation rules:
273    </para>
275    <itemizedlist>
276    <listitem>
277      <para>
278      Names and identifiers for extended properties and raw data type
279      can only contain letters, digits and underscores. They must not
280      start with a digit.
281      </para>
282    </listitem>
283    <listitem>
284      <para>
285      Names of database tables and columns can only contain letters,
286      digits and underscores. They must not start with a digit.
287      </para>
288    </listitem>
289    <listitem>
290      <para>
291      There mustn't be any duplicate tables, columns, properties, etc.
292      for a given context. For example, no duplicate tables in the
293      database, no duplicate columns in a table, and no duplicate
294      properties for a raw data type.
295      </para>
296    </listitem>
297    </itemizedlist>
299  </sect1>
301  <sect1 id="appendix.incompatible.2.3">
302    <title>BASE 2.3 release</title>
304    <bridgehead>FlatFileParser</bridgehead>
305    <para>
306      The <methodname>hasMoreData()</methodname> method has changed the
307      order of checks made to determine the line type. The checks are
308      now made in the following order:
310      <orderedlist>
311      <listitem>
312        <para>
313        Check if the line should be ignored.
314        </para>
315      </listitem>
316      <listitem>
317        <para>
318        Check if the line is a data footer.
319        </para>
320      </listitem>
321      <listitem>
322        <para>
323        Check if the line is the start of a new section.
324        </para>
325      </listitem>
326      <listitem>
327        <para>
328        Check if the line is a data line.
329        </para>
330      </listitem>
331      </orderedlist>
332      The data line check has been moved to the last since it was difficult
333      to create settings that made sure section and data footer lines where
334      matched correctly.
335    </para>
337    <bridgehead>BASE 1 Plug-in executer</bridgehead>
339    <para>
340      Changed to store information about plug-in parameters as XML in the
341      database instead of in the orignal BASE 1 plug-in definition file.
342      Existing BASE 1 plug-ins must be re-configured before they can be
343      used. To do this:
344    </para>
346    <orderedlist>
347    <listitem>
348      <para>
349      Go to
350      <menuchoice>
351        <guimenu>Administrate</guimenu>
352        <guisubmenu>Plugins</guisubmenu>
353        <guimenuitem>Configurations</guimenuitem>
354      </menuchoice>
355      </para>
356    </listitem>
357    <listitem>
358      <para>
359      Step through the configuration wizard for all BASE 1 plug-in
360      configurations. You do not need to change any parameters.
361      Just click on the <guibutton>Next</guibutton> button
362      until the configuration is complete.
363      </para>
364    </listitem>
365    </orderedlist>
366  </sect1>
368  <sect1 id="appendix.incompatible.2.2">
369    <title>BASE 2.2 release</title>
371    <bridgehead>BASE 1 Plug-in executer</bridgehead>
373    <para>
374      No longer provides a default mapping between BASE 1 and BASE 2
375      raw data columns. To solve this add a <guilabel>Formula</guilabel>
376      item with the same name as the BASE 1 column name and an expression
377      that picks the BASE 2 raw data property. For example:
378    </para>
381<guilabel>Name</guilabel>          BCh1Mean
382<guilabel>Type</guilabel>          Column expression
383<guilabel>Raw data type</guilabel> GenePix
384<guilabel>Channels</guilabel>      2
385<guilabel>Expressions</guilabel>   1: raw('ch1BgMean')
388  </sect1>
Note: See TracBrowser for help on using the repository browser.