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

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

Fixes #1350: Update to Hibernate 3.3.2

Updated documentation.

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