Creating OSGi bundles
When approaching OSGi, one of the first concepts that have to be learned is the notion of a bundle. In this entry, I'd like to take a closer look of what a bundle actually is and how a vanilla jar can be transformed into an OSGi bundle. So, without further ado,
What is a bundle?
The OSGi spec describes the bundle as a "unit of modularization" that "is comprised of Java classes and other resources which together can provide functions to end users.". So far so good, but what exactly is a bundle? Quoting the spec again:
a bundle is a JAR file that:
- Contains [...] resources
- Contains a manifest file describing the contents of the JAR file and providing information about the bundle
- Can contain optional documentation in the OSGI-OPT directory of the JAR file or one of its sub-directories
In short, a bundle = jar + OSGI information (specified in the JAR manifest file - META-INF/MANIFEST.MF), no extra files or predefined folder layout are required. This means that all it takes to create a bundle from a jar, is to add some entries to the JAR manifest.
OSGi metadata
The OSGi metadata is represented by manifest entries that dictate to the OSGi framework what the bundle provides or/and requires. The specification indicates around 20 manifest headers but we will just take a look at the ones you are most likely to use.
Export-Package
As the name implies, this header indicates what packages (available in the bundle) are exported so they can be imported by other bundles. Only the packages specified by the header will be exported, the rest will be private and will not be seen outside the containing bundle.
Import-Package
Similar to Export-Package, this header indicates the packages that are imported by a bundle. As well, only the packages specified by this header will be imported. By default, imported packages are mandatory - the importing bundle will fail to start, if the imported package is not available.
Bundle-SymbolicName
The only required header, this entry specifies a unique identifier for a bundle, based on the reverse domain name convention (used also by the java packages).Bundle-Name
Defines a human-readable name, without spaces, for this bundle. Setting this header is recommend since it can provide a shorter, more meaningful information about the bundle content then Bundle-SymbolicName.Bundle-Activator
The BundleActivator is an OSGi specific interface that allows Java code to be notified when a bundle is started or stopped by the OSGi framework. The value of this header should contain a fully qualified name of the activator class which should be public and contain a public constructor without any arguments.Bundle-Classpath
This header is handy when the jar contains embedded libraries or class packages under various folders, by extending the default bundle classpath (which expects the classes to be available directly under the jar root).Bundle-ManifestVersion
This little known header indicates the OSGi specification to use for reading this bundle. 1 indicates OSGi release 3 while 2 OSGi release 4 and later. Since 1 is the default version, it is strongly recommended to specify this header since an OSGi release 4 bundle will not work as expected under OSGi release 3.Below is an example, taken from Spring 2.5.x core bundle manifest that uses some of the headers mentioned above:
Bundle-Name: spring-core
Bundle-SymbolicName: org.springframework.bundle.spring.core
Bundle-ManifestVersion: 2
Export-Package:org.springframework.core.task;uses:="org.springframework.core,org.springframework.util";version=2.5.1 org.springframework.core.type;uses:=org.springframework.core.annotation;version=2.5.1[...]
Import-Package:org.apache.commons.logging,edu.emory.mathcs.backport.java.util.concurrent;resolution:=optional[...]
Most of the time used on OSGi metadata is likely to be spent on Export/Import package entries as they describe the relationship between bundles (that is, between your modules). When it comes to packages, nothing is implicit - only packages that are mentioned are imported/exported, the rest aren't. This applies also to sub-packages: exporting org.mypackage will export just this package and nothing else (like org.mypackage.util). Same goes for importing - even if a package is available inside the OSGi space, it will not be seen by a certain bundle unless it is explicitly imported by it.
To summarize, if a bundle A exports package org.mypackage and bundle B wants to consume it, then the META-INF/MANIFEST.MF for bundle A should specify the package inside its Export-Package header, while bundle B should include it in its Import-Package entry.
Package consideration
While exporting is fairly straight forward, importing is slightly more complex. It is common for applications to degrade nicely by searching the environment for certain libraries and using only what is available, or for libraries to include code that is not used by the user. Such examples include logging (using JDK 1.4 or Log4j), regular expressions (Jakarta ORO or JDK 1.4+) or concurrent utilities (java.util in JDK 5 or backport-util-concurrent library for JDK 1.4).
In OSGi terms, relying on a package based on its availability translates to an optional Package-Import. You have already seen such a package in the previous example:
```code Import-Package: [...]edu.emory.mathcs.backport.java.util.concurrent;resolution:=optional ```Since in OSGi, multiple versions of the same class can exist, it is best practice to specify the version of the class package both when exporting and importing a package. This is done through the version attribute which is added after each package declaration. The version format supported by OSGi is <major>.<minor>.<micro>.<qualifier> where major, minor and micro are numbers and qualifier is alphanumeric.
The meaning of the version is completely up to the bundle provider however, it is recommend to use a popular numbering scheme such as the one from Apache APR project where:
- <major> - indicates a significant update which doesn't guarantee any compatibility
- <minor> - indicates an update which preserves compatibility with older minor versions
- <micro> - represents an insignificant update from the user point of view which is perfectly compatible both forwards and backwards
- <qualifier> - is a user defined string - it is not widely used and can provide an additional label to the version number, such as the build number or target platform without a standardized meaning
The default version (if the attribute is missing) is "0.0.0".
While the exported packages have to indicate a specific version, the importers can indicate a range using the mathematical interval notation - for example
[1.0.4, 2.0) will match version 1.0.42 and upwards up to 2.0 (excluding). Note that an specifying only a version instead of an interval will match all packages that are at greater or equal then the specified version, that is :
Import-Package: com.mypackage;version="1.2.3"
is equivalent to
Import-Package: com.mypackage;version="[1.2.3, ∞)"
As a last tip, make sure to always use quotes when specifying an version, whether it is a range or not.
Working with OSGi metadata
Now that we have some information on what bundles are, let's see what tools we can use for osgi-fying an existing jar:
by hand
This do-it-yourself approach is discouraged as typos and extra spaces can easily sneak in and render the manifest useless. Even when working with a smart editor, the manifest format itself can cause some problems since it has a limit of 72 spaces per line which, if broken, can cause some cryptic problems. Manually creating or updating the jar is not a good idea since the jar format requires the META-INF/MANIFEST.MF entry to be the first one in the archive - if it's not, even though it's present in the jar, the manifest file will not be read. The manual approach is really recommended for cases where there are no other alternatives.
However, if one really wants/needs to work directly with the manifest, then a editor that can deal with UNIX/DOS spaces should be used along with a proper jar creation utility (such as the jar tool that comes with the JDK) to cope with all the MANIFEST requirements.
Bnd
Bnd stands for BuNDle tool and is a nice utility created by Peter Kriens (OSGi Technical Officer) that "helps [...] create and diagnose OSGi R4 bundles". Bnd parses the java classes to understand the available and imported packages so it can create the equivalent OSGi entries. Bnd offers a series of directives and options which can customize the resulting artifact. The nice thing about bnd.jar itself is that is can be run from command line, by Ant through dedicated tasks or integrated into Eclipse as a plug-in.
Bnd can create jars from the classes available on the classpath or inside Eclipse projects or can osgi-fy existing jars by adding the needed OSGi artifacts. Additionally, it can print and verify the OSGi information about the given jar making it quite a powerful, yet simple to use tool.
First time users, can use Bnd to see what OSGi manifest will be added to a vanilla jar. Let's pick a vanilla jar such as c3p0 (which is an excellent connection pool library) and issue a print command:
```code java -jar bnd.jar print c3p0-0.9.1.2.jar ```
The output is fairly big and contains of several sections:
- Generic manifest information:
[MANIFEST c3p0-0.9.1.2.jar] Ant…
