Building OSGi Bundles with Apache Maven

It seems that still today some developers think that creating an OSGi bundle is complicated – in contrast to simply creating a jar. Well, an OSGi bundle is a jar. The factor which distinguishes the two is that an OSGi bundle has additional manifest entries. Adding those using the right tooling is really simple.

The more difficult part is creating good modules: clearly separating public API from the implementation and correctly version the API based on the changes you made. But this is a general problem not related to OSGi at all and applies to any Java coding. There are some simple guidelines:

1. Leverage packages – put the API in a different package than your implementation. It’s also good still to use a package name for your implementation which makes clear that this is the implementation, e.g. by using impl as one part of the package name.
2. Start private and only make public if necessary. Once something is public, you never can make it private without breaking your clients. Starting private makes things easier.
3. Use semantic versioning. Whenever you change your public API, make sure to correctly increase the package version depending on the type of change you made.

Again, these are general guidelines and have nothing to do with OSGi. But OSGi uses headers in the manifest of your jar to know which packages from inside the jar are public API and the version of those packages. This is the export package header. Packages not listed there are private and not accessible to other modules. The other important header is the import package header, specifying which other packages this module is using. This usually comes with a version range, like a bundle is using package foo.bar version 1.1 or higher up to but not including 2.0.

Therefore, the only required thing to make a bundle out of your jar is more or less calculating these export and import packages headers and adding them to the manifest. But don’t fear, the tooling does this automatically for you. Let’s build a bundle/jar.

Using Apache Maven to Create a OSGi Bundle
There is always the year old debate on which build tool is the best one, I will not get into this discussion. I simply use what I know best and what I’m forced to use anyway: Apache Maven.

By default, Maven is not adding the additional manifest information to the jar, but there are different plugins for Maven available. For this tutorial, I’ll use the newer bnd Maven Plugin from the bnd project.

Add the following two plugin configurations to your pom. It’s usually a good idea to put this into your parent pom:

<plugin>

    <groupId>biz.aQute.bnd</groupId>

    <artifactId>bnd-maven-plugin</artifactId>

    <version>3.2.0</version>

    <executions>

        <execution>

            <goals>

               <goal>bnd-process</goal>

            </goals>

        </execution>

    </executions>

    <configuration>

        <bnd><![CDATA[

            -exportcontents: ${packages;VERSIONED}

        ]]></bnd>

    </configuration>

</plugin>

<plugin>

    <groupId>org.apache.maven.plugins</groupId>

    <artifactId>maven-jar-plugin</artifactId>

    <configuration>

        <useDefaultManifestFile>true</useDefaultManifestFile>

    </configuration>

</plugin>

The first adds the bnd maven plugin which creates the manifest data and the second instructs the default jar plugin to use the manifest created by the bnd plugin. And that’s it. If you now build your jar project using Maven you’ll have additional manifest entries in there.

Standard OSGi Bundle Headers
The first entries are standard headers which make your jar a bundle and contain some metadata:

• Bundle-ManifestVersion: This header is required and marks the jar as a bundle, the value is always 2 (newer OSGi specifications might add more features in which case the number would be increased).
• Bundle-Name: A human readable name for your bundle. This defaults to your project name from the pom.
• Bundle-SymbolicName: In combination with the bundle version (see below) the symbolic name provides a key to uniquely identify a bundle. This name should be based on the reverse domain name convention and defaults to the artifact id of your project. I’ll talk a little bit more about this soon.
• Bundle-Version: The version of your bundle, this defaults to the version of your project.

There is no magic in the above entries and having them in your jar does not hurt at all. As mentioned above, the symbolic name should be based on the reverse domain name convention. Usually in the Maven world you follow this rule for your group id, like org.mycompany.myproject and then use a simple name for the artifact id like scheduler-api. However a good practice is to use a full qualified name for the artifact id (which usually means you prefix the artifact id with the group id), e.g. org.mycompany.myproject.scheduler-api. Why is this a good idea? It has nothing to do with OSGi and simply makes sure that the final name of the artifact is fully qualified. If you don’t add the group id to the artifact id, the jar filename would be scheduler-api-1.2.3.jar – which is not very descriptive and gives you no clue what this thing is (and it might clash with other projects using the same artifact id).

The bundle version as any version in software development should increase with continued development/releases. For OSGi this information together with the symbolic name provides a unique key for a bundle and allows OSGi to verify if this exact bundle (name and version) is already installed in the OSGi framework. On a technical level, the bundle version information is more a marketing version.

Public API
More important than versioning your bundle (which still is important), it’s more important to correctly version your public API which might be used by others. For this add the following dependency to your pom:

<dependency>

    <groupId>org.osgi</groupId>

    <artifactId>osgi.annotation</artifactId>

    <version>1.0.0</version>

    <scope>provided</scoped>

</dependency>

The above dependency adds some annotations to your project – using the scope “provided” is a good practice as this avoids dragging in transitive dependencies.

Your public API should be in a separate Java package than your implementation – again this is a general good style and not tied to OSGi at all. If you want to export a package to be used by others, add a package-info.java file within your package:

@org.osgi.annotation.versioning.Version("1.0")
package org.osoco.software.samples.guessinggame;
If it’s the first version of your package, simply use 1.0 as the version – from now on once you have released this API as version 1.0, follow semantic versioning. Build your project again and you will see a header similar to this: 

Export-Package    org.osoco.software.samples.guessinggame; version="1.0"

As you can see creating the export is really easy, just use the above annotation and done. And the imports are even easier. The plugin analyses your classes and calculates the imports for you. For example, for my sample project, it looks like this: 

Import-Package  

javax.servlet; version="[3.1,4)", 

javax.servlet.http;version="[3.1,4)", org.osoco.software.samples.guessinggame;version="[1.0,1.1)"

And that’s it, your jar is now a bundle and can be used in any OSGi installation as a first-class citizen. It’s really simple – and in 96% of your cases, the automatic calculation by the tooling is sufficient. There are only rare and special cases where you want to have them differently. In that case, you can configure the plugin accordingly.