OSGi Bundles require Classes from the Environment

Imagine your great application running inside an OSGi framework such as Apache Felix or Eclipse Equinox and requiring a class, which you know is provided by the Java Platform but not provided inside the framework.

For example, you provide functionality for the general user on the Internet to submit comments or register themselves but you want to protect this functionality from robots. To do this, you include a Captcha and decided to use the simple java captcha library from SourceForge. This library requires classes from the com.sun.image.codec.jpeg package. This package is generally not made visible inside the framework.

So, what can you do ? Of course you could configure your OSGi framework to just make the package visible by configuring either the org.osgi.framework.system.packages or the org.osgi.framework.bootdelegation property accordingly. But what if you can't do that ?

Here come the so-called Extension Bundles. Extension Bundles are actually Fragment Bundles, which attach to the System Bundle and extend the framework either by providing more exports from the System Bundle or by even appending to the class loader which loaded the OSGi framework.


How can an OSGi Framework be extended ?

A framework can be extended in two ways: Either by extending the list of packages available in the framework itself by ammending the System Bundle export list or by adding classes to the framework boot class loader.

To extend the framework the bundle must have the Fragment-Host manifest header set to either the actual bundle symbolic name of the system bundle as defined by the framework vendor. Alternatively the alias of the system bundle name, which is system.bundle may be used. I prefer the latter case because it would not create vendor lock-in on the Extension Bundle.

The type of extension is indicated by the extension directive of the Fragment-Host manifest header. The directive may take either of the following values:

• framework -- A framework extension ammends the System Bundle export list
• bootclasspath -- The Extension Bundle jar file is added to the class path of the class loader loading the OSGi framework. As such, the classes from the Extension Bundle jar file are actually loaded outside of the OSGi framework.
  

Example 1: Provide the com.sun.image.codec.jpeg Package

To continue our initial example, lets see how the com.sun.image.codec.jpeg package can actually be made visible to our Captcha bundle. To do this, we just need a manifest file which we package into a standard JAR file using the jar tool.

Frist create a file -- say manifest.mf with the following contents:

Bundle-ManifestVersion: 2
Bundle-SymbolicName: ch.meschberger.sample.extension
Bundle-Version: 0.0.1
Fragment-Host: system.bundle; extension:=framework
Bundle-Name: Sample Framework Extension
Bundle-Description: Sample Bundle exporting Sun's JPEG classes
Export-Package: com.sun.image.code.jpeg

Now, create the bundle JAR file:

$ jar -cfm ch.meschberger.sample.extension-0.0.1.jar manifest.mf

That's it. After installing this bundle in your framework you can use the Sun JPEG classes as usual.


Restrictions of Framework Extension Bundles


There are a few restrictions when using Framework Extension Bundles. First of all refreshing an Extension Bundle must cause the OSGi framework to stop and be restarted. An Extension Bundle enters the INSTALLED state but may enter the RESOLVED state only at the discretion of the OSGi framework. An Extension Bundle will never be in the STARTED state, though.

Further restrctions exist for the Bundle Manifest headers. That is, the following headers are not allowed to be used in an Extension Bundle:

• Import-Package
• Require-Bundle
• Bundle-NativeCode
• DynamicImport-Package
• Bundle-Activator

This is not generally a restriction per-se, because it is very unlikely that any of these headers is actually required by an Extension Bundle. Nevertheless, you must take care to not set any of these headers.


More Information

More information on the Extension Bundles may be found in section 3.15, Extension Bundles, of the OSGi Service Platform Core Specification which is available for download from the specification page of the OSGi Alliance.