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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: incompatible.xml 7161 2016-05-27 09:26:39Z nicklas $
  
  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<appendix id="appendix.incompatible">
  <?dbhtml filename="incompatible.html" ?>
  <title>API changes that may affect backwards compatibility</title>
  <para>
    In this document we list all changes to code in the <emphasis>Public API</emphasis>
    that may be backwards incompatible with existing client applications
    and or plug-ins. See <xref linkend="base_api.public" /> for more
    information about what we mean with the <emphasis>Public API</emphasis>
    and backwards compatible.
  </para>
  
  <sect1 id="appendix.incompatible.3.9">
    <title>BASE 3.9 release</title>
    
    <bridgehead id="appendix.incompatible.session-control">Application.getSessionControl()</bridgehead>
    <para>
      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
      method for getting access to an existing session has been deprecated. A new
      version has been implemented that require that an <emphasis>external client id</emphasis>
      is specified. This change was needed to avoid sessions leaking between client 
      applications and prevent users to use an application they don't have permission to use.
    </para>
    
    <para>
      The deprecated method use the client id from the BASE web client. Extensions and
      other clients that use a different client id are affected and may stop to work
      until they have been updated to use the new API. For more information see
      <ulink url="http://base.thep.lu.se/ticket/2011">ticket 2011</ulink>.
    </para>
    
  </sect1>
  
  
  <sect1 id="appendix.incompatible.3.8">
    <title>BASE 3.8 release</title>
    
    <bridgehead id="appendix.incompatible.service-session-control">ServiceSessionControl API</bridgehead>
    <para>
      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for 
      configuration and building Hibernate <classname>SessionFactory</classname>
      instances has been changed due the Hibernate 5 upgrade. This change affects
      extensions that use the API for storing their own data inside the BASE database.
      Extensions that use this API must be updated or they will not work with BASE 3.8.
    </para>
    
  </sect1>
  
  
  <sect1 id="appendix.incompatible.3.6">
    <title>BASE 3.6 release</title>
    
    <bridgehead id="appendix.incompatible.cloned-annotation">Cloned annotations</bridgehead>
    <para>
      A new feature that allows an inherited annotation to be cloned has been implemented.
      Several methods in <classname docapi="net.sf.basedb.core">AnnotationSet</classname>,
      <classname docapi="net.sf.basedb.core.snapshot">AnnotationSnapshot</classname> and some 
      other classes has been deprecated and replaced with new methods. Existing code that
      is not aware of cloned annotations should continue to work, but may experience some
      inconsistent behaviour in case the cloned values are out-of-sync with the original
      values.
    </para>

    <bridgehead id="appendix.incompatible.experimental-factors">Experimental factors have moved</bridgehead>
    <para>
      To allow the owner of an experiment to manage experimental factor values as part
      of the experiment, the <classname docapi="net.sf.basedb.core">RootRawBioassay</classname>
      item was introduced. The new item is a one-to-one representation of a <classname 
      docapi="net.sf.basedb.core">RawBioAssay</classname> inside that experiment.
      Experimental factor values that are found on existing raw bioassays are copied to the
      root rawbioassays when updating BASE. Changes made after the update will only
      affect the root raw bioassays. Existing code that is not aware of root raw bioassays
      may not find the experimental factor values.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.incompatible.3.5">
    <title>BASE 3.5 release</title>
    
    <bridgehead id="appendix.incompatible.itemlists">Biomaterial lists has been replaced with item lists</bridgehead>
    <para>
      The <classname docapi="net.sf.basedb.core">BioMaterialList</classname> 
      class has been removed and replaced with <classname 
      docapi="net.sf.basedb.core">ItemList</classname>. The API is similar 
      but not exactly the same. In most cases only minor changes are required
      to make existing code work with the new API.
    </para>
    
    <para>
      Queries that use the <code>BioMaterial.bioMaterialLists</code> association
      for joining will no longer work. There is no replacement functionality for
      joining item lists.
    </para>
    
    <para>
      All classes in the <code>net.sf.basedb.util.biomaterial</code> package has
      been deprecated. It is recommended that code that uses any of these classes
      are updated to use classes in <code>net.sf.basedb.util.listable</code> instead.
      The API is a bit different, but the new implementations typically performs a 
      lot better so it is worth the work.
    </para>

    <para>
      There are several other minor changes in the API that previously worked with
      the <code>BioMaterialList</code> class that has been removed and replaced
      with something else.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.incompatible.3.4">
    <title>BASE 3.4 release</title>
    
    <bridgehead>Updated JDOM to 2.0</bridgehead>
    <para>
      The JDOM library has been updated to version 2.0 from 1.1. The
      new version is incompatible with the old version. BASE 3.4 will
      ship with both versions but JDOM 1.1 will be removed in BASE 3.5
      and so will all API methods that expose JDOM 1.1 classes.
      It is recommended that plug-ins and extensions that use JDOM also
      update to JDOM 2.0.
    </para>
    
    <bridgehead>Updated to Apache HttpClient 4.3.4</bridgehead>
    <para>
      The Apache HTTP Client library has been updated to version 4.3.4.
      The new version has deprecated some classes that are exposed through
      the BASE API (mainly in <classname docapi="net.sf.basedb.util.ssl">SSLUtil</classname>).
      As a result we had to deprecate parts of the BASE API, which will
      be removed in BASE 3.5. It is recommended that plug-ins and
      extensions that are affected are updated to use the replacement API
      instead.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.incompatible.3.3">
    <title>BASE 3.3 release</title>
    
    <bridgehead>Content security policy</bridgehead>
    <para>
      The BASE web client now set a rather strict <emphasis>Content 
      Security Policy</emphasis> that prevent browsers from executing
      code (including JavaScript) that is considered unsafe. Some extensions
      may cease to work due to this. Go to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
        <guimenuitem>Overview</guimenuitem>
      </menuchoice> 
      (after upgrading) to see if there are any warnings about this.
      Read more in <xref linkend="appendix.web.xml.csp-filter" />
      for information about how to relax the policy.
    </para>

    <bridgehead>Re-factored JavaScript API</bridgehead>
    <para>
      The BASE web client has undergone a major refactoring with respect to
      the JavaScript API that is used on the server. A lot of functions have
      been replaced with new implementations. We have tried to map the old
      functions to the new ones, but this has not always been possible. Extentions
      that use the BASE JavaScript API must be tested with BASE 3.3 to find
      out if they are still working or if modifications are needed.
    </para>
    
    <note>
      <title>Avoid in-line event handlers and script</title>
      <para>
        The main reason for the refactoring is to get rid of all in-line
        event handlers and script sections since this is a possible entry
        point for cross-site scripting attacks (see <ulink 
          url="http://base.thep.lu.se/ticket/1712">ticket 1712</ulink>).
        Extension developers are encouraged to make the same changes in 
        their applications.
      </para>
    </note>

    <bridgehead>Biomaterial items are now lazy-loading</bridgehead>
    <para>
      For performance reasons biomaterial items have been changed from
      eager-loading to lazy-loading. This may affect clients and/or plug-ins
      that expect the parent chain of biomaterials to always be fully initialized
      without explicitely having told the BASE core to do so.
    </para>
    
    <bridgehead>Tables can have columns with different sort order</bridgehead>
    <para>
      A new feature has been implemented which allows columns in a table to
      have different sort order. This is implemented by allowing '+' or '-'
      as a prefix to properties returned by the <methodname>ItemContext.getSortProperty()</methodname>
      method. Properties without a prefix still use the global sort order as returned
      by <methodname>ItemContext.getSortDirection()</methodname>.
    </para>
    
    <para>
      Code that is not aware of the prefixes may fail since '+' and '-' are not
      allowed in property names.
    </para>
    
    <bridgehead>External authentication has been converted to an extension point</bridgehead>
    <para>
      External authentication plug-ins using the old system are supported through a 
      wrapper extension, but the recommendation is to update those plug-in to the
      new system. See <xref linkend="extensions_developer.login-manager" /> for more information.
    </para>
    
    <bridgehead>Setting parameters for a job no longer set it to status=WAITING</bridgehead>
    <para>
      Added <methodname>Job.setScheduled()</methodname> to switch the state
      from <constant>UNCONFIGURED</constant> to <constant>WAITING</constant>. 
      A job can't be executed before it has entered the <constant>WAITING</constant>
      state. The change makes it possible to register a job and some parameters for
      it and remain in the <constant>UNCONFIGURED</constant> state.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.incompatible.3.2">
    <title>BASE 3.2 release</title>

    <bridgehead>Derived bioassays can now have multiple parents</bridgehead>
    <para>
      Before BASE 3.2 a derived bioassay was restricted to a single parent 
      item. This affects the API and the <methodname>DerivedBioAssay.getParent()</methodname>
      and <methodname>DerivedBioAssay.getPhysicalBioAssays()</methodname> now always
      return null. Existing code should be updated to use <methodname>getPhysicalBioAssays()</methodname>
      and <methodname>getParents()</methodname> (which return <classname>ItemQuery</classname> instances)
      instead. Code that is using queries to filter or sort on parent items must also be
      updated since the association names have changed.
    </para>

    <bridgehead>BASEfile exporter automatically closes the output stream</bridgehead>
    <para>
      The implementation of the BASEfile exporter has been changed to
      automatically close the provided output stream when the export
      is complete. Clients that need the old behavior should call
      <code>BaseFileExporter.setAutoCloseWriters(false)</code> before
      using it.
    </para>

    <bridgehead>Change history logging is now an extension point</bridgehead>
    <para>
      The change history logging has been converted to an extension point.
      The <constant>changelog.factory</constant> setting in <filename>base.config</filename>
      is no longer used. Existing logging implementations should be updated
      to use the extension system. See <xref linkend="extensions_developer.logging" />.
      A temporary solution is to use one of the debugging action factories to 
      define the extension point:
    </para>
    
    <programlisting language="xml">
<![CDATA[
<extension 
   id="id-of-custom-log-manager"
   extends="net.sf.basedb.core.log-manager"
   >
   <about>
      <name>My custom log manager</name>
      <description>
         Temporary solution to allow the old log manager to work with the extension system.
      </description>
   </about>
   <index>1</index>
   <action-factory>
      <factory-class>net.sf.basedb.util.extensions.debug.BeanActionFactory</factory-class>
      <parameters>
         <beanClass>my.custom.LogmangerClass</beanClass>
      </parameters>
   </action-factory>
</extension>
]]>
</programlisting>

  </sect1>
  
  <sect1 id="appendix.incompatible.3.1">
    <title>BASE 3.1 release</title>

    <bridgehead>Web service framework updated to Axis2 1.6</bridgehead>
    <para>
      We have updated the web services framework to Axis2 1.6. Clients
      that use earlier Axis2 versions may not work when connecting to a
      BASE 3.1 server. Unfortunately, clients that use the Axis2 1.6
      framework may have problems connecting to BASE 3.0 servers so it
      may be difficult to implement support for both BASE 3.0 and BASE 3.1
      in a single client application.
    </para>

    <bridgehead>New GUI look and feel</bridgehead>
    <para>
      Taglibs, stylesheets and javscript functions have been changed
      to create a new look and feel. Plug-ins and extensions that uses
      GUI elements from the core BASE installation may need to be updated
      for the best user experience. The changes are too numerous so we can't
      list them here. Please use the developers mailing list if specific
      information is needed or see <ulink url="http://base.thep.lu.se/ticket/1655">ticket
      1655</ulink> for some screenshots and other information.
    </para>
    
    <bridgehead>Per-experiment copy of reporter annotations</bridgehead>
    <para>
      A new feature has been implemented that allows a user to make a
      local copy of reporter annotations for reporters that are used
      in an experiment. The existing API will by default use the local
      copy if one is available. It is possible to use the master reporter
      annotations by invoking certain API methods (for example: 
      <code>DynamicQuery.setUseClonedReporters(false)</code>). Since the copy
      may include only a subset of the available reporter annotations this
      may cause problems for code that is expecting all annotations to be
      available. See <classname docapi="net.sf.basedb.core">ReporterCloneTemplate</classname>
      and <ulink url="http://base.thep.lu.se/ticket/1616">ticket 1616</ulink>
      for more information.
    </para>

    <bridgehead>Annotations can be inherited/pushed from child to parent item</bridgehead>
    <para>
      A new feature has been implemented that allows an item to "push" annotations
      up to it's parent in addition to the normal "inherit to child" method.
      This has been implemented as a change in the <methodname>getAnnotatableParents()</methodname>
      method defined by the <interfacename docapi="net.sf.basedb.core">Annotatable</interfacename>
      interface. This may cause unexpected issues with code that is not prepared to handle
      this situation. Particulary, infinite loops must be avoided when traversing the "parent"
      tree of an item (but this should already be in place since it can already happen due to
      mistakes when creating items). See <ulink url="http://base.thep.lu.se/ticket/1605">ticket 1605</ulink>
      for more information.
    </para>

  </sect1>
  
  
  <sect1 id="appendix.incompatible.3.0">
    <title>BASE 3.0 release</title>

    <para>
      There are a lot incompatible changes between BASE 3 and any of the BASE 2.x
      versions. We do not list list those changes here since we do not expect existing
      plug-ins, extensions or other client application to work with BASE 3 without
      modification. See <xref linkend="migrate_2_3" /> for more information.
    </para>
  </sect1>
  
  <sect1 id="appendix.incompatible.2.x">
    <title>All BASE 2.x releases</title>

    <para>
      The list of changes made in the various BASE 2.x releases can be found
      in the <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/appendix/appendix.incompatible.html"
      >BASE 2.17 documentation</ulink>.
    </para>
    
  </sect1>
  

</appendix>