 | OLD BRANCH: Pax Construct 0.1.6
|
Purpose
Provide a set of tools and processes to help construct and manage OSGi projects.
Resources
The latest set of OSGi archetype scripts can be downloaded from:
http://repository.ops4j.org/maven2/org/ops4j/pax/construct/scripts/0.1.6/scripts-0.1.6.zip
You must have Maven 2.0.5 or later installed and on your path so that the scripts can bootstrap themselves.
Add also the scripts folder to you path for easy usage:
unzip scripts-0.1.6.zip
Windows: set PATH=<path-to-pax-construct-0.1.6>\bin;%PATH%
*nix/Mac: PATH=<path-to-pax-construct-0.1.6>/bin:$PATH; export PATH
If you run into any problems using these scripts, or would like to request a new feature, please raise an issue - feedback is very welcome!
Scripts
This is the script that gets you started with Pax Construct, it creates a simple OSGi project layout:
| command |
goal |
usage |
| pax-create-project |
create a new OSGi project |
pax-create-project -g groupId -a artifactId [v version ] [- mvnopts ...] |
The following scripts should be run at the topmost folder of an OSGi project created by Pax Construct:
| command |
goal |
usage |
| pax-add-repository |
add a repository the the projec |
pax-add-repository -i id -u url [-- mvnopts ...] |
| pax-create-bundle |
create a new OSGi bundle |
pax-create-bundle -p javaPackage -n bundleName [v version ] [- mvnopts ...] |
| pax-import-bundle |
import an existing bundle from Maven |
pax-import-bundle -g groupId -a artifactId -v version [-- mvnopts ...] |
| pax-wrap-jar |
wrap an existing jar as a bundle |
pax-wrap-jar -g groupId -a artifactId -v version [-- mvnopts ...] |
| pax-provision |
deploy bundles onto a framework |
pax-provision -p platform [-- mvnopts ...] |
| pax-remove-bundle |
remove an existing OSGi bundle |
pax-remove-bundle -n bundleName [-- mvnopts ...] |
The following scripts should be run inside bundle directories that were created using pax-create-bundle:
| command |
goal |
usage |
| pax-embed-jar |
embed a jar inside the current bundle |
pax-embed-jar -g groupId -a artifactId -v version [-- mvnopts ...] |
| pax-use-bundle |
add a dependency to the current bundle |
pax-use-bundle -n bundleName [-- mvnopts ...] |
 | Simple use case - a web based OSGi application
pax-create-project -g simple.project -a osgi-web-app
cd osgi-web-app
pax-wrap-jar -g javax.servlet -a servlet-api -v 2.5
pax-import-bundle -g org.ops4j.pax.logging -a api -v 0.9.4
pax-import-bundle -g org.ops4j.pax.logging -a jcl -v 0.9.4
pax-import-bundle -g org.ops4j.pax.logging -a slf4j -v 0.9.4
pax-import-bundle -g org.ungoverned.osgi.bundle -a http -v 1.1.2
pax-create-bundle -p my.osgi.code.myBundle -n myBundle
mvn install pax:provision |
Additional Settings
Almost all of the scripts now support an additional mvn option -Doverwrite=true to overwrite existing files and entries.
pax-create-bundle accepts additional mvn options to control which files it automatically generates:
| -Dactivator=[false|true] |
if true the archetype generates a skeleton bundle activator and service implementation |
| -Dinterface=[false|true] |
if true the archetype generates a skeleton service interface |
| -DFRAMEWORK_OPTS='-Xmx200m' |
set the FRAMEWORK options for the PaxRunner, here, let it run with max 200MB heap space |
| -Dplatform=felix |
set the platform parameter for the PaxRunner, here, let it boot on Felix |
Example:
pax-create-bundle -p org.foo.service -n bar1 -- -Dinterface=false
pax-create-bundle -p org.foo.service -n bar2 -- -Dactivator=false
Produces an API/implementation pair of bundles - the default for both settings is true.
pax-embed-jar accepts an additional mvn option -Dunpack=true to unpack the contents of a jar instead of embedding it.
The generated OSGi project layout
| myProjct |
|
|
| \ ______ |
poms |
default configuration |
| \ ______ |
bundle_1 |
OSGi bundles, can be: |
| \ ______ |
bundle_2 |
wrapped, |
| \ ______ |
...... |
imported, |
| \ ______ |
bundle_N |
or compiled |
Provisioning Profiles
The pax-provision script uses the projects in the Maven reactor to determine which bundles to deploy.
You can therefore quickly setup different provisioning schemes by using Maven build profiles to select
which project modules will be in the reactor.
Eclipse Integration
The Pax plugin automatically creates Eclipse project files and metadata as part of the install phase.
It builds on the maven eclipse plugin to provide even better OSGi support. After running "mvn install"
you should be able to import all your bundles into Eclipse, and deploy them onto Equinox from the IDE.
 | Warning
using mvn eclipse:eclipse will overwrite the locally optimized project files |
Pax Construct 0.1.6 will now automatically restore previously generated metadata files whenever a
compilation fails (say if you use mvn clean install) - so hopefully no more missing manifests!
This is enabled by default in new project layouts - to enable it in old layouts add the following:
<execution>
<id>backup-metadata</id>
<phase>generate-resources</phase>
<goals>
<goal>backup</goal>
</goals>
</execution>
to the maven-pax-plugin executions section of the poms/compiled/pom.xml file.
Environment Variables
You can use these settings to try out snapshot releases of the Pax Construct tools:
| Name |
Effect |
| PAX_CONSTRUCT_VERSION |
Selects a different version of the Pax plugin |
| PAX_CONSTRUCT_OPTIONS |
Adds options to the maven archetype commands |
PAX_CONSTRUCT_VERSION=0.1.7-SNAPSHOT
PAX_CONSTRUCT_OPTIONS=-DarchetypeVersion=0.1.7-SNAPSHOT
export PAX_CONSTRUCT_VERSION
export PAX_CONSTRUCT_OPTIONS
... use tools to create new projects/bundles, etc.
Source
https://scm.ops4j.org/repos/ops4j/projects/pax/construct
This project builds on Felix's maven-bundle-plugin, Peter Krien's bnd tool and Maven's maven-eclipse-plugin.
Features, Roadmap & Changes
Release 0.1.4 provides a set of Windows batch files and Unix/Linux/Cygwin shell scripts to
make things even easier for OSGi developers.
Release 0.1.5 provides additional scripts to help automate the setup of more complex projects.
Release 0.1.6 provides unpacking of jars inside bundles using pax-embed-jar -g com.example -a somejar -v 1.0 – -Dunpack=true.
Further Examples
Embedding jars inside bundles
|
A number of people have asked about embedding dependendent jars inside bundles - with Pax Construct 0.1.5 this is as simple as going to the bundle directory (created using pax-create-bundle) and using pax-embed-jar to add the dependency. The dependent jarfile will be pulled into the final bundle artifact and added to the bundle classpath by a series of BND directives, added by the embed command. |
For the record, here is the old approach using Pax Construct 0.1.4:
http://wiki.ops4j.org/confluence/download/attachments/241/embed-example.zip
it includes a patchfile to show what changes were made to the original bundle.
There are basically three steps:
- use the maven-dependency-plugin to copy the dependencies to a folder
- add the folder as an embedded entry, using the Include-Resource directive
- add the jars to the Bundle-ClassPath, using their location in the bundle
If you're importing the project into Eclipse, you also need to alias the 'target/lib' folder to 'lib' using the Eclipse link feature.
