The Maven Cookbook

1.4.1. Task

You want to configure your OSGi runtime to load bundles on startup.

1.4.2. Action

Import OSGi bundles from the Maven repository. While the Maven repository wasn't designed for OSGi like the OSGi Bundle Repositoriy (OBR) repository format, it contains a few components which contain the appropriate metadata to be referenced as OSGi components. To configure your runtime environment to load these components at runtime, you will need to invoke the pax:import-bundle goal.

As shown in the following screen listing, you are going to import several OSGi bundles from the Maven repository. First you are going to install the Apache Felix Web Management Console and then you are going to install some of its requirements. To install the first OSGi bundle run the following command:

~/examples/osgi/osgi-project $ mvn pax:import-bundle \
    -DgroupId=org.apache.felix \
    -DartifactId=org.apache.felix.webconsole \
    -Dversion=1.2.8
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   org.sonatype.mcookbook.osgi-project (OSGi project)
[INFO]   osgi-project - plugin configuration
[INFO]   osgi-project - wrapper instructions
[INFO]   osgi-project - bundle instructions
[INFO]   osgi-project - imported bundles
[INFO] ------------------------------------------------------------------------
[INFO] Building org.sonatype.mcookbook.osgi-project (OSGi project)
[INFO]    task-segment: [pax:import-bundle] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] [pax:import-bundle]
[INFO] Importing Apache Felix Web Management Console to \
       org.sonatype.mcookbook.osgi-project.build:provision:pom:1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6 seconds
[INFO] Finished at: Mon Jul 13 18:30:37 CDT 2009
[INFO] Final Memory: 8M/16M
[INFO] ------------------------------------------------------------------------

After installing the Apache Felix Web Management console, you will need to install some of its prerequisites. The following commands install version 2.1 of the Java Servlet API, the Jetty HTTP server, and the org.apache.felix.scr component. As you can see, some of the OSGi bundle you are installing are simple libraries and APIs, while others are complex servers.

~/examples/osgi/osgi-project $ mvn pax:import-bundle \
    -DgroupId=org.apache.felix \
    -DartifactId=javax.servlet
    -Dversion=1.0.0
~/examples/osgi/osgi-project $ mvn pax:import-bundle \
    -DgroupId=org.apache.felix \
    -DartifactId=org.apache.felix.scr \
    -Dversion=1.0.8
~/examples/osgi/osgi-project $ mvn pax:import-bundle \
    -DgroupId=org.apache.felix \
    -DartifactId=org.apache.felix.http.jetty \
    -Dversion=1.0.1

Once you have bundled these OSGi bundles, you can start your runtme environment. Because the pax:import-bundle goal changes some of the POMs in your osgi-project, you will need to run mvn install before you can run mvn pax:provision. After importing bundles, they will appear in provision/pom.xml.

~/examples/osgi/osgi-project $ mvn install pax:provision
[INFO] [pax:provision]
[INFO] Installing ~/examples/osgi/osgi-project/runner/target/pom-transformed.xml 
       to ~/.m2/repository/org/sonatype/mcookbook/osgi-project/build/deployment/1.0-SNAPSHOT/\
          deployment-1.0-SNAPSHOT.pom
    ______  ________  __  __
   / __  / /  __   / / / / /
  /  ___/ /  __   / _\ \ _/
 /  /    /  / /  / / _\ \
/__/    /__/ /__/ /_/ /_/

Pax Runner (1.0.0) from OPS4J - http://www.ops4j.org
----------------------------------------------------

 -> Using config [classpath:META-INF/runner.properties]
 -> Using only arguments from command line
 -> Scan bundles from [~/examples/osgi/osgi-project/runner/deploy-pom.xml]
 -> Scan bundles from [scan-pom:file:~/examples/osgi/osgi-project/runner/deploy-pom.xml]
 -> Provision bundle [mvn:org.apache.felix/org.apache.felix.webconsole/1.2.8, 
at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [mvn:org.apache.felix/javax.servlet/1.0.0, at default start 
level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [mvn:org.apache.felix/org.apache.felix.http.jetty/1.0.1, 
at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [mvn:org.apache.felix/org.apache.felix.scr/1.0.8, at default 
start level, bundle will be started, bundle will be loaded from the cache]
 -> Preparing framework [Felix 1.8.0]
 -> Downloading bundles...
 -> mvn:org.apache.felix/org.apache.felix.webconsole/1.2.8 : 102399 bytes 
 -> mvn:org.apache.felix/javax.servlet/1.0.0 : 30450 bytes @ [ 10150kBps ]
 -> mvn:org.apache.felix/org.apache.felix.http.jetty/1.0.1 : 102399 bytes @ 
 -> mvn:org.apache.felix/org.apache.felix.scr/1.0.8 : 112058 bytes @ [ 8619kBps ]
 -> Using execution environment [J2SE-1.5]
 -> Runner has successfully finished his job!


Welcome to Felix.
=================

-> org.mortbay.log:Logging to org.mortbay.log via org.apache.felix.http.jetty.LogServiceLog
org.mortbay.log:Init SecureRandom.
org.mortbay.log:started org.mortbay.jetty.servlet.HashSessionIdManager@34a33d
org.mortbay.log:started org.mortbay.jetty.servlet.HashSessionManager@46ac5a
org.mortbay.log:starting OsgiServletHandler@dd7786
org.mortbay.log:started OsgiServletHandler@dd7786
org.mortbay.log:starting SessionHandler@d23e75
org.mortbay.log:started SessionHandler@d23e75
org.mortbay.log:starting org.mortbay.jetty.servlet.Context@9deddb{/,null}
org.mortbay.log:starting ErrorHandler@28bda
org.mortbay.log:started ErrorHandler@28bda
org.mortbay.log:started org.mortbay.jetty.servlet.Context@9deddb{/,null}
org.mortbay.log:jetty-6.1.x
org.mortbay.log:started Realm[OSGi HTTP Service Realm]==[]
org.mortbay.log:started org.mortbay.thread.QueuedThreadPool@f13b08
org.mortbay.log:starting Server@5a936b
org.mortbay.log:started org.mortbay.jetty.nio.SelectChannelConnector$1@9576c3
org.mortbay.log:Started SelectChannelConnector@0.0.0.0:8080
org.mortbay.log:started SelectChannelConnector@0.0.0.0:8080
org.mortbay.log:started Server@5a936b
org.mortbay.log:started /system/console/*
org.mortbay.log:started /system/console/res

After running mvn pax:provision, you have an instance of Felix that is running the Apache Felix Web Management Console application. Fire up a web brower, and go to http://localhost:8080/system/console to load the interface. The default administrative username and password is admin/admin.

Figure 1.2. Apache Felix Web Management Console

Note

Instead of executing these goals manually, you can also download and install the Pax-Construct scripts which can be used to automate the process of importing bundles with the Pax plugin. For more information, see the Pax Construct Quickstart page.

1.4.3. Detail

Once you start the web management console for Apache Felix, you can start to manage the installed bundles. You can start and stop bundles via the interface, and you can install bundles from remote repositories. If you prefer to use the shell interface from the previous recipe, click on the Shell interface and you can enter in any of the commands you used at the command-line Felix management console as shown in Figure 1.3, “Running the Apache Felix Shell via the Administrative Web Console”.

Figure 1.3. Running the Apache Felix Shell via the Administrative Web Console

You can manage Felix interactions with events and repositories, and you can also restart, stop, and change the default run levels. Clicking on the "System Information" tab will also allow you to get some statistics about the runtime container as shown in Figure 1.4, “Managing the Apache Felix via System Information”.

Figure 1.4. Managing the Apache Felix via System Information

When we imported these bundles into the project, they were added to the provision/pom.xml file, and we had to install all of a bundle's dependencies one by one. Instead of listing out each of bundle's dependencies on the command-line, we can tell the Pax plugin to import transitive bundle dependencies and optional bundles. The following command line will instruct the Pax plugin to install a bundle's full compile and runtime dependencies in provision/pom.xml.

~/examples/osgi/osgi-project $ mvn pax:import-bundle \
                                        -DgroupId=org.apache.felix \
                                        -DartifactId=org.apache.felix.http.jetty \
                                        -Dversion=1.0.1 \
                                        -DimportTransitive=true \
                                        -DimportOptional=true \
                                        -DwidenScope=true

The importTransitive and importOptional options tell the Pax plugin to look at the OBR metadata to find bundle dependencies. The widenScope parameter tells the Pax plugin to install all compile and runtime dependencies as bundles in provision/pom.xml.

1.4.4. Resources