Appendix I. API changes that may affect backwards compatibility

Table of Contents

I.1. BASE 3.3 release
I.2. BASE 3.2 release
I.3. BASE 3.1 release
I.4. BASE 3.0 release
I.5. All BASE 2.x releases

In this document we list all changes to code in the Public API that may be backwards incompatible with existing client applications and or plug-ins. See Section 28.1, “The Public API of BASE” for more information about what we mean with the Public API and backwards compatible.

I.1. BASE 3.3 release

Content security policy

The BASE web client now set a rather strict Content Security Policy that prevent browsers from executing code (including JavaScript) that is considered unsafe. Some extensions may cease to work due to this. Go to AdministratePlug-ins & extensionsOverview (after upgrading) to see if there are any warnings about this. Read more in Section E.1, “Content security policy” for information about how to relax the policy.

Re-factored JavaScript API

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.

[Note] Avoid in-line event handlers and script

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 ticket 1712). Extension developers are encouraged to make the same changes in their applications.

Biomaterial items are now lazy-loading

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.

Tables can have columns with different sort order

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 ItemContext.getSortProperty() method. Properties without a prefix still use the global sort order as returned by ItemContext.getSortDirection().

Code that is not aware of the prefixes may fail since '+' and '-' are not allowed in property names.

External authentication has been converted to an extension point

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 Section 26.8.14, “Login manager” for more information.

Setting parameters for a job no longer set it to status=WAITING

Added Job.setScheduled() to switch the state from UNCONFIGURED to WAITING. A job can't be executed before it has entered the WAITING state. The change makes it possible to register a job and some parameters for it and remain in the UNCONFIGURED state.

I.2. BASE 3.2 release

Derived bioassays can now have multiple parents

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

BASEfile exporter automatically closes the output stream

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 BaseFileExporter.setAutoCloseWriters(false) before using it.

Change history logging is now an extension point

The change history logging has been converted to an extension point. The changelog.factory setting in base.config is no longer used. Existing logging implementations should be updated to use the extension system. See Section 26.8.9, “Logging managers”. A temporary solution is to use one of the debugging action factories to define the extension point:


<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>

I.3. BASE 3.1 release

Web service framework updated to Axis2 1.6

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.

New GUI look and feel

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 ticket 1655 for some screenshots and other information.

Per-experiment copy of reporter annotations

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: DynamicQuery.setUseClonedReporters(false)). 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 ReporterCloneTemplate and ticket 1616 for more information.

Annotations can be inherited/pushed from child to parent item

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 getAnnotatableParents() method defined by the Annotatable 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 ticket 1605 for more information.

I.4. BASE 3.0 release

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 Chapter 23, Migrating code from BASE 2 to BASE 3 for more information.

I.5. All BASE 2.x releases

The list of changes made in the various BASE 2.x releases can be found in the BASE 2.17 documentation.