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

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

References #108: Logging the change history of an item

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