Page History

Wiki Markup
This Maven plug-in aims to automate OBR ([OSGi Bundle Repository\|http://www2.osgi.org/Repository/HomePage]) management. It

...

 helps manage a local OBR for your local Maven repository

...

Features:

The plug-in allows:

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 plug-in?

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:

Variable name (prefixed by --D)	status	description
file	require	Path to the jar file (used to install bundle only)
artefactId	require	artefactId of the bundle Use to determine path to the jar file in local maven Repository use as symbolic name if it isn't define in manifest
groupId	require	groupId of the bundle Use to determine path to the jar file on local maven repository
version	require	Version of the bundle Use to determine path to the jar file on local maven repository
packaging	require	File type Use by maven to install the file (used to install bundle only)
repository-path	optional	Path to the repository descriptor file (if not define: default path is : MavenRepo\repository.xml
obr-file	optional	Path to the obr.xml, file which describe capabilities requirement and category given manually by user. (if not define: nothing is added to the resource description).

Example of command line:

...

 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 computes capabilities and requirements and edits the repository description file to add (or update) the bundle description.

h2. Features:

The plug-in supports:
* 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

h2. How to use the plug-in?

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.

h3. 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|http://felix.apache.org/site/maven-bundle-plugin-bnd.html].

h3. 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:
| Variable name (prefixed by \--D) | status | description |
| artifactId | required | artifactId of the bundle Used to determine path to the jar file in local maven Repository use as symbolic name if it isn't define in manifest |
| groupId | required | groupId of the bundle Used to determine path to the file in the local maven repository |
| version | required | Version of the bundle Used to determine path to the file in the local maven repository |
| packaging | required | File type Used to determine path to the file in the local maven repository |
| repository-path | optional | Path to the repository descriptor file (if not defined: default path is _{localRepository}_/repository.xml |
| obr-file | optional | Path to the obr.xml, file which describes capabilities, requirements and categories given manually by user. (if not defined: nothing is added to the resource description). |

h4. Example of command line:

mvn org.apache.felix:maven-obr-plugin:install-file \
\-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

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 |http://www2.osgi.org/Repository/BIndex]and information from the command line (

...

groupId, artifactId, version, and obr file (if set)).

...

Note:

...



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

...

C: Deploying a bundle on a remote OBR

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

Add the "deployment" goal

...



h3. Deploying a bundle to a remote OBR

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

* Add the "deploy" goal
** {color:black}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.

...

{color}
{color:teal}<{color}{color:#3f7f7f}plugin{color}{color:teal}>{color}
{color:teal}&nbsp;&nbsp;&nbsp; <{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}{color:black}org.apache.felix

...

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 :

Variable name (preceded by --D)	status	description
file	require	Path to the jar file
artefactId	require	artefactId of the bundle Use to determine path to the jar file in local maven Repository use as symbolic name if it isn't define in manifest
groupId	require	groupId of the bundle Use to determine path to the jar file on local maven repository
version	require	Version of the bundle Use to determine path to the jar file on local maven repository
packaging	require	File type Use by maven to install the file (used to install bundle only)
url	require	url to the remote server
uniqueVersion	optional	Set it to false to avoid unique filename when you upload
repositoryId	optional	Name of the repository use to upload file
obr-file	optional	Path to the obr.xml, file which describe capabilities requirement and category given manually by user. (if not define: nothing is added to the resource description).

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

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 a locking systems. At each time the plug-in try to modify the file, it set a lock on it. If it can't take the lock, it will wait and retry. After 3 tries, 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.

...

{color}{color:teal}</{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}{color:black}maven-obr-plugin{color}{color:teal}</{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}configuration{color}{color:teal}>{color}
{color:black}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;{color} {color:teal}<{color}{color:#3f7f7f}repository-name{color}{color:teal}>{color}{color:black}repository.xml{color}{color:teal}</{color}{color:#3f7f7f}repository-name{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}configuration{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}executions{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}execution{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}goals{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}goal{color}{color:teal}>{color}{color:black}deployment{color}{color:teal}</{color}{color:#3f7f7f}goal{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}goals{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}execution{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}executions{color}{color:teal}>{color}
{color:teal}</{color}{color:#3f7f7f}plugin{color}{color:teal}>{color}
** You must also configure where the plugin will upload bundles and repository descriptor file. You could do it in maven as this:
&nbsp; {color:teal}<{color}{color:#3f7f7f}distributionManagement{color}{color:teal}>{color}
{color:teal}&nbsp;&nbsp;&nbsp; <{color}{color:#3f7f7f}repository{color}{color:teal}>{color}
{color:teal}&nbsp;&nbsp;&nbsp;&nbsp; <{color}{color:#3f7f7f}id{color}{color:teal}>{color}{color:black}ftp-repository{color}{color:teal}</{color}{color:#3f7f7f}id{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}name{color}{color:teal}>{color}{color:black}RepoName{color}{color:teal}</{color}{color:#3f7f7f}name{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}url{color}{color:teal}>{color}{color:black}[ftp://ftp.youraddress.com/obr]{color}{color:teal}</{color}{color:#3f7f7f}url{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}repository{color}{color:teal}>{color}
&nbsp; {color:teal}</{color}{color:#3f7f7f}distributionManagement{color}{color:teal}>{color}
** 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:

{color:teal}<{color}{color:#3f7f7f}build{color}{color:teal}>{color}
{color:teal}&nbsp;&nbsp;&nbsp;&nbsp; <{color}{color:#3f7f7f}extensions{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}extension{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}{color:black}org.apache.maven.wagon{color}{color:teal}</{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}{color:black}wagon-ftp{color}{color:teal}</{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}version{color}{color:teal}>{color}{color:black}1.0-alpha-6{color}{color:teal}</{color}{color:#3f7f7f}version{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}extension{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}extensions{color}{color:teal}>{color}

The deploy goal supports all protocols supported by wagon.

h3. 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:
| Variable name (preceded by \--D) | status | description |
| artifactId | required | artifactId of the bundle Used to determine path to the file in the local maven repository |
| groupId | required | groupId of the bundle Used to determine path to the file in the local maven repository |
| version | required | Version of the bundle Used to determine path to the file in the local maven repository |
| packaging | required | File type Used to determine path to the file in the local maven repository |
| repository-name | optional | Name of the OBR file. (if not defined: defaults to repository.xml). |
| obr-file | optional | Path to the obr.xml, file which describe capabilities requirement and category given manually by user. (if not defined: nothing is added to the resource description). |

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

mvn deploy:deploy-file org.apache.felix:maven-obr-plugin:deploy-file \
\-Dfile=echo2.jar \
\-DrepositoryId=ftp-repository \
\-Durl=[ftp://ftp.plop-plop.net/obr] \
\-DuniqueVersion=false \
\-DgroupId=tools \
\-DartifactId=echo2 \
\-Dversion=2.0.0 \
\-Dpackaging=jar \
\-Dobr-file=c:\obr.xml

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

{color:teal}<{color}{color:#3f7f7f}project{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}modelVersion{color}{color:teal}>{color}{color:black}4.0.0{color}{color:teal}</{color}{color:#3f7f7f}modelVersion{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}packaging{color}{color:teal}>{color}{color:black}jar{color}{color:teal}</{color}{color:#3f7f7f}packaging{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}{color:black}tools{color}{color:teal}</{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}{color:black}echo2{color}{color:teal}</{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}version{color}{color:teal}>{color}{color:black}2.0.0{color}{color:teal}</{color}{color:#3f7f7f}version{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}distributionManagement{color}{color:teal}>{color}
&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}repository{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}id{color}{color:teal}>{color}{color:black}ftp-repository{color}{color:teal}</{color}{color:#3f7f7f}id{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}name{color}{color:teal}>{color}{color:black}RepoName{color}{color:teal}</{color}{color:#3f7f7f}name{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}url{color}{color:teal}>{color}{color:black}[ftp://ftp.plop-plop.net/obr]{color}{color:teal}</{color}{color:#3f7f7f}url{color}{color:teal}>{color}
&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}repository{color}{color:teal}>{color}
&nbsp; {color:teal}</{color}{color:#3f7f7f}distributionManagement{color}{color:teal}>{color}
&nbsp; {color:teal}<{color}{color:#3f7f7f}build{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}extensions{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}extension{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}{color:black}org.apache.maven.wagon{color}{color:teal}</{color}{color:#3f7f7f}groupId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}{color:black}wagon-ftp{color}{color:teal}</{color}{color:#3f7f7f}artifactId{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}<{color}{color:#3f7f7f}version{color}{color:teal}>{color}{color:black}1.0-alpha-6{color}{color:teal}</{color}{color:#3f7f7f}version{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}extension{color}{color:teal}>{color}
&nbsp;&nbsp;&nbsp; {color:teal}</{color}{color:#3f7f7f}extensions{color}{color:teal}>{color}
&nbsp; {color:teal}</{color}{color:#3f7f7f}build{color}{color:teal}>{color}
{color:teal}</{color}{color:#3f7f7f}project{color}{color:teal}>{color}

h4. 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 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 -Dignore-lock to the command-line or the configuration section of your Pom.

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

To use this feature, run the following command from a folder in your project 'mvn org.apache.felix:maven-obr-plugin:clean'.

h2.

...

 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

...

In order to create the bundle description, the plug-in gets information from bindex, the pom.xml and the obr.xml file. Information can be overridden:
Bindex
| (overrides)
Pom.xml
| (overrides)
Obr.xml

...

 description and capabilities for the bundle

In order to create the bundle description, the plug-in gets information from bindex, the pom.xml and the obr.xml file. Information can be overridden:
Bindex
\| (overrides)
pom.xml
\| (overrides)
obr.xml

A warning message is displayed each time already 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.

...



h2. Known issues & limitations:

...

1.

...

Does not support relative paths when you specify the repository descriptor in command line use.

...

2.

...

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.

Child pages

Versions Compared

Old Version 2

New Version 3

Key