Monday, March 26, 2012

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.

2 comments:

Jimmi Dyson said...

Hi Jamie,

Great post - thanks for this.

You can also use features files for creating Karaf distributions - e.g. for repeatable installations across multiple servers when you don't want bundles downloaded from Maven repos at runtime.

I've also found it useful to attach the features XML as an artifact to the Maven build using the build-helper-maven-plugin (http://mojo.codehaus.org/build-helper-maven-plugin/attach-artifact-mojo.html). That way it gets deployed to a Maven repo & the actual feature file (using classifier of feature & type of xml) can be used as a dependency, perhaps of other features projects. That way you can chain features files to produce even better flexibility around your deployments.

A couple of problems I do have with using features though is that uninstalling features doesn't work particularly well. What if a bundle is required by multiple features, or installed manually rather than through a features installation? Should the bundle be uninstalled in these cases if a feature requiring it is uninstalled? Also there is no facility to upgrade features (i.e. upgrading versions of bundles in those features). Adding this functionality would make it more complex, like a full package manager like APT, & adding that complexity may not be desirable. Any thoughts on that?

Thanks,
Jimmi

Jamie Goodyear said...

Hi Jimmi,

Thanks for your post!

As to your comments regarding issues using features files in production (upgrades, uninstalls, etc), a lot of these issues lead to the development of Apache Karaf Kars.

An Apache Karaf KAR (KARaf archive) is a zip file which gathers a features XML and all bundles and configuration files dependencies. It means that a KAR is an atomic artifact which can be deployed without an Internet connection (as all is shipped in the KAR file itself). This leads to a some what easier administrative process for provisioning an application.

For more information on Apache Karaf Kars please see my previous post A brief introduction to Apache Karaf Archives (kars).

-Jamie