The Maven Cookbook

1.3.1. Task

You created an OSGi project, now you want to see it running in an OSGi environment. You need to start an OSGi container and load imported bundles into the runtime environment.

1.3.2. Action

First, create an OSGi project by executing the commands in Section 1.2, “Generating an OSGi Project with Maven”. Once you do this, you have a structure that has been designed to support OSGi development with Maven. To start the Apache Felix container, run mvn install pax:provision from the osgi-project/ directory:

~/examples/osgi/osgi-project $ mvn install pax:provision
[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] [pax:provision]
[INFO] ~~~~~~~~~~~~~~~~~~~
[INFO]  No bundles found! 
[INFO] ~~~~~~~~~~~~~~~~~~~
    ______  ________  __  __
   / __  / /  __   / / / / /
  /  ___/ /  __   / _\ \ _/
 /  /    /  / /  / / _\ \
/__/    /__/ /__/ /_/ /_/

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]
 -> Preparing framework [Felix 1.8.0]
 -> Downloading bundles...
 -> Using execution environment [J2SE-1.5]
 -> Runner has successfully finished his job!


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

->

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 running Apache Felix with the Pax plugin. For more information, see the Pax Construct Quickstart page.

1.3.3. Detail

When you started up Felix, notice that the line directly following the execution of the pax:provision goal says "No bundles found!". By running pax:provision, you've started the Felix OSGi service platform. Felix uses the configuration from a properties file and then scans two deploy-pom.xml files for bundles that it should download and install. Finding none, it presents a simple prompt and awaits orders. At this point, we have an empty container that isn't running any custom logic or downloading any OSGi bundles.

The first time you ran pax:provision, the Pax plugin created a runner directory under osgi-project which captures the configuration of the runtime environment. This runner directory contains the following files and directories:

osgi-project/runner/deploy-pom.xml: This POM file is generated using Pax-Construct, it contains some configuration parameters for the Apache Felix container.
osgi-project/runner/bundles: This directory contains OSGi bundles which have been downloaded for use in Apache Felix.
osgi-project/runner/felix: This directory contains the runtime files that are required for Apache Felix, this includes a config.ini file and a cache directory.

Once you have the console for Felix loaded, you can control the platform, load components from remote repositories, list all of the running components, and start and stop components. Try executing the command help to see a list of available commands:

-> help
bundlelevel <level> <id> ... | <id> - set or get bundle start level.
cd [<base-URL>]                     - change or display base URL.
exports <id> ...                    - list exported packages.
headers [<id> ...]                  - display bundle header properties.
help                                - display impl commands.
imports <id> ...                    - list imported packages.
install <URL> [<URL> ...]           - install bundle(s).
ps [-l | -s | -u]                   - list installed bundles.
refresh [<id> ...]                  - refresh packages.
requirers <id> ...                  - list requiring bundles.
requires <id> ...                   - list required bundles.
resolve [<id> ...]                  - attempt to resolve the specified bundles.
scr help                            - Declarative Services Runtime
services [-u] [-a] [<id> ...]       - list registered or used services.
shutdown                            - shutdown framework.
start [-t] <id> [<id> <URL> ...]    - start bundle(s).
startlevel [<level>]                - get or set framework start level.
stop [-t] <id> [<id> ...]           - stop bundle(s).
uninstall <id> [<id> ...]           - uninstall bundle(s).
update <id> [<URL>]                 - update bundle.
version                             - display version of framework.

If you execute the ps command, you can see a list of bundles with IDs that are running in the Felix container. You can start and stop bundles by running start and stop followed by the ID of the specific bundle you want to control. You can also install and uninstall bundles in the running container. Over the next few recipes we're going to fill in this picture a bit by wrapping existing JARs, importing existing OSGi bundles, and writing a custom OSGi service.

1.3.4. Resources