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

Last change on this file since 7681 was 7681, checked in by Nicklas Nordborg, 3 years ago

References #2137: Remove some of the deprecated code

Added a note in the documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 23.1 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 7681 2019-04-04 07:47:05Z 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  <?dbhtml filename="incompatible.html" ?>
29  <title>API changes that may affect backwards compatibility</title>
30  <para>
31    In this document we list all changes to code in the <emphasis>Public API</emphasis>
32    that may be backwards incompatible with existing client applications
33    and or plug-ins. See <xref linkend="base_api.public" /> for more
34    information about what we mean with the <emphasis>Public API</emphasis>
35    and backwards compatible.
36  </para>
38  <sect1 id="appendix.incompatible.3.15">
39    <title>BASE 3.15 release</title>
41    <bridgehead id="appendix.incompatible.secondarystorage">Secondary storage support has been removed</bridgehead>
42    <para>
43      API that is related to the secondary storage feature has been removed. For example,
44      in the <classname docapi="net.sf.basedb.core">File</classname> class, <code>getAction()/setAction()</code>
45      has been removed. In the <classname docapi="net.sf.basedb.core">Location</classname> enumeration,
46      <code>SECONDARY</code> has been removed.   
47    </para>
49    <bridgehead id="appendix.incompatible.spotimages">Spot images support has been removed</bridgehead>
50    <para>
51      API that is related to creating and viewing spot images has been removed. For example,
52      in the <classname docapi="net.sf.basedb.core">RawBioAssay</classname> class, the
53      <code>getSpotImages()</code> method has been removed. The <classname>SpotImages</classname>
54      class has been removed and there are several other minor changes related to this.
55      There is no replacement.
56    </para>
58    <bridgehead id="appendix.incompatible.deprecated">Some deprecated classes and methods has been removed</bridgehead>
59    <para>
60      Classes and methods that has been deprecated since BASE 3.10 or earlier have been removed. This
61      may affect existing plug-ins and extensions. In most cases there exists a replacement method or
62      class as indicated in the BASE 3.14 documentation.
63    </para>
65    <bridgehead id="appendix.incompatible.generics">Introduced generic return parameters</bridgehead>
66    <para>
67      Some API methods with a return type of <classname>Object</classname> have been
68      changed to <code>&lt;T&gt; T</code> (for example <code>public &lt;T&gt; T getObject(String name)</code> in
69      <classname>ItemContext</classname>)
70      which means that no explicit cast is needed since the compiler can typically infer this from the
71      assignment made by the calling code. Note that this change is binary compatible with existing
72      code, but in some cases it may be source code incompatible. Thus, already compiled code
73      should continue to work, but source code may have to modified if compiling against the
74      BASE 3.15 API. Here are some examples:
75    </para>
77    <programlisting language="java">
79// With BASE 3.14 (also works with BASE 3.15)
80ItemContext cc = ...
81Hardware hardware = (Hardware)cc.getObject("item");
83// With BASE 3.15
84Hardware hardware = cc.getObject("item");
86// This will not compile against BASE 3.15!
87Set<AnnotatedItem> items = (Set<AnnotatedItem>)cc.getObject("AnnotatedItems");
89// The explict cast must be removed
90Set<AnnotatedItem> items = cc.getObject("AnnotatedItems");
94    <para>
95      Besides the change in the <methodname>ItemContext.getObject()</methodname> method there
96      are several similar changes in the <classname docapi="net.sf.basedb.core">ItemContext</classname> 
97      class as well as in <classname docapi="net.sf.basedb.core">SessionControl</classname>,
98      <classname docapi="net.sf.basedb.core">Annotation</classname>,
99      <classname docapi="net.sf.basedb.core">AnnotationType</classname>
100      <classname docapi="net.sf.basedb.clients.web.formatter">FormatterFactory</classname>,
101      <classname docapi="net.sf.basedb.core">ParameterValues</classname> and several other
102      classes. In all cases, it should be relatively simple to update the code that doesn't compile.
103    </para>
105    <note>
106      <title>Beware of JSP files</title>
107      <para>
108        Since this change doesn't affect already compiled code, extensions and plug-ins are
109        typically not affected. The exception is of course JSP files that are part of an
110        extension since they are compiled at runtime by Tomcat. It may be wise to test this
111        before upgrading a live BASE installation to BASE 3.15.
112      </para>
113    </note>
114  </sect1>
116  <sect1 id="appendix.incompatible.3.14">
117    <title>BASE 3.14 release</title>
119    <bridgehead id="appendix.incompatible.authenticator">The (very) old Authenticator API has been removed</bridgehead>
120    <para>
121      The <code>net.sf.basedb.core.authentication.Authenticator</code>
122      interface and other related code that was deprecated in BASE 3.3
123      has been removed. Systems that still use old authentication code
124      need to replace this with a newer version before updating.
125    </para>
127  </sect1>
129  <sect1 id="appendix.incompatible.3.11">
130    <title>BASE 3.11 release</title>
132    <bridgehead id="appendix.incompatible.paused-job">Job.Status.PAUSED</bridgehead>
133    <para>
134      Added the <code>PAUSED</code> option to the <code>Job.Status</code>
135      enumeration. This option is used when a running job has been temporarily paused.
136      Code that uses the job's status to decide what action to take may fail since
137      this is a new option. In most cases, it should be handled in the same way as
138      if the job is <code>WAITING</code>.
139    </para>
141    <bridgehead id="appendix.incompatible.sha-256">SHA-256 fingerprint on file servers</bridgehead>
142    <para>
143      Added support for storing SHA-256 fingerprints on file servers. Code
144      that is expecting the fingerprint to always be a MD5 value may stop
145      to work. A new method <code>FileServer.getFingerprintType()</code>
146      has been added.
147    </para>
149    <bridgehead id="appendix.incompatible.inactive-roles">Inactive roles</bridgehead>
150    <para>
151      A new feature which allows a user to activate and de-activate roles on the
152      fly during a login session has been implemented. This may cause a user to
153      gain or lose permissions at any time. A change of active roles triggers an
154      internal reload of permissions and since there are already other things that
155      do this, it should not cause any problems. The <code>SessionControl.getRoles()</code>
156      method has been deprecated and replaced with <code>SessionControl.getAllRoles()</code>,
157      <code>SessionControl.getActiveRoles()</code> and <code>SessionControl.getInactiveRoles()</code>.
158    </para>
160  </sect1>
162  <sect1 id="appendix.incompatible.3.10">
163    <title>BASE 3.10 release</title>
165    <bridgehead id="appendix.incompatible.annotate-permission">Annotate permission</bridgehead>
166    <para>
167      A new permission level, <code>ANNOTATE</code> has been added to
168      the permission system. Extensions and other clients that are not
169      aware of this permission may think that the user only has
170      <code>READ</code> permission.
171    </para>
173    <bridgehead id="appendix.incompatible.project-annotations">Project-specific annotations</bridgehead>
174    <para>
175      The annotation system has been extended with a new feature: project-specific annotations.
176      Extensions and other code that is not aware of this may experience strange behaviour
177      where annotation values may not change as expected or may change in unexpected ways.
178      For example, trying to change the default value of a project-specific annotation when
179      a project is active causes a new annotation to be created in the background instead
180      of changing the current one. Note that this feature is disabled by default and
181      must be enabled per annotation type. Updating an existing server should be safe
182      and will not affect existing annotations or annotation types.
183    </para>
185  </sect1>
187  <sect1 id="appendix.incompatible.3.9">
188    <title>BASE 3.9 release</title>
190    <bridgehead id="appendix.incompatible.session-control">Application.getSessionControl()</bridgehead>
191    <para>
192      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
193      method for getting access to an existing session has been deprecated. A new
194      version has been implemented that require that an <emphasis>external client id</emphasis>
195      is specified. This change was needed to avoid sessions leaking between client
196      applications and prevent users to use an application they don't have permission to use.
197    </para>
199    <para>
200      The deprecated method use the client id from the BASE web client. Extensions and
201      other clients that use a different client id are affected and may stop to work
202      until they have been updated to use the new API. For more information see
203      <ulink url="">ticket 2011</ulink>.
204    </para>
206  </sect1>
209  <sect1 id="appendix.incompatible.3.8">
210    <title>BASE 3.8 release</title>
212    <bridgehead id="appendix.incompatible.service-session-control">ServiceSessionControl API</bridgehead>
213    <para>
214      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for
215      configuration and building Hibernate <classname>SessionFactory</classname>
216      instances has been changed due the Hibernate 5 upgrade. This change affects
217      extensions that use the API for storing their own data inside the BASE database.
218      Extensions that use this API must be updated or they will not work with BASE 3.8.
219    </para>
221  </sect1>
224  <sect1 id="appendix.incompatible.3.6">
225    <title>BASE 3.6 release</title>
227    <bridgehead id="appendix.incompatible.cloned-annotation">Cloned annotations</bridgehead>
228    <para>
229      A new feature that allows an inherited annotation to be cloned has been implemented.
230      Several methods in <classname docapi="net.sf.basedb.core">AnnotationSet</classname>,
231      <classname docapi="net.sf.basedb.core.snapshot">AnnotationSnapshot</classname> and some
232      other classes has been deprecated and replaced with new methods. Existing code that
233      is not aware of cloned annotations should continue to work, but may experience some
234      inconsistent behaviour in case the cloned values are out-of-sync with the original
235      values.
236    </para>
238    <bridgehead id="appendix.incompatible.experimental-factors">Experimental factors have moved</bridgehead>
239    <para>
240      To allow the owner of an experiment to manage experimental factor values as part
241      of the experiment, the <classname docapi="net.sf.basedb.core">RootRawBioassay</classname>
242      item was introduced. The new item is a one-to-one representation of a <classname 
243      docapi="net.sf.basedb.core">RawBioAssay</classname> inside that experiment.
244      Experimental factor values that are found on existing raw bioassays are copied to the
245      root rawbioassays when updating BASE. Changes made after the update will only
246      affect the root raw bioassays. Existing code that is not aware of root raw bioassays
247      may not find the experimental factor values.
248    </para>
250  </sect1>
252  <sect1 id="appendix.incompatible.3.5">
253    <title>BASE 3.5 release</title>
255    <bridgehead id="appendix.incompatible.itemlists">Biomaterial lists has been replaced with item lists</bridgehead>
256    <para>
257      The <classname docapi="net.sf.basedb.core">BioMaterialList</classname> 
258      class has been removed and replaced with <classname 
259      docapi="net.sf.basedb.core">ItemList</classname>. The API is similar
260      but not exactly the same. In most cases only minor changes are required
261      to make existing code work with the new API.
262    </para>
264    <para>
265      Queries that use the <code>BioMaterial.bioMaterialLists</code> association
266      for joining will no longer work. There is no replacement functionality for
267      joining item lists.
268    </para>
270    <para>
271      All classes in the <code>net.sf.basedb.util.biomaterial</code> package has
272      been deprecated. It is recommended that code that uses any of these classes
273      are updated to use classes in <code>net.sf.basedb.util.listable</code> instead.
274      The API is a bit different, but the new implementations typically performs a
275      lot better so it is worth the work.
276    </para>
278    <para>
279      There are several other minor changes in the API that previously worked with
280      the <code>BioMaterialList</code> class that has been removed and replaced
281      with something else.
282    </para>
284  </sect1>
286  <sect1 id="appendix.incompatible.3.4">
287    <title>BASE 3.4 release</title>
289    <bridgehead>Updated JDOM to 2.0</bridgehead>
290    <para>
291      The JDOM library has been updated to version 2.0 from 1.1. The
292      new version is incompatible with the old version. BASE 3.4 will
293      ship with both versions but JDOM 1.1 will be removed in BASE 3.5
294      and so will all API methods that expose JDOM 1.1 classes.
295      It is recommended that plug-ins and extensions that use JDOM also
296      update to JDOM 2.0.
297    </para>
299    <bridgehead>Updated to Apache HttpClient 4.3.4</bridgehead>
300    <para>
301      The Apache HTTP Client library has been updated to version 4.3.4.
302      The new version has deprecated some classes that are exposed through
303      the BASE API (mainly in <classname docapi="net.sf.basedb.util.ssl">SSLUtil</classname>).
304      As a result we had to deprecate parts of the BASE API, which will
305      be removed in BASE 3.5. It is recommended that plug-ins and
306      extensions that are affected are updated to use the replacement API
307      instead.
308    </para>
310  </sect1>
312  <sect1 id="appendix.incompatible.3.3">
313    <title>BASE 3.3 release</title>
315    <bridgehead>Content security policy</bridgehead>
316    <para>
317      The BASE web client now set a rather strict <emphasis>Content
318      Security Policy</emphasis> that prevent browsers from executing
319      code (including JavaScript) that is considered unsafe. Some extensions
320      may cease to work due to this. Go to
321      <menuchoice>
322        <guimenu>Administrate</guimenu>
323        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
324        <guimenuitem>Overview</guimenuitem>
325      </menuchoice> 
326      (after upgrading) to see if there are any warnings about this.
327      Read more in <xref linkend="appendix.web.xml.csp-filter" />
328      for information about how to relax the policy.
329    </para>
331    <bridgehead>Re-factored JavaScript API</bridgehead>
332    <para>
333      The BASE web client has undergone a major refactoring with respect to
334      the JavaScript API that is used on the server. A lot of functions have
335      been replaced with new implementations. We have tried to map the old
336      functions to the new ones, but this has not always been possible. Extentions
337      that use the BASE JavaScript API must be tested with BASE 3.3 to find
338      out if they are still working or if modifications are needed.
339    </para>
341    <note>
342      <title>Avoid in-line event handlers and script</title>
343      <para>
344        The main reason for the refactoring is to get rid of all in-line
345        event handlers and script sections since this is a possible entry
346        point for cross-site scripting attacks (see <ulink 
347          url="">ticket 1712</ulink>).
348        Extension developers are encouraged to make the same changes in
349        their applications.
350      </para>
351    </note>
353    <bridgehead>Biomaterial items are now lazy-loading</bridgehead>
354    <para>
355      For performance reasons biomaterial items have been changed from
356      eager-loading to lazy-loading. This may affect clients and/or plug-ins
357      that expect the parent chain of biomaterials to always be fully initialized
358      without explicitely having told the BASE core to do so.
359    </para>
361    <bridgehead>Tables can have columns with different sort order</bridgehead>
362    <para>
363      A new feature has been implemented which allows columns in a table to
364      have different sort order. This is implemented by allowing '+' or '-'
365      as a prefix to properties returned by the <methodname>ItemContext.getSortProperty()</methodname>
366      method. Properties without a prefix still use the global sort order as returned
367      by <methodname>ItemContext.getSortDirection()</methodname>.
368    </para>
370    <para>
371      Code that is not aware of the prefixes may fail since '+' and '-' are not
372      allowed in property names.
373    </para>
375    <bridgehead>External authentication has been converted to an extension point</bridgehead>
376    <para>
377      External authentication plug-ins using the old system are supported through a
378      wrapper extension, but the recommendation is to update those plug-in to the
379      new system. See <xref linkend="extensions_developer.login-manager" /> for more information.
380    </para>
382    <bridgehead>Setting parameters for a job no longer set it to status=WAITING</bridgehead>
383    <para>
384      Added <methodname>Job.setScheduled()</methodname> to switch the state
385      from <constant>UNCONFIGURED</constant> to <constant>WAITING</constant>.
386      A job can't be executed before it has entered the <constant>WAITING</constant>
387      state. The change makes it possible to register a job and some parameters for
388      it and remain in the <constant>UNCONFIGURED</constant> state.
389    </para>
391  </sect1>
393  <sect1 id="appendix.incompatible.3.2">
394    <title>BASE 3.2 release</title>
396    <bridgehead>Derived bioassays can now have multiple parents</bridgehead>
397    <para>
398      Before BASE 3.2 a derived bioassay was restricted to a single parent
399      item. This affects the API and the <methodname>DerivedBioAssay.getParent()</methodname>
400      and <methodname>DerivedBioAssay.getPhysicalBioAssays()</methodname> now always
401      return null. Existing code should be updated to use <methodname>getPhysicalBioAssays()</methodname>
402      and <methodname>getParents()</methodname> (which return <classname>ItemQuery</classname> instances)
403      instead. Code that is using queries to filter or sort on parent items must also be
404      updated since the association names have changed.
405    </para>
407    <bridgehead>BASEfile exporter automatically closes the output stream</bridgehead>
408    <para>
409      The implementation of the BASEfile exporter has been changed to
410      automatically close the provided output stream when the export
411      is complete. Clients that need the old behavior should call
412      <code>BaseFileExporter.setAutoCloseWriters(false)</code> before
413      using it.
414    </para>
416    <bridgehead>Change history logging is now an extension point</bridgehead>
417    <para>
418      The change history logging has been converted to an extension point.
419      The <constant>changelog.factory</constant> setting in <filename>base.config</filename>
420      is no longer used. Existing logging implementations should be updated
421      to use the extension system. See <xref linkend="extensions_developer.logging" />.
422      A temporary solution is to use one of the debugging action factories to
423      define the extension point:
424    </para>
426    <programlisting language="xml">
429   id="id-of-custom-log-manager"
430   extends="net.sf.basedb.core.log-manager"
431   >
432   <about>
433      <name>My custom log manager</name>
434      <description>
435         Temporary solution to allow the old log manager to work with the extension system.
436      </description>
437   </about>
438   <index>1</index>
439   <action-factory>
440      <factory-class>net.sf.basedb.util.extensions.debug.BeanActionFactory</factory-class>
441      <parameters>
442         <beanClass>my.custom.LogmangerClass</beanClass>
443      </parameters>
444   </action-factory>
449  </sect1>
451  <sect1 id="appendix.incompatible.3.1">
452    <title>BASE 3.1 release</title>
454    <bridgehead>Web service framework updated to Axis2 1.6</bridgehead>
455    <para>
456      We have updated the web services framework to Axis2 1.6. Clients
457      that use earlier Axis2 versions may not work when connecting to a
458      BASE 3.1 server. Unfortunately, clients that use the Axis2 1.6
459      framework may have problems connecting to BASE 3.0 servers so it
460      may be difficult to implement support for both BASE 3.0 and BASE 3.1
461      in a single client application.
462    </para>
464    <bridgehead>New GUI look and feel</bridgehead>
465    <para>
466      Taglibs, stylesheets and javscript functions have been changed
467      to create a new look and feel. Plug-ins and extensions that uses
468      GUI elements from the core BASE installation may need to be updated
469      for the best user experience. The changes are too numerous so we can't
470      list them here. Please use the developers mailing list if specific
471      information is needed or see <ulink url="">ticket
472      1655</ulink> for some screenshots and other information.
473    </para>
475    <bridgehead>Per-experiment copy of reporter annotations</bridgehead>
476    <para>
477      A new feature has been implemented that allows a user to make a
478      local copy of reporter annotations for reporters that are used
479      in an experiment. The existing API will by default use the local
480      copy if one is available. It is possible to use the master reporter
481      annotations by invoking certain API methods (for example:
482      <code>DynamicQuery.setUseClonedReporters(false)</code>). Since the copy
483      may include only a subset of the available reporter annotations this
484      may cause problems for code that is expecting all annotations to be
485      available. See <classname docapi="net.sf.basedb.core">ReporterCloneTemplate</classname>
486      and <ulink url="">ticket 1616</ulink>
487      for more information.
488    </para>
490    <bridgehead>Annotations can be inherited/pushed from child to parent item</bridgehead>
491    <para>
492      A new feature has been implemented that allows an item to "push" annotations
493      up to it's parent in addition to the normal "inherit to child" method.
494      This has been implemented as a change in the <methodname>getAnnotatableParents()</methodname>
495      method defined by the <interfacename docapi="net.sf.basedb.core">Annotatable</interfacename>
496      interface. This may cause unexpected issues with code that is not prepared to handle
497      this situation. Particulary, infinite loops must be avoided when traversing the "parent"
498      tree of an item (but this should already be in place since it can already happen due to
499      mistakes when creating items). See <ulink url="">ticket 1605</ulink>
500      for more information.
501    </para>
503  </sect1>
506  <sect1 id="appendix.incompatible.3.0">
507    <title>BASE 3.0 release</title>
509    <para>
510      There are a lot incompatible changes between BASE 3 and any of the BASE 2.x
511      versions. We do not list list those changes here since we do not expect existing
512      plug-ins, extensions or other client application to work with BASE 3 without
513      modification. See <xref linkend="migrate_2_3" /> for more information.
514    </para>
515  </sect1>
517  <sect1 id="appendix.incompatible.2.x">
518    <title>All BASE 2.x releases</title>
520    <para>
521      The list of changes made in the various BASE 2.x releases can be found
522      in the <ulink url=""
523      >BASE 2.17 documentation</ulink>.
524    </para>
526  </sect1>
Note: See TracBrowser for help on using the repository browser.