Page History

This Maven plug-in aims to automate OBR (OSGi Bundle Repository) management. It creates helps manage a local OBR repository and can create a remote OBR to distribute bundles. This plug-in allows you to install your bundles inside an OBR repository at the same time you install it in your Maven repository. It can also deploy your bundle in a remote Maven repository when you deploy your Maven artefactfor your local Maven repository, and also supports remote OBRs for bundle distribution. 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 plug-in allows:maven-obr-plugin supports:

• Management of both local and remote OBRs
• Registering Maven and non-Maven artifacts with OBRs
• Automatically discovering
• Installing Maven artefact inside an OBR repository, 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:

• A: The standard 'install' goal: it will install your bundle in the repository at the same time it install it in your Maven repository.
• B: An 'install-file' goal which takes a jar file, and installs it in the local Maven repository and update  the remote repository descriptor file.
• C: A 'deploy' goal which upload a bundle on a remote repository and update the remote repository descriptor file.
• D: A 'deploy-file' goal which upload jar file on a remote repository and update the remote repository descriptor file. 
• E : A 'clean' goal cleaning the local obr repository.      

A: Installing bundles in a local OBR repository

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

B: Installing an existing Maven artefact in a local OBR repository

This second way, to use the plug-in,  is to add an already existing bundle in 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:

mvn homega.tools:obrPlugin:install-file \
-Drepository-path=file:/c:\repository.xml \
-obr-file=file:/c:\project\homega\obr.xml \
-DartifactId=multicast.discovery \
-DgroupId=homega.utils {color}
-Dversion=1.0.0

By using this command, the plug-in will look at the artefact MavenRepo\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 (artifactId, groupId, version, and obr file (if set)).

Note:

As said previously, the plug-in does not install the file in the Maven repository but target an already install artefact. However, it is possible to install the bundle in the repository and to add it in the OBR repository file in one command:
 mvn install:install-file homega.tools:obrPlugin:install-file {color}
-Dfile=file:/c:\projet\homega\multicast.discovery-1.0.0.jar {color}
-Drepository-path=file:/c:\repository.xml {color}
-Dobr-file=file:/c:\project\homega\obr.xml {color}
-DartifactId=multicast.discovery {color}
-DgroupId=homega.utils {color}
-Dversion=1.0.0 {color}
-Dpackaging=jar

C: Deploying a bundle on a remote OBR

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

• Add the "deployment" 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

In fact, all protocols are not supported by maven. For example ftp protocol as describe above require wagon plugin to run correctly. So you could add this part in your pom.xml to use wagon in ftp protocol:

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

By this way, the deploy goal supports all protocols supported by wagon.

D: Deploy non maven bundle on a remote OBR repository

This goal is useful if you want add a non-maven project on your remote repository, for example a legacy bundles.The command line is compozed by :

Example of complete command line:

mvn deploy:deploy-file homega.tools:obrPlugin:deploy-file \
-DartifactId=echo2
-DgroupId=tools
-Dversion=2.0.0
-Dpackaging=jar
-DrepositoryId=ftp-repository
-DuniqueVersion=false
-Durl=ftp://ftp.plop-plop.net/obr
-Dobr-file=c:\obr.xml
-Dfile=echo2.jar

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:
<project>
  <modelVersion>4.0.0</modelVersion>
  <packaging>jar</packaging>
  <groupId>tools</groupId>
  <artifactId>echo2</artifactId>
  <version>2.0.0</version>
  <distributionManagement>
   <repository>
    <id>ftp-repository</id>
    <name>RepoName</name>
    <url>ftp://ftp.plop-plop.net/obr</url>
   </repository>
  </distributionManagement>
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
         <artifactId>wagon-ftp</artifactId>
         <version>1.0-alpha-6</version>
      </extension>
    </extensions>
  </build>
</project>

Concurrent updates 

• 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 org.apache.felix:maven-obr-plugin:1.2.0:deploy-file \
  -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/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 must As the obr file is remote, several uploads can occur at the same time. However, the obr repository is centralized in one file, so concurrent modification need to be avoided. To achieve this, the plug-in  implement in implements a locking systemssystem. At each Each time the plug-in try tries to modify the file , it set sets a file based lock on it. If it can't take the lock, it will wait and retry. After 3 tries, attempts the upload process failed.

E: Cleaning the local obr repository 

Sometimes, you would like to clean your obr repository because it contains no more existing bundles. This case often occurs when artifacts were deleted manually from the maven repository. The plug-in provides a simple goal to look for missing bundle and to remove them from the obr repository.

...

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 analyzing  that analyzes a bundle manifest to generate OBR description
• The Pom file pom.xml : by analyzing the pom file, some various information are is collected (symbolic name ...)
• The obr.xml file : this file contains customized description of 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.: artefactId, groupId, version) is considered as pom.xml properties.

Known issues & limitations

...

...

1. obr.xml (file given by the user to

...

1. add properties not found by Bindex) must be correct, because the plug-in does not check

...

1. its syntax.