Ensuring Compatibility

Compatibility Goals

The DDF framework, like all software, will mature over time.  Changes will be made to improve efficiency, add features, and fix bugs.  To ensure that compontents built for DDF and its sub-frameworks are compatible, developers must be aware when and where they establish dependencies from developed components.

Guidelines for Maintaining Compatibility

DDF Framework

For components written at the DDF Framework level (see Developing at the Framework Level), adhere to the following specifications: 

DDF Catalog API

For components written for the DDF Catalog (see Developing Catalog Components), only dependencies on the current major version of the Catalog API should be used.  .  Detailed documentation of the Catalog API can be found in the Catalog API Javadocs.

DDF Software Versioning

DDF follows the Semantic Versioning White Paper for bundle versioning (see Software Versioning).  

Third Party and Utility Bundles

It is recommended to avoid building directly on included third party and utility bundles. These components do provide utility (e.g. JScience) and reuse potential, however they may be upgraded or even replaced at anytime as bug fixes and new capabilities dictate. For example, Web services may be built using CXF. However, the distributions upgrade CXF frequently between releases to take advantage of new features. If building on these components, please be aware of the version upgrades with each distribution release.

Instead, component developers should package and deliver their own dependencies to ensure future compatibility.  For example if re-using a bundle like commons-geospatial, the specific bundle version that you are depending on should be included in your packaged release and the proper versions should be referenced in your bundle(s).

Best Practices

• Always use a version number when exporting a package

  Export Example

  <Export-Package>
    ${project.artifactId}*;version=${project.version}
  </Export-Package>

  In the example above the ${project.artifactId} represents the project and artifactId of the package being exported. The ${project.version} represents the version of the project.

• Try to avoid deploying multiple versions of a bundle. Although OSGi is designed to support multiple versions other developers may leave the version off packages that are being imported. If the bundle is versioned and designed appropriately typically multiple versions of the bundle will not be an issue. However, if each bundle is competing for a specific resource then race conditions may occur.  Third party and utility bundles (often denoted by commons in the bundle name) are the general exception to this rule, as these bundles will likely function as expected with multiple versions deployed.