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

Last change on this file since 6480 was 6480, checked in by Nicklas Nordborg, 7 years ago

References #1809: Upgrade 3-rd party libraries

Added notes about JDOM and Apache HTTP Client update/deprecation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 11.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 6480 2014-06-12 12:19:59Z 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.4">
39    <title>BASE 3.4 release</title>
41    <bridgehead>Updated JDOM to 2.0</bridgehead>
42    <para>
43      The JDOM library has been updated to version 2.0 from 1.1. The
44      new version is incompatible with the old version. BASE 3.4 will
45      ship with both versions but JDOM 1.1 will be removed in BASE 3.5
46      and so will all API methods that expose JDOM 1.1 classes.
47      It is recommended that plug-ins and extensions that use JDOM also
48      update to JDOM 2.0.
49    </para>
51    <bridgehead>Updated to Apache HttpClient 4.3.4</bridgehead>
52    <para>
53      The Apache HTTP Client library has been updated to version 4.3.4.
54      The new version has deprecated some classes that are exposed through
55      the BASE API (mainly in <classname docapi="net.sf.basedb.util.ssl">SSLUtil</classname>).
56      As a result we had to deprecate parts of the BASE API, which will
57      be removed in BASE 3.5. It is recommended that plug-ins and
58      extensions that are affected are updated to use the replacement API
59      instead.
60    </para>
62  </sect1>
64  <sect1 id="appendix.incompatible.3.3">
65    <title>BASE 3.3 release</title>
67    <bridgehead>Content security policy</bridgehead>
68    <para>
69      The BASE web client now set a rather strict <emphasis>Content
70      Security Policy</emphasis> that prevent browsers from executing
71      code (including JavaScript) that is considered unsafe. Some extensions
72      may cease to work due to this. Go to
73      <menuchoice>
74        <guimenu>Administrate</guimenu>
75        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
76        <guimenuitem>Overview</guimenuitem>
77      </menuchoice> 
78      (after upgrading) to see if there are any warnings about this.
79      Read more in <xref linkend="appendix.web.xml.csp-filter" />
80      for information about how to relax the policy.
81    </para>
83    <bridgehead>Re-factored JavaScript API</bridgehead>
84    <para>
85      The BASE web client has undergone a major refactoring with respect to
86      the JavaScript API that is used on the server. A lot of functions have
87      been replaced with new implementations. We have tried to map the old
88      functions to the new ones, but this has not always been possible. Extentions
89      that use the BASE JavaScript API must be tested with BASE 3.3 to find
90      out if they are still working or if modifications are needed.
91    </para>
93    <note>
94      <title>Avoid in-line event handlers and script</title>
95      <para>
96        The main reason for the refactoring is to get rid of all in-line
97        event handlers and script sections since this is a possible entry
98        point for cross-site scripting attacks (see <ulink 
99          url="">ticket 1712</ulink>).
100        Extension developers are encouraged to make the same changes in
101        their applications.
102      </para>
103    </note>
105    <bridgehead>Biomaterial items are now lazy-loading</bridgehead>
106    <para>
107      For performance reasons biomaterial items have been changed from
108      eager-loading to lazy-loading. This may affect clients and/or plug-ins
109      that expect the parent chain of biomaterials to always be fully initialized
110      without explicitely having told the BASE core to do so.
111    </para>
113    <bridgehead>Tables can have columns with different sort order</bridgehead>
114    <para>
115      A new feature has been implemented which allows columns in a table to
116      have different sort order. This is implemented by allowing '+' or '-'
117      as a prefix to properties returned by the <methodname>ItemContext.getSortProperty()</methodname>
118      method. Properties without a prefix still use the global sort order as returned
119      by <methodname>ItemContext.getSortDirection()</methodname>.
120    </para>
122    <para>
123      Code that is not aware of the prefixes may fail since '+' and '-' are not
124      allowed in property names.
125    </para>
127    <bridgehead>External authentication has been converted to an extension point</bridgehead>
128    <para>
129      External authentication plug-ins using the old system are supported through a
130      wrapper extension, but the recommendation is to update those plug-in to the
131      new system. See <xref linkend="extensions_developer.login-manager" /> for more information.
132    </para>
134    <bridgehead>Setting parameters for a job no longer set it to status=WAITING</bridgehead>
135    <para>
136      Added <methodname>Job.setScheduled()</methodname> to switch the state
137      from <constant>UNCONFIGURED</constant> to <constant>WAITING</constant>.
138      A job can't be executed before it has entered the <constant>WAITING</constant>
139      state. The change makes it possible to register a job and some parameters for
140      it and remain in the <constant>UNCONFIGURED</constant> state.
141    </para>
143  </sect1>
145  <sect1 id="appendix.incompatible.3.2">
146    <title>BASE 3.2 release</title>
148    <bridgehead>Derived bioassays can now have multiple parents</bridgehead>
149    <para>
150      Before BASE 3.2 a derived bioassay was restricted to a single parent
151      item. This affects the API and the <methodname>DerivedBioAssay.getParent()</methodname>
152      and <methodname>DerivedBioAssay.getPhysicalBioAssays()</methodname> now always
153      return null. Existing code should be updated to use <methodname>getPhysicalBioAssays()</methodname>
154      and <methodname>getParents()</methodname> (which return <classname>ItemQuery</classname> instances)
155      instead. Code that is using queries to filter or sort on parent items must also be
156      updated since the association names have changed.
157    </para>
159    <bridgehead>BASEfile exporter automatically closes the output stream</bridgehead>
160    <para>
161      The implementation of the BASEfile exporter has been changed to
162      automatically close the provided output stream when the export
163      is complete. Clients that need the old behavior should call
164      <code>BaseFileExporter.setAutoCloseWriters(false)</code> before
165      using it.
166    </para>
168    <bridgehead>Change history logging is now an extension point</bridgehead>
169    <para>
170      The change history logging has been converted to an extension point.
171      The <constant>changelog.factory</constant> setting in <filename>base.config</filename>
172      is no longer used. Existing logging implementations should be updated
173      to use the extension system. See <xref linkend="extensions_developer.logging" />.
174      A temporary solution is to use one of the debugging action factories to
175      define the extension point:
176    </para>
178    <programlisting language="xml">
181   id="id-of-custom-log-manager"
182   extends="net.sf.basedb.core.log-manager"
183   >
184   <about>
185      <name>My custom log manager</name>
186      <description>
187         Temporary solution to allow the old log manager to work with the extension system.
188      </description>
189   </about>
190   <index>1</index>
191   <action-factory>
192      <factory-class>net.sf.basedb.util.extensions.debug.BeanActionFactory</factory-class>
193      <parameters>
194         <beanClass>my.custom.LogmangerClass</beanClass>
195      </parameters>
196   </action-factory>
201  </sect1>
203  <sect1 id="appendix.incompatible.3.1">
204    <title>BASE 3.1 release</title>
206    <bridgehead>Web service framework updated to Axis2 1.6</bridgehead>
207    <para>
208      We have updated the web services framework to Axis2 1.6. Clients
209      that use earlier Axis2 versions may not work when connecting to a
210      BASE 3.1 server. Unfortunately, clients that use the Axis2 1.6
211      framework may have problems connecting to BASE 3.0 servers so it
212      may be difficult to implement support for both BASE 3.0 and BASE 3.1
213      in a single client application.
214    </para>
216    <bridgehead>New GUI look and feel</bridgehead>
217    <para>
218      Taglibs, stylesheets and javscript functions have been changed
219      to create a new look and feel. Plug-ins and extensions that uses
220      GUI elements from the core BASE installation may need to be updated
221      for the best user experience. The changes are too numerous so we can't
222      list them here. Please use the developers mailing list if specific
223      information is needed or see <ulink url="">ticket
224      1655</ulink> for some screenshots and other information.
225    </para>
227    <bridgehead>Per-experiment copy of reporter annotations</bridgehead>
228    <para>
229      A new feature has been implemented that allows a user to make a
230      local copy of reporter annotations for reporters that are used
231      in an experiment. The existing API will by default use the local
232      copy if one is available. It is possible to use the master reporter
233      annotations by invoking certain API methods (for example:
234      <code>DynamicQuery.setUseClonedReporters(false)</code>). Since the copy
235      may include only a subset of the available reporter annotations this
236      may cause problems for code that is expecting all annotations to be
237      available. See <classname docapi="net.sf.basedb.core">ReporterCloneTemplate</classname>
238      and <ulink url="">ticket 1616</ulink>
239      for more information.
240    </para>
242    <bridgehead>Annotations can be inherited/pushed from child to parent item</bridgehead>
243    <para>
244      A new feature has been implemented that allows an item to "push" annotations
245      up to it's parent in addition to the normal "inherit to child" method.
246      This has been implemented as a change in the <methodname>getAnnotatableParents()</methodname>
247      method defined by the <interfacename docapi="net.sf.basedb.core">Annotatable</interfacename>
248      interface. This may cause unexpected issues with code that is not prepared to handle
249      this situation. Particulary, infinite loops must be avoided when traversing the "parent"
250      tree of an item (but this should already be in place since it can already happen due to
251      mistakes when creating items). See <ulink url="">ticket 1605</ulink>
252      for more information.
253    </para>
255  </sect1>
258  <sect1 id="appendix.incompatible.3.0">
259    <title>BASE 3.0 release</title>
261    <para>
262      There are a lot incompatible changes between BASE 3 and any of the BASE 2.x
263      versions. We do not list list those changes here since we do not expect existing
264      plug-ins, extensions or other client application to work with BASE 3 without
265      modification. See <xref linkend="migrate_2_3" /> for more information.
266    </para>
267  </sect1>
269  <sect1 id="appendix.incompatible.2.x">
270    <title>All BASE 2.x releases</title>
272    <para>
273      The list of changes made in the various BASE 2.x releases can be found
274      in the <ulink url=""
275      >BASE 2.17 documentation</ulink>.
276    </para>
278  </sect1>
Note: See TracBrowser for help on using the repository browser.