Page History

This Maven plug-in 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. This plug-in lets you add your bundles to the local OBR at the same time you install them into your local Maven repository. It can also register your bundles with a remote OBR when you deploy them to a remote Maven repository. The plug-in automatically computes bundle capabilities and requirements and edits the repository description file to add (or update) the bundle description, using a combination of Bindex and Maven metadata.

Features

...

The plugmaven-obr-in plugin supports:

• Management of both local and remote OBRs
• Registering Maven and non-Maven artifacts with OBRs
• Automatically discovering
• Installing Maven artifacts inside an OBR, automatically or manually (for legacy bundles). This OBR could be remote or local.
• Discovering bundle capabilities and requirements
• Customizing bundle descriptions

How to use the

...

maven-obr-

...

plugin?

The plug-in offers five Maven goals:

• The standard 'install' goal which installs your bundle in the local OBR at the same time you install it in your local Maven repository.
• An 'install-file' goal which takes an existing Maven artifact, and installs it into the local OBR.
• A 'deploy' goal which installs your bundle in a remote OBR at the same time you deploy it to a remote Maven repository.
• A 'deploy-file' goal which takes an existing Maven artifact, and installs it into a remote OBR.
• A 'clean' goal which cleans the local OBR.

Installing bundles in a local OBR

The plug-in can create a local OBR at the root of the local Maven repository. Each time the artifact is installed in the local Maven repository (by using the 'mvn install' command), the local OBR repository is updated to contain the description of the artifact. This feature is automated inside the maven-bundle-plugin.

Installing an existing Maven artifact in a local OBR

This second way, to use the plug-in is to add an already existing bundle to the OBR. The bundle must be already in the Maven local repository (you can use the Maven install:install-file plug-in to install an external bundle in your Maven repository).

To use this goal, the user must provide information in command line:

Example of command line:

...

• install adds the current bundle project to the local OBR
• install-file adds a local bundle file to the local OBR
• deploy adds the current bundle project to a remote OBR
• deploy-file adds a local bundle file to a remote OBR
• clean cleans the local OBR, removing missing bundles

Any of these goals can be disabled by setting -DobrRepository=NONE

obr:install

The install goal updates the local OBR with the details of the installed bundle from the local Maven repository.

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

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-obr-plugin</artifactId>
  <version>1.2.0</version>
  <executions>
    <execution>
      <goals>
        <goal>install</goal>
      </goals>
    </execution>
  </executions>
</plugin>

obr: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-obr-plugin:1.2.0:install-file \

...

  -DpomFile=myPom.xml -Dfile=foo-1.0.jar

obr: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:

• obrRepository name of remote OBR, defaults to repository.xml
• altDeploymentRepository alternative remote repository, id::layout::url
• ignoreLock ignore remote locking when updating the OBR

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

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-obr-plugin</artifactId>
  <version>1.2.0</version>
  <executions>
    <execution>
      <goals>
        <goal>deploy</goal>
      </goals>
    </execution>
  </executions>
</plugin>

obr: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:

• obrRepository name of remote OBR, 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 

By using this command, the plug-in will look at the artifact <localRepository>/homega/utils/multicast.discovery/1.0.0/multicast.discovery-1.0.0.jar

Then it will compute bundle description by using bindex and information from the command line (groupId, artifactId, version, and obr file (if set)).

Note:

The OBR plug-in does not install the file in the Maven repository but uses an already installed artifact. However, it is possible to install the bundle in the repository and to add it to the local OBR in one command:

mvn install:install-file org.apache.felix:maven-obr-plugin:install-file \
-Dfile=file:///c:\projet\homega\multicast.discovery-1.0.0.jar \
-Drepository-path=file:///c:\repository.xml \
-obr-file=file:///c:\project\homega\obr.xml \
-DgroupId=homega.utils \
-DartifactId=multicast.discovery \
-Dversion=1.0.0 \
-Dpackaging=jar

Deploying a bundle to a remote OBR

To use the deploy goal, you must change your pom.xml

• Add the "deploy" goal
  • Indicate the repository-name property. This is the name of the repository descriptor file (this property is optional; default value is "repository.xml"). This file is located on url provided by user.
    <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-obr-plugin</artifactId>
            <configuration>
                <repository-name>repository.xml</repository-name>
            </configuration>
            <executions>
              <execution>
                <goals>
                  <goal>deployment</goal>
                </goals>
              </execution>
            </executions>
    </plugin>
  • You must also configure where the plugin will upload bundles and repository descriptor file. You could do it in maven as this:
      <distributionManagement>
        <repository>
         <id>ftp-repository</id>
         <name>RepoName</name>
         <url>ftp://ftp.youraddress.com/obr</url>
        </repository>
      </distributionManagement>
  • Now maven will upload your bundle on this ftp site.
• Launch the 'mvn deploy' command

Not all protocols are supported by maven out of the box. For example the ftp protocol described above requires the wagon plugin to run correctly. To use wagon for 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>

The deploy goal supports all protocols supported by wagon.

Deploy non-maven bundle on a remote OBR

This goal is useful if you want add a non-maven artifact to your remote repository, for example a legacy bundle.

To use this goal, the user must provide information in command line:

Example of complete command line, which also uses the maven-deploy-plugin to deploy the legacy bundle to the server:

...

org.apache.felix:maven-obr-plugin:1.2.0:deploy-file \

...

  -

...

DpomFile=

...

myPom.xml -Dfile=foo-1.0.jar -Durl=

...

file:/

...

To upload your file, you must create a small pom file declaring a repositoryManagement to indicates which remote server you use and the component to use for the protocol transfer. This file must contain also groupId, artifactId version and packaging information (in fact those data are redundant with the command line, so you could omit them in command line).

Example of additional pom.xml:

...

tmp/example/OBR \
  -DbundleUrl=http://www.foo.org/bundles/foo.jar

obr: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-obr-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-obr-plugin</artifactId>
  <version>1.2.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 needs to 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 addd add -Dignore-lock DignoreLock to the command-line (or add <ignoreLock>true<ignoreLock> to the configuration section of your Pom).

Cleaning the local OBR

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 from the Maven repository. The plug-in provides a simple goal to look for missing bundles and to remove them from the local OBR.

...

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
• The pom.xml file : by analyzing the pom file, various information is collected (symbolic name ...)
• The obr.xml file : 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 each time already when existing information is overridden. In case of install-file goal, the information given by user (i.e.: groupId, artifactId, version) is considered as pom.xml properties.

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.