This Maven plug-in aims to automate OBR (OSGi Bundle Repository) management. It creates 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 artefact. The plug-in computes capabilities and requirements and edits the repository description file to add (or update) the bundle description.
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:
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.
- 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.
- 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 :
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.
To launch this feature, launch the following command from a folder of one of your bundle 'mvn org.apache.felix:maven-obr-plugin:clean'.
How the plug-in compute the description of the bundle
The description of the bundle comes from three different sources:
- Bindex : Bindex is a tool analyzing a bundle manifest to generate OBR description
- The Pom file : by analyzing the pom file, some information are collected (symbolic name ...)
- The obr.xml file : this file contains customized description of 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.: artefactId, groupId, version) is considered as pom.xml properties.
Known issues & limitations:
1. Do not support relative paths when you specify the repository descriptor in command line use.
2. obr.xml (file given by the user to describe some
properties not found by Bindex) must be correct, because the plug-in
does not check the syntax.