Apache Felix Maven Bundle Plugin (BND)

To use this plugin, very little information is required by BND. As part of the Maven integration, the plugin tries to set reasonable defaults for various instructions. For example:

Since the plugin creates bundles for OSGi R4, it hard-codes Bundle-ManifestVersion to be '2'. Additionally, it generates imports for every export to ensure package substitutability, which is very important when working with collaborating services. It is possible to override any of these values (except Bundle-ManifestVersion) just by specifying the desired value in the plugin configuration section of the POM file.

The first step in the process of using the plugin is downloading and installing the latest version of the Maven2 runtime. The latest Maven2 release and instuctions for getting started with Maven2 can be found at the Maven website.

To use the maven-bundle-plugin, you first need to add the plugin and some appropriate plugin configuration to your bundle project’s POM. Below is an example of a simple OSGi bundle POM for Maven2:

There are two main things to note: (1) the <packaging> specifier must be "bundle" and (2) the plugin and configuration must be specified (the configuration section is where you will issue instructions to the plugin).

Consider this more real-world example using Felix' Log Service implementation. The Log Service project is comprised of a single package: org.apache.felix.log.impl. It has a dependency on the core OSGi interfaces as well as a dependency on the compendium OSGi interfaces for the specific log service interfaces. The following is its POM file:

Notice that the <Export-Package> instruction specifies that the bundle exports the Log Service package, even though this package is not contained in the bundle project. By declaring this, the plugin will copy the Log Service package into the resulting bundle JAR file. This is useful in this case because now the bundle can resolve without having to download the entire compendium bundle. The resulting manifest for the Log Service bundle looks like this (notice how the imports/exports automatically have version information associated with them, which was obtained from packageinfo files in the source packages):

The resulting bundle JAR file has the following content (notice how the LICENSE and NOTICE files were automatically copied from the src/main/resources/ directory of the project):

If you want to keep your project packaging type (for example "jar") but would like to add OSGi metadata you can use the manifest goal to generate a bundle manifest. The maven-jar-plugin can then be used to add this manifest to the final artifact. For example:

If you want to use packaging types other than "jar" and "bundle" then you also need to enable support for them in the bundleplugin configuration, for example if you want to use the plugin with WAR files:

You’ll also need to configure the other plugin to pick up and use the generated manifest, which is written to ${project.build.outputDirectory}/META-INF/MANIFEST.MF by default (unless you choose a different manifestLocation in the maven-bundle-plugin configuration). Continuing with our WAR example:

The plugin is hosted at the Apache Felix project. The following steps describe how to build and install the plugin into your local Maven2 repository.

Using the SVN client of your choice, checkout the maven-bundle-plugin project.

Using Maven2, build and install the maven-bundle-plugin by issuing the following Maven2 command in the project directory that was created as a result of the previous step.

The Maven Bundle Plugin supports embedding of selected project dependencies inside the bundle by using the <Embed-Dependency> instruction:

where:

The plugin uses the <Embed-Dependency> instruction to transform the project dependencies into <Include-Resource> and <Bundle-ClassPath> clauses, which are then appended to the current set of instructions and passed onto BND. If you want the embedded dependencies to be at the start or middle of <Include-Resource> or <Bundle-ClassPath> then you can use {maven-dependencies}, which will automatically expand to the relevant clauses.

some examples:

examples of using {maven-dependencies}:

By default matched dependencies are embedded in the bundle as artifactId-version.jar. This behaviour can be modified using the following instructions:

Normally the plugin only checks direct dependencies, but this can be changed to include the complete set of transitive dependencies with the following option:

If you want a dependency inlined instead of embedded add the inline=true. For example to inline all compile and runtime scoped dependencies use:

The latest Maven Bundle Plugin automatically updates the local OBR repository.xml file during the install phase, using a default location of:

You can configure the location of the OBR repository by using the command line:

or in the configuration section for the maven-bundle-plugin in your Maven POM:

to disable OBR installation set the obrRepository to NONE, for example:

It is possible to configure the Maven Bundle Plugin to put the bundle manifest where Eclipse/PDE expects it, and use the Maven Dependency Plugin to arrange for any embedded dependencies to appear in a local directory that matches the Bundle-ClassPath entries. Here is an example POM that does this:

To generate the Eclipse metadata use:

and you should now be able to import this as an existing Eclipse project.

FYI: the above POM was generated using the pax-create-bundle command from Pax-Construct and then tweaked to demonstrate using the Maven Dependency Plugin to handle embedded jars in Eclipse.

With the original Pax-Construct generated POM you would simply use:

to create the appropriate Eclipse files and manifest, and also handle any embedded entries. The pax:eclipse goal extends eclipse:eclipse, and supports the same parameters.

Once in a while you may create a bundle which contains additional classes to the ones compiled from src/main/java, for example when you embed the classes from another jar. This can sometimes cause unforeseen problems in Maven, as it will use the output directory (target/classes) rather than the final bundle, when compiling against projects in the same reactor (ie. the same build).

The easiest way to get around this Maven 'feature' is to unpack the contents of the bundle to the output directory after the packaging step, so the additional classes will be found where Maven expects them. Thankfully there is now an easy option to do this in the bundle-plugin:

If you have an existing manifest, you can add this to the Bnd instructions, like so:

Bnd will use it when calculating the bundle contents, and will also copy across all manifest attributes starting with a capital letter. As shown in the above example, you could use this to include a non-OSGi manifest which you then customize with extra OSGi attributes.

The ant goal creates a customized build.xml Ant script along with a collection of BND instructions and properties, taken from the current project and stored in maven-build.bnd. You also need to run `ant:ant` to create the standard Ant support tasks to download Maven dependencies and perform compilation, etc.

The customized Ant script uses the BND tool to rebuild the bundle, so any source changes should be reflected in the (re)generated manifest.

Example:

The install-file goal updates the local OBR with the details of a bundle from the local filesystem.

Configuration:

Example:

The deploy goal updates the remote OBR with the details of the deployed bundle from the local Maven repository. The remote OBR is found by querying the <distributionManagement> section of the project, unless -DaltDeploymentRepository is set. See http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html for more details about these particular settings.

(If the project has an obr.xml file somewhere in its resources, then it will be automatically detected and applied.)

Configuration:

This goal is part of the "bundle" packaging lifecycle, but is disabled by default - to enable just set the remoteOBR parameter.

The deploy-file goal updates the remote OBR with the details of a deployed bundle from the local filesystem. The remote OBR is found using the -DrepositoryId and -Durl parameters. See http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html for more details about these particular settings.

You can use the -DbundleUrl parameter to give the public location of the deployed bundle, which may differ from the remote OBR location.

Configuration:

Example:

Sometimes you would like to clean your local OBR because it contains bundles that are no longer in your local Maven repository. This case often occurs when artifacts were deleted manually. The maven-bundle-plugin provides a simple goal to check for missing bundles, and remove them from the local OBR.

Configuration:

Example:

The index goal allows the creation of an OBR repository based on a set of jars in a maven repository.

Configuration:

Possible values for the urlTemplate are:

With a remote OBR, several uploads may occur at the same time. However, the remote OBR is centralized in one file, so concurrent modification must be avoided. To achieve this, the plug-in implements a locking system. Each time the plug-in tries to modify the file it sets a file based lock. If it can’t take the lock, it will wait and retry. After 3 attempts the upload process fails. To bypass this lock add -DignoreLock to the command-line (or add <ignoreLock>true<ignoreLock> to the configuration section of your Pom).

Not all protocols are supported by Maven out of the box. For example the ftp protocol requires the wagon-ftp component. To enable the ftp protocol add this to your Pom:

The description of the bundle comes from three different sources:

These sources are merged together using the following precedence:

A warning message is displayed when existing information is overridden.