Table of Contents
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.
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.
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.
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.
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.
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. |
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.
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
.
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.
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()
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 (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.
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.
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. |
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.
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 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.
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.
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.
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.
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>
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.
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.
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.
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.
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.
The list of changes made in the various BASE 2.x releases can be found in the BASE 2.17 documentation.