OSGi Contracts

This is an advanced subject.

One possibility for the versioning problem in the previous section is to use OSGi contracts. An OSGi contract replaces the versions on the myriad packages with a single versioned name. This was concept was developed because the versions on servlet related packages was a disaster. This is outlined in 135.3 osgi.contract Namespace.

Providing a contract is quite straightforward, you provide a capability that enumerates the packages that belong to the contract. The users of the bundle should then have a matching requireme capability. (bnd has support then to remove the versions from the package import, read 135.3 osgi.contract Namespace for more information.)

The capability that we provide for the contract must contain the list of packages in the uses: directive. Fortunately, the ${exports} macro contains the list of all our exported packages in bnd. Saves us from maintaining this list by hand. So the capability would look like:

Provide-Capability: \
  ... \
  osgi.contract; \
    osgi.contract=DOM4J; \
    uses:="${exports}"; \
    version:List<Version>=1.0.0

There is a bug in the OSGi specification, it lists version=1.0.0 but it should be version:List<Version>=1.0.0.

The bundles that use this DOM4J contract should now have a matching require capability like:

Require-Capability: \
  ... \
  osgi.contract; \
    filter:="(&(osgi.contract=DOM4J)(version=1.0))"
-contract: DOM4J

The -contract instruction tells bnd to remove the versions of all packages that are part of the contract.