Rapid OSGi development with Pax-Construct
Z Jacek Laskowski - Wiki Projektanta Java EE
It's all begun when I suddenly realized that I don't really know how to lay down a OSGi bundle project quickly and with no or a minimum effort. I'm a Apache Maven user so it was quite obvious to me to find a way with the tool. After a bit of Googling, I stumbled upon the blog entry Quick OSGi projects using Maven archetypes dated at...2007 (!) It led to Pax-Construct that's a tool for "rapid OSGi development from OPS4j" (quoting "About the Authors" in OSGi in Action from Manning). The example on its home page made it crystal clear that a few shell scripts that use Apache Maven plugins can do a chore an easy and pleasant exercise. Enter Pax-Construct that aims to smooth your way through the early stages of developing OSGi bundles (and even more, but this, however, has not yet been proved by myself).
The article's goal is to expand the information available on Pax Construct Quickstart page with the commands' output, the bundle naming, more explanation, and a few screenshots.
The home page of Pax-Construct says about the version 1.4 shipped on 01/15/2009. There is, however, the version 1.5 available in Maven's official repository.
Spis treści |
Installing Pax-Construct
The installation of Pax-Construct boils down to downloading the scripts-1.5.zip archive and unpacking to the directory of your choice.
Add the bin subdirectory to the PATH environment variable and you're all set.
export PATH=~/apps/pax-construct/bin:$PATH
Make sure you've got Apache Maven installed, too.
Creating Apache Maven-based POM module for OSGi bundle projects - pax-pax-create-project
With the pax-construct scripts available, it's time to create a OSGi project that in fact a Apache Maven project with plugins and modules set up to ease your development endeavor.
The script to begin with is pax-create-project.
$ pax-create-project -h pax-create-project -g groupId -a artifactId [-v version] [-o] [-- mvnOpts ...] @ http://www.ops4j.org/projects/pax/construct/help/create-project.html
The options correspond to Apache Maven naming scheme, with mandatory groupId and artifactId.
$ pax-create-project -g pl.jaceklaskowski.osgi -a helloworld-osgi [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Maven Stub Project (No POM) 1 [INFO] ------------------------------------------------------------------------ ... [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating Archetype: maven-archetype-osgi-project:1.5 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: packageName, Value: pl.jaceklaskowski.osgi.helloworld-osgi [INFO] Parameter: archetypeVersion, Value: 1.5 [INFO] Parameter: groupId, Value: pl.jaceklaskowski.osgi [INFO] Parameter: archetypeArtifactId, Value: maven-archetype-osgi-project [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: archetypeGroupId, Value: org.ops4j.pax.construct [INFO] Parameter: basedir, Value: /Users/jacek/sandbox [INFO] Parameter: package, Value: pl.jaceklaskowski.osgi.helloworld-osgi [INFO] Parameter: artifactId, Value: helloworld-osgi [INFO] ********************* End of debug info from resources from generated POM *********************** [INFO] Archetype created in dir: /Users/jacek/sandbox/helloworld-osgi [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
pax-create-project uses the maven-archetype-osgi-project archetype that was the archetype I was initially looking for before I found Pax-Construct.
Change the working directory to the just-created directory - helloworld-osgi that becomes the directory where the rest commands will be executed.
$ cd helloworld-osgi/
Create OSGi bundle project - pax-create-bundle
The next command you'll surely use after pax-create-project is pax-create-bundle to create a Apache Maven project to manage (the files of) a OSGi bundle.
$ pax-create-bundle -h pax-create-bundle -p package [-n bundleName] [-g bundleGroupId] [-v version] [-o] [-- mvnOpts ...] @ http://www.ops4j.org/projects/pax/construct/help/create-bundle.html
The options of pax-create-bundle let you specify the naming scheme for your OSGi bundle. Again, if you know Apache Maven and OSGi naming scheme it should come quite natural and smooth.
$ pax-create-bundle -p pl.jaceklaskowski.osgi.helloworld -n pl.jaceklaskowski.osgi.helloworld.api -v 1.0.0 [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building pl.jaceklaskowski.osgi.helloworld-osgi (OSGi project) 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] ... [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating Archetype: maven-archetype-osgi-bundle:1.5 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: symbolicName, Value: pl.jaceklaskowski.osgi.helloworld.api [INFO] Parameter: packageName, Value: pl.jaceklaskowski.osgi.helloworld [INFO] Parameter: archetypeVersion, Value: 1.5 [INFO] Parameter: groupId, Value: pl.jaceklaskowski.osgi.helloworld-osgi [INFO] Parameter: archetypeArtifactId, Value: maven-archetype-osgi-bundle [INFO] Parameter: version, Value: 1.0.0 [INFO] Parameter: archetypeGroupId, Value: org.ops4j.pax.construct [INFO] Parameter: isMultiModuleProject, Value: true [INFO] Parameter: basedir, Value: /Users/jacek/sandbox/helloworld-osgi [INFO] Parameter: package, Value: pl.jaceklaskowski.osgi.helloworld [INFO] Parameter: artifactId, Value: pl.jaceklaskowski.osgi.helloworld.api [INFO] ********************* End of debug info from resources from generated POM *********************** [INFO] Archetype created in dir: /Users/jacek/sandbox/helloworld-osgi/pl.jaceklaskowski.osgi.helloworld.api [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating Archetype: maven-archetype-osgi-service:1.5 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: symbolicName, Value: pl.jaceklaskowski.osgi.helloworld.api [INFO] Parameter: packageName, Value: pl.jaceklaskowski.osgi.helloworld [INFO] Parameter: archetypeVersion, Value: 1.5 [INFO] Parameter: groupId, Value: pl.jaceklaskowski.osgi.helloworld-osgi [INFO] Parameter: archetypeArtifactId, Value: maven-archetype-osgi-service [INFO] Parameter: version, Value: 1.0.0 [INFO] Parameter: archetypeGroupId, Value: org.ops4j.pax.construct [INFO] Parameter: isMultiModuleProject, Value: true [INFO] Parameter: basedir, Value: /Users/jacek/sandbox/helloworld-osgi [INFO] Parameter: package, Value: pl.jaceklaskowski.osgi.helloworld [INFO] Parameter: artifactId, Value: pl.jaceklaskowski.osgi.helloworld.api [INFO] ********************* End of debug info from resources from generated POM *********************** [INFO] Archetype created in dir: /Users/jacek/sandbox/helloworld-osgi/pl.jaceklaskowski.osgi.helloworld.api [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
OSGi bundle provisioning - pax:provision
With the projects set up - a POM "umbrella" project and a single module for the OSGi bundle - we can run the bundle in a OSGi framework. Run pax:provision as a Apache Maven task to execute the bundle in Apache Felix.
$ mvn clean install pax:provision
[INFO] Scanning for projects...
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] pl.jaceklaskowski.osgi.helloworld-osgi (OSGi project)
[INFO] helloworld-osgi - plugin configuration
[INFO] helloworld-osgi - wrapper instructions
[INFO] helloworld-osgi - bundle instructions
[INFO] helloworld-osgi - imported bundles
[INFO] pl.jaceklaskowski.osgi.helloworld.api [pl.jaceklaskowski.osgi.helloworld]
...
\______ \_____ ___ ___ \______ \__ __ ____ ____ ___________
| ___/\__ \ \ \/ / | _/ | \/ \ / \_/ __ \_ __ \
| | / __ \_> < | | \ | / | \ | \ ___/| | \/
|____| (____ /__/\_ \ |____|_ /____/|___| /___| /\___ >__|
\/ \/ \/ \/ \/ \/
Pax Runner (1.7.4) from OPS4J - http://www.ops4j.org
----------------------------------------------------
-> Using only arguments from command line
-> Scan bundles from [/users/jacek/sandbox/helloworld-osgi/runner/deploy-pom.xml]
-> Scan bundles from [scan-pom:file:/users/jacek/sandbox/helloworld-osgi/runner/deploy-pom.xml]
-> Provision bundle [mvn:pl.jaceklaskowski.osgi.helloworld-osgi/pl.jaceklaskowski.osgi.helloworld.api/1.0.0,
at default start level, bundle will be started, bundle will be loaded from the cache]
-> Preparing framework [Felix 3.2.1]
...
-> mvn:pl.jaceklaskowski.osgi.helloworld-osgi/pl.jaceklaskowski.osgi.helloworld.api/1.0.0 : 5830 bytes @ [ 5830kBps ]
-> Using execution environment [J2SE-1.6]
-> Runner has successfully finished his job!
STARTING pl.jaceklaskowski.osgi.helloworld
REGISTER pl.jaceklaskowski.osgi.helloworld.ExampleService
____________________________
Welcome to Apache Felix Gogo
g!While in Apache Felix Gogo Shell, type in lb to list available bundles.
g! lb
START LEVEL 6
ID|State |Level|Name
0|Active | 0|System Bundle (3.2.1)
1|Active | 5|pl.jaceklaskowski.osgi.helloworld.api [pl.jaceklaskowski.osgi.helloworld] (1.0.0)
2|Active | 1|Apache Felix Gogo Command (0.8.0)
3|Active | 1|Apache Felix Gogo Runtime (0.8.0)
4|Active | 1|Apache Felix Gogo Shell (0.8.0)As you may have noticed the bundle of ours is Active with the id 1.
Shut down the framework by stopping the System Bundle. That will in turn finish the Maven execution.
g! stop 0 g! STOPPING pl.jaceklaskowski.osgi.helloworld -> Platform has been shutdown. [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] [INFO] pl.jaceklaskowski.osgi.helloworld-osgi (OSGi project) SUCCESS [2:59.479s] [INFO] helloworld-osgi - plugin configuration ............ SUCCESS [0.154s] [INFO] helloworld-osgi - wrapper instructions ............ SUCCESS [0.049s] [INFO] helloworld-osgi - bundle instructions ............. SUCCESS [0.031s] [INFO] helloworld-osgi - imported bundles ................ SUCCESS [0.010s] [INFO] pl.jaceklaskowski.osgi.helloworld.api [pl.jaceklaskowski.osgi.helloworld] SUCCESS [33.105s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
Importing OSGi project to Eclipse IDE - mvn pax:eclipse
It's nearly impossible to go on developing OSGi bundles on the command line and no one or very few brave souls do it on a daily basis. That's where an IDE shines. Use mvn pax:eclipse to generate necessary project files for Eclipse.
$ mvn pax:eclipse -DdownloadSources [INFO] Scanning for projects... ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
Import the project into Eclipse with File > Import > Existing projects into Workspace and click Next >.
Select root directory - the directory of your OSGi project.
Press Finish.
You can now continue OSGi development from within Eclipse IDE. Happy hacking!
