Making OSGi deployments easier with feature files

Q: How can we simplify provisioning bundles?
A: We use feature xml files.

When developing OSGi applications developers often end up with a large number of components that need to be deployed together. Doing this in a piece meal fashion can quickly become error prone, to help over come this problem Apache Karaf contains the concept of a feature file.

A feature file is a simple xml file that lists a collection of bundles that should be deployed together. It's really that simple! To make things even easier, a feature file may also reference other feature files allowing a developer to wire together even larger deployments. It should be noted that feature files are just a collection of references to resources - it is not a self contained artifact representing a ready to run application, that capability is encapsulated by the Apache Karaf Archive.

Luckily we've made creating a feature project really straight forward in Apache Karaf via the Karaf Feature Archetype. The archetype, when invoked, creates a skeleton Maven project for building a feature file. Using features to organize your provisioning of bundles marks one of the best practices for provisioning OSGi applications on Apache Karaf. Generally if I have two or more bundles that I need to deploy together then I'll go ahead and create a feature file.

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 feature project is as follows:
       mvn archetype:generate \
           -DarchetypeGroupId=org.apache.karaf.archetypes \
           -DarchetypeArtifactId=karaf-feature-archetype \
           -DarchetypeVersion=2.2.6-SNAPSHOT \
           -DgroupId=org.myorg \
           -DartifactId=my-feature \
           -Dversion=1.0.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, version, and package should be configured to your own project name and versions.

Using the Karaf Feature Archetype to create Maven
feature project skeletons is easy!

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. This project can be built by running "mvn install", a feature file will appear in the target/classess directory.

The generated feature file can then be deployed by either coping it into Karaf's deploy folder, or by adding the feature file to Karaf via the features:addurl command, then issuing the features:install command for the feature. In either case the bundles specified in the feature file will be resolved, then started.

To help make things a little clearer I've included a feature demo in Karaf's demo/deployer folder (as of Karaf version 2.2.6). The particular feature 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 feature.