Appendix I. API changes that may affect backwards compatibility

Table of Contents

I.1. BASE 3.15 release
I.2. BASE 3.14 release
I.3. BASE 3.11 release
I.4. BASE 3.10 release
I.5. BASE 3.9 release
I.6. BASE 3.8 release
I.7. BASE 3.6 release
I.8. BASE 3.5 release
I.9. BASE 3.4 release
I.10. BASE 3.3 release
I.11. BASE 3.2 release
I.12. BASE 3.1 release
I.13. BASE 3.0 release
I.14. 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 29.1, “The Public API of BASE” for more information about what we mean with the Public API and backwards compatible.

I.1. BASE 3.15 release

Secondary storage support has been removed

API that is related to the secondary storage feature has been removed. For example, in the File class, getAction()/setAction() has been removed. In the Location enumeration, SECONDARY has been removed.

Spot images support has been removed

API that is related to creating and viewing spot images has been removed. For example, in the RawBioAssay class, the getSpotImages() method has been removed. The SpotImages class has been removed and there are several other minor changes related to this. There is no replacement.

Some deprecated classes and methods has been removed

Classes and methods that has been deprecated since BASE 3.10 or earlier have been removed. This may affect existing plug-ins and extensions. In most cases there exists a replacement method or class as indicated in the BASE 3.14 documentation.

Introduced generic return parameters

Some API methods with a return type of Object have been changed to <T> T (for example public <T> T getObject(String name) in ItemContext) which means that no explicit cast is needed since the compiler can typically infer this from the assignment made by the calling code. Note that this change is binary compatible with existing code, but in some cases it may be source code incompatible. Thus, already compiled code should continue to work, but source code may have to modified if compiling against the BASE 3.15 API. Here are some examples:


// With BASE 3.14 (also works with BASE 3.15)
ItemContext cc = ...
Hardware hardware = (Hardware)cc.getObject("item");

// With BASE 3.15
Hardware hardware = cc.getObject("item");

// This will not compile against BASE 3.15!
Set<AnnotatedItem> items = (Set<AnnotatedItem>)cc.getObject("AnnotatedItems");

// The explict cast must be removed
Set<AnnotatedItem> items = cc.getObject("AnnotatedItems");

Besides the change in the ItemContext.getObject() method there are several similar changes in the ItemContext class as well as in SessionControl, Annotation, AnnotationType FormatterFactory, ParameterValues and several other classes. In all cases, it should be relatively simple to update the code that doesn't compile.

[Note] Beware of JSP files

Since this change doesn't affect already compiled code, extensions and plug-ins are typically not affected. The exception is of course JSP files that are part of an extension since they are compiled at runtime by Tomcat. It may be wise to test this before upgrading a live BASE installation to BASE 3.15.

I.2. BASE 3.14 release

The (very) old Authenticator API has been removed

The net.sf.basedb.core.authentication.Authenticator interface and other related code that was deprecated in BASE 3.3 has been removed. Systems that still use old authentication code need to replace this with a newer version before updating.

I.3. BASE 3.11 release

Job.Status.PAUSED

Added the PAUSED option to the Job.Status enumeration. This option is used when a running job has been temporarily paused. Code that uses the job's status to decide what action to take may fail since this is a new option. In most cases, it should be handled in the same way as if the job is WAITING.

SHA-256 fingerprint on file servers

Added support for storing SHA-256 fingerprints on file servers. Code that is expecting the fingerprint to always be a MD5 value may stop to work. A new method FileServer.getFingerprintType() has been added.

Inactive roles

A new feature which allows a user to activate and de-activate roles on the fly during a login session has been implemented. This may cause a user to gain or lose permissions at any time. A change of active roles triggers an internal reload of permissions and since there are already other things that do this, it should not cause any problems. The SessionControl.getRoles() method has been deprecated and replaced with SessionControl.getAllRoles(), SessionControl.getActiveRoles() and SessionControl.getInactiveRoles().

I.4. BASE 3.10 release

Annotate permission

A new permission level, ANNOTATE has been added to the permission system. Extensions and other clients that are not aware of this permission may think that the user only has READ permission.

Project-specific annotations

The annotation system has been extended with a new feature: project-specific annotations. Extensions and other code that is not aware of this may experience strange behaviour where annotation values may not change as expected or may change in unexpected ways. For example, trying to change the default value of a project-specific annotation when a project is active causes a new annotation to be created in the background instead of changing the current one. Note that this feature is disabled by default and must be enabled per annotation type. Updating an existing server should be safe and will not affect existing annotations or annotation types.

I.5. BASE 3.9 release

Application.getSessionControl()

The Application.getSessionControl() method for getting access to an existing session has been deprecated. A new version has been implemented that require that an external client id 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.

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 ticket 2011.

I.6. BASE 3.8 release

ServiceSessionControl API

The ServiceSessionControl API for configuration and building Hibernate SessionFactory 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.

I.7. BASE 3.6 release

Cloned annotations

A new feature that allows an inherited annotation to be cloned has been implemented. Several methods in AnnotationSet, AnnotationSnapshot 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.

Experimental factors have moved

To allow the owner of an experiment to manage experimental factor values as part of the experiment, the RootRawBioassay item was introduced. The new item is a one-to-one representation of a RawBioAssay 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.

I.8. BASE 3.5 release

Biomaterial lists has been replaced with item lists

The BioMaterialList class has been removed and replaced with ItemList. 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.

Queries that use the BioMaterial.bioMaterialLists association for joining will no longer work. There is no replacement functionality for joining item lists.

All classes in the net.sf.basedb.util.biomaterial package has been deprecated. It is recommended that code that uses any of these classes are updated to use classes in net.sf.basedb.util.listable instead. The API is a bit different, but the new implementations typically performs a lot better so it is worth the work.

There are several other minor changes in the API that previously worked with the BioMaterialList class that has been removed and replaced with something else.

I.9. BASE 3.4 release

Updated JDOM to 2.0

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.

Updated to Apache HttpClient 4.3.4

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 SSLUtil). 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.

I.10. 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 27.8.16, “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.11. 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 27.8.10, “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.12. 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.13. 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 24, Migrating code from BASE 2 to BASE 3 for more information.

I.14. 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.