Best practices for package versioning

When you specify a version range for a package, you need to consider current policy and best practices, and requirements for compatibility with both earlier and future versions.

The OSGi Alliance best practices for specifying a version range on an Import-Package header are as follows: This reflects OSGi versioning policy, that is, when a new version of a package is not compatible with earlier versions, increment the major version number of the package.

For example, the following import statement can resolve against any version of a package from version 1.0 up to, but not including, version 2.0.

Import-Package: com.myco.a.pkge;version="[1.0,2.0)"

A package at version 1.3 is expected to be compatible with a package at version 1.0, and so a bundle that requires at least version 1.0 of a package should work if it is resolved against version 1.3 of that package. However, the bundle might not work if it is resolved against version 2.0 of the package, so version 2.0 and later versions are excluded.

An exception to this best practice is advisable for standard javax packages that are defined by the Java™ Community Process (JCP). The JCP currently does not define OSGi metadata such as package versions when it defines APIs. Currently, the OSGi versions are defined in the OSGi specifications that reference the Java technologies. Future versions of JCP specifications are expected to be compatible with earlier versions, so the OSGi package versioning policy for such future specifications could simply reflect the JCP specification version. This might result in a change of major version of a javax package even when the new version is compatible with the old. For example, the Java Persistence API (JPA) 2.0, which is compatible with the earlier version JPA 1.0, would follow the JCP specification name and use version 2.0, rather than following OSGi versioning policy and using version 1.1.

Because JCP specifications always try to maintain compatibility with earlier versions, it is advisable to specify only the minimum package version for a javax.* package and leave the upper boundary open. For example, if a version of WebSphere® Application Server in the future has a default JPA provider that implements a JPA later than version 2.0, it can export the javax.persistence package at that later version and still be resolved by applications that are written to work with JPA 1.0 or 2.0. Similarly, the following example import statement can resolve against any version of the javax.persistence package at 1.0 or higher:

Import-Package: javax.persistence;version="1.0"

Icon that indicates the topic type Concept topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Saturday, 20 October 2012
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v700osgijpa&product=was-nd-mp&topic=ca_eba_version

Copyright IBM Corporation 2009, 2012.
This information center is powered by Eclipse technology. (http://www.eclipse.org)