Making an OSGi bundle using Apache Karaf 2.2.x.

How do I make one of these OSGi bundles?

I received a few private messages regarding my last Apache Karaf demo post asking a more fundamental question on making OSGi bundles for use with Apache Karaf - that is how to just make a standalone bundle?

Before I dive into the above question, if you're wondering just what OSGi is then please visit: http://www.osgi.org/About/HowOSGi.

To the unfamiliar an OSGi bundle is essentially a special Java Archive file. The basic premise behind the idea is to add a set of properties to a jar's standard Manifest file. These properties correspond to OSGi naming and versioning standards, it also includes a few properties that enable an OSGi container to manage dependencies for the bundles deployed inside it. Outside of these properties, little else differs, except for a special class that implements the Bundle Activator interface; this is used by the OSGi container as a hook into bundle's life cycle (one would normally specify a Main method to execute code from a jar, OSGi uses an implementation of the Bundle Activator interface which contains a start, stop, and other methods to control life cycle states). The class implementing the Bundle Activator interface is specified in the Manifest file so that the OSGi container may interact with it.

A bundle is built up from a collection of classes, resources, and a manifest file.

Well luckily we've made creating a bundle project really straight forward in Apache Karaf via the Karaf Bundle Archetype. The archetype, when invoked, creates a skeleton Maven project for building an OSGi bundle. This skeleton goes so far as to even generate a bundle activator for you. Personally, I find this methodology much easier than creating all the artifacts by hand ;)

To use the archetype you'll need the following:

1. Java 1.5 or higher.
2. Apache Maven 2.2.1 or higher.
3. And Apache Karaf 2.2.6 kit or higher installed.

The general format of the archetype invocation for generating a bundle project is as follows:
    mvn archetype:generate \
      -DarchetypeGroupId=org.apache.karaf.archetypes \ 
      -DarchetypeArtifactId=karaf-bundle-archetype \ 
      -DarchetypeVersion=2.2.6-SNAPSHOT \ 
      -DgroupId=org.myorg \
      -DartifactId=my-bundle \ 
      -Dversion=1.0-SNAPSHOT \ 
      -Dpackage=org.myorg.package
The command may look a little complicated but its mostly straight forward once you break it down into its parts.

The first three arguments to the archetype generate directive simply specify to maven which archetype to use, the next four arguments are what you're going to be most interested in configuring. The groupId, artifactId, and version are how you want your bundle to be named and versioned. The package argument is the name of the package you want the internal code to use.

Once you've invoked the command it will begin parsing your input, then ask to confirm its interpretation of your configuration before writing to disk a skeleton project. Once this is complete you'll have a new folder created that contains a pom file and src folder containing a sample activator class. This project can be built by running "mvn install", a bundle will appear in the target directory.

Using the Karaf Bundle Archetype to create Maven
bundle project skeletons is easy!

The generated bundle can then be deployed by coping it into Karaf's deploy folder or by invoking an install command on Karaf's console. When the bundle is started a message will be printed to the prompt, similarly when the bundle is stopped another message will be displayed (this behaviour can be removed by editing the start and stop methods of the Bundle Activator implementation).

To help make things a little clearer I've included a bundle demo in Karaf's demo/deployer folder (as of Karaf version 2.2.6). The particular bundle project you'll find has been crafted to be as minimal as possible. You'll find a README file in the folder as well that outlines the instructions to build and deploy the demo bundle.