Appendix K. API changes that may affect backwards compatibility

Table of Contents

K.1. BASE 2.9 release
K.2. BASE 2.7.1 release
K.3. BASE 2.7 release
K.4. BASE 2.6 release
K.5. BASE 2.5 release
K.6. BASE 2.4 release
K.7. BASE 2.3 release
K.8. BASE 2.2 release

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.

[Note] Note

There is no history for releases prior to BASE 2.2 because we did not actively keep track of them. We believe that if such changes exists, they are minor and does not affect many plug-ins since in those days very few 3rd-party plug-ins existed.

K.1. BASE 2.9 release

Must use a database that supports UTF-8

If you have been running BASE on a database that is not using UTF-8 as the character set you need to convert the database as part of the update. Read Section L.1, “BASE 2.9 must use a database that supports UTF-8” for more information.

K.2. BASE 2.7.1 release

Type.BOOLEAN.parseString()

This method now converts the empty string, "no", "0", and "false" (ignoring case) to boolean false. A null value as input still returns null as output. All other values are converted to true. Previously, all values except null and the string "true", was converted to false. The change was made to make this method behave the same as other string conversion methods.

K.3. BASE 2.7 release

Tomcat 6 or higher is required

If you have been running BASE with Tomcat 5.5 you need to upgrade your Tomcat installation before installing BASE 2.7.

K.4. BASE 2.6 release

Feature identification methods

Array design features can now be identified by three different methods: COORDINATES, POSITION and FEATURE_ID. The coordinates method was the only one supported earlier.

  • Client and plug-in code that depends on features having unique COORDINATES may no longer work if used with an array design using a different identification method. Code that is, directly or indirectly, using a FeatureBatcher or RawDataBatcher are probably affected by this. For example, a raw data importer which doesn't know how to set the position or the feature ID can't import data to an array design that is using one of the new identification methods.

  • The POSITION identification method will require a unique position number. This value used to be an auto-generated sequence starting at 1. The other identification methods will still do that, but when using the POSITION identification method the only requirement is that the position value is a unique positive integer. Client or plug-in code that depends on the position being a number between 1 and the number of features may fail if used with an array design using the POSITION identification method.

Data file types

The DataFileType.setValidatorClass() and DataFileType.setMetadataReaderClass() no longer verifies that the specified class names exists and implements the required interfaces. This validation will instead happen at commit time. The reason for this change is the added support for having the validator/meta data reader in external JAR files. This means that the validation can't happen until both the class names and JAR paths has been set. If a client application need validation before commit time it should use DataFileType.getValidator() and DataFileType.getMetadataReader() after the class names and JAR paths has been set.

Job.Status.ABORTING

Added the ABORTING option to the Job.Status enumeration. This option is used when the ABORT signal has been sent to an executing job, but the job has not yet responded to it. 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 EXECUTING.

Hybridization to Labeled extracts link

This link can now hold information about which sub-array a labeled extract belongs to on a multi-array hybridization. Code that is unaware of the concept of sub-arrays may find hybridizations where the number of labeled extracts doesn't match the number channels in the platform used, and that more than one labeled extract has the same label. This was previously considered as an error condition by the experiment validator. With the new scheme the validation has to be done on a sub-array basis instead of on the complete hybridization.

A similar issue arises when inheriting annotations to a raw bioassay which stems from a specific sub-array on a multi-array hybridization. This raw bioassay should only inherit annotations from the labeled extracts that are part of the same sub-array. For API compatibility reasons the Hybridization.getAnnotatableParents() will still return all labeled extracts. Code that is calling this method in order to find the parents to a raw bioassay should instead call the new method, Hybridizations.getAnnotatableParents(int), where the int is the sub-array index value for the raw bioassay.

A related issue arise when querying labeled extracts and joining the source events collection to use the linked hybridizations in the query. Here is an example:


// Find all labeled extracts on a given hybridization
Hybridization current = ...
ItemQuery<LabeledExtract> labeledExtractQuery = LabeledExtract.getQuery();

// This no longer works
// labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "evt"));

// Replace the above line with these two line
labeledExtractQuery.join(Hql.innerJoin("sourceEvents", "srcevt"));
labeledExtractQuery.join(Hql.innerJoin("srcevt", "event", "evt"));

labeledExtractQuery.restrict(
  Restrictions.eq(
    Hql.property("evt", "hybridization"), 
    Expressions.integer(current.getId())
  )
);

The good new is that the modifications makes it possible to filter the query on used quantity and sub-array. See the Javadoc for Hybridization to get more information.

K.5. BASE 2.5 release

Raw data types

The storage attribute of the <raw-data-type> has been deprecated for the raw-data-types.xml file. BASE will refuse to start if it finds this attribute. Raw data types which doesn't use the database for storing data should be registered as Platform:s instead.

Applications or plug-ins that filters on the rawDataType property for RawBioAssay or Experiment may need to change. The ID given to raw data types that doesn't use the database for storing data are prefixed with "platform.". The ID for the Affymetrix platform has changed from affymetrix to platform.affymetrix.

Raw bioassays

The property spots which used to hold the number of spots in the database OR in the file(s) has been split into two properties:

  • spots: Now only holds the number of database spots

  • numFileSpots: Holds the number of spots that are stored in files

Applications or plug-ins that filters on the spots property may no longer work as expected for file-only platforms, since this value is now always 0. They should use the numFileSpots property instead.

Array designs

The ArrayDesign.isAffyChip() method has been deprecated. Applications or plug-ins that filter on the affyChip property may no longer work as expected. The applications should instead filter on the platform.externalId and look for the value given by the constant Platform.AFFYMETRIX.

// This may no longer work
query.restrict(
   Restrictions.eq(
      Hql.property("affyChip"), 
      Expressions.parameter("affyChip", true, Type.BOOLEAN)
   )
);

// Use this instead
query.restrict(
   Restrictions.eq(
      Hql.property("platform.externalId"), 
      Expressions.string(Platform.AFFYMETRIX)
   )
);

K.6. BASE 2.4 release

Plug-in API

The InteractivePlugin.isInContext() method may now throw exceptions to indicate error-level messages. Messages that are returned by the method are considered as a warning message and are by default no longer shown to the users. See the section called “The net.sf.basedb.core.plugin.InteractivePlugin interface” and the section called “The Plugins tab”.

Custom JSP pages for plug-ins

Plug-ins using custom JSP pages for parameter input are recommended to pass along the requestId parameter. The parameter is optional, but if used it will prevent data from two different plug-ins configurations to get mixed up. See Section 26.2.3, “Using custom JSP pages for parameter input”.

JEP parser

The Jep.nodeToExpression() and Jep.nodeToString() methods return NULL if they find an unqouted NULL string in the expression. This allows JEP to convert expressions like ch(1) == NULL into a Query API expression testing for null. To get the old behaviour use ch(1) == 'NULL'.

Parsing strings into numeric values

The Type.parseString(String) method for Type.FLOAT and Type.DOUBLE has changed it's behaviour for NaN and Infinity values. The methods used to return Float.NaN, Float.NEGATIVE_INFINITY, Float.POSITIVE_INFINITY or the corresponding Double values. Since databases doesn't like these special values and eventually most values will go into the database, the parseString method now returns null instead.

Extended properties and raw data types

We have added validation code to check for invalid values. If you have modified the extended-properties.xml or the raw-data-types.xml file and they contain invalid values, you may not be able to start BASE until they are fixed. The validation is rather strict and things that may have worked before (because you were lucky or the because the database has been forgiving) may no longer work. Here is an overview of the most important validation rules:

  • Names and identifiers for extended properties and raw data type can only contain letters, digits and underscores. They must not start with a digit.

  • Names of database tables and columns can only contain letters, digits and underscores. They must not start with a digit.

  • There mustn't be any duplicate tables, columns, properties, etc. for a given context. For example, no duplicate tables in the database, no duplicate columns in a table, and no duplicate properties for a raw data type.

K.7. BASE 2.3 release

FlatFileParser

The hasMoreData() method has changed the order of checks made to determine the line type. The checks are now made in the following order:

  1. Check if the line should be ignored.

  2. Check if the line is a data footer.

  3. Check if the line is the start of a new section.

  4. Check if the line is a data line.

The data line check has been moved to the last since it was difficult to create settings that made sure section and data footer lines where matched correctly.

BASE 1 Plug-in executer

Changed to store information about plug-in parameters as XML in the database instead of in the original BASE version 1 plug-in definition file. Existing BASE version 1 plug-ins must be re-configured before they can be used. To do this:

  1. Go to AdministratePluginsConfigurations

  2. Step through the configuration wizard for all BASE version 1 plug-in configurations. You do not need to change any parameters. Just click on the Next button until the configuration is complete.

K.8. BASE 2.2 release

BASE 1 Plug-in executer

No longer provides a default mapping between BASE version 1 and BASE version 2 raw data columns. To solve this add a Formula item with the same name as the BASE version 1 column name and an expression that picks the BASE version 2 raw data property. For example:


Name          BCh1Mean
Type          Column expression
Raw data type GenePix
Channels      2
Expressions   1: raw('ch1BgMean')