...

This plugin for Maven 2 is based on the BND tool from Peter Kriens. The way BND works is by treating your project as a big collection of classes (e.g., project code, dependencies, and the class path). The way you create a bundle with BND is to tell it the content of the bundle's JAR file as a subset of the available classes. This plugin wraps BND to make it work specifically with the Maven 2 project structure and to provide it with reasonable default behavior for Maven 2 projects.

Since the 1.4.0 release, this plugin also aims to automate OBR (OSGi Bundle Repository) management. It helps manage a local OBR for your local Maven repository, and also supports remote OBRs for bundle distribution. The plug-in automatically computes bundle capabilities and requirements, using a combination of Bindex and Maven metadata.

...

• manifest - create an OSGi manifest for the current project
  configuration options:
  • manifestLocation defaults to ${project.build.outputDirectory}/META-INF
  • supportedProjectTypes defaults to "jar","bundle"

...

• ant - create an Ant build script to rebuild the bundle

• install - adds the current bundle project to the local OBR
  configuration options:
  • obrRepository path to local OBR, defaults to <local-maven-repository>/repository.xml

More GOALs are available in the 1.4.0 release:

• ant - create an Ant build script to rebuild the bundle

• install-install-file - adds a local bundle file to the local OBR
  configuration options:
  • obrRepository path to local OBR, defaults to <local-maven-repository>/repository.xml
  • groupId Maven groupId for the bundle, taken from pomFile if given
  • artifactId Maven artifactId for the bundle, taken from pomFile if given
  • version Maven version for the bundle, taken from pomFile if given
  • packaging Maven packaging type for the bundle, taken from pomFile if given
  • classifier Maven classifier type, defaults to none
  • pomFile optional Pom file describing the bundle
  • file bundle file, defaults to the bundle from the local Maven repository
  • obrXml optional additional properties for the bundle

...

The default goal bundle will be initialized by setting the <packaging> entry to "bundle".

The following features are only available

...

from version 1.

...

2.0 onwards

Embedding dependencies

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

...

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 following features are only available from version 1.4.0 onwards

bundle:install-file

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

configuration:

• obrRepository path to local OBR, defaults to <local-maven-repository>/repository.xml
• groupId Maven groupId for the bundle, taken from pomFile if given
• artifactId Maven artifactId for the bundle, taken from pomFile if given
• version Maven version for the bundle, taken from pomFile if given
• packaging Maven packaging type for the bundle, taken from pomFile if given
• classifier Maven classifier type, defaults to none
• pomFile optional Pom file describing the bundle
• file bundle file, defaults to the bundle from the local Maven repository
• obrXml optional additional properties for the bundle

Example:

mvn org.apache.felix:maven-bundle-plugin:1.4.0:install-file \
  -DpomFile=myPom.xml -Dfile=foo-1.0.jar

bundle:deploy

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:

• remoteOBR name of remote OBR, defaults to NONE (which means no remote OBR deployment)
• obrRepository used when the remoteOBR name is blank, defaults to repository.xml
• altDeploymentRepository alternative remote repository, id::layout::url
• ignoreLock ignore remote locking when updating the OBR

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

bundle:deploy-file

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:

• remoteOBR name of remote OBR, defaults to an empty string
• obrRepository used when the remoteOBR name is blank, defaults to repository.xml
• repositoryId optional repository id, used to lookup authentication settings
• url remote repository transport URL, like

  No Format
  scpexe://host/path/to/obr

• bundleUrl public URL of deployed bundle, like

  No Format
  http://www.foo.org/bundles/foo.jar

• groupId Maven groupId for the bundle, taken from pomFile if given
• artifactId Maven artifactId for the bundle, taken from pomFile if given
• version Maven version for the bundle, taken from pomFile if given
• packaging Maven packaging type for the bundle, taken from pomFile if given
• classifier Maven classifier type, defaults to none
• pomFile optional Pom file describing the bundle
• file bundle file, defaults to the bundle from the local Maven repository
• obrXml optional additional properties for the bundle
• ignoreLock ignore remote locking when updating the OBR

Example:

mvn org.apache.felix:maven-bundle-plugin:1.4.0:deploy-file \
  -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/tmp/example/OBR \
  -DbundleUrl=http://www.foo.org/bundles/foo.jar

bundle:clean

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:

• obrRepository path to local OBR, defaults to <local-maven-repository>/repository.xml

To attach this goal to your project's lifecycle, use:

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <version>1.4.0</version>
  <executions>
    <execution>
      <goals>
        <goal>clean</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Concurrent updates

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).

FTP protocol

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:

<build>
  <extensions>
    <extension>
      <groupId>org.apache.maven.wagon</groupId>
      <artifactId>wagon-ftp</artifactId>
      <version>1.0-alpha-6</version>
    </extension>
  </extensions>
</build>

How the plug-in computes the description of the bundle

The description of the bundle comes from three different sources:

• Bindex : Bindex is a tool that analyzes a bundle manifest to generate OBR description
• pom.xml : by analyzing the pom file, various information is collected (symbolic name ...)
• obr.xml : this file contains customized description and capabilities for the bundle

These sources are merged together using the following precedence:

Bindex
| (overrides)
pom.xml
| (overrides)
obr.xml

A warning message is displayed when existing information is overridden.

Known issues & limitations

1. obr.xml (file given by the user to add properties not found by Bindex) must be correct, because the plug-in does not check its syntax.

Feedback

Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org.