Fuse ESB 4 still supports JBI, as described in Using Java Business Integration. However, because Fuse ESB 4 is based on OSGi, it provides additional flexibility. Fuse ESB 4 has the following layered architecture:

Figure 1.1 shows the architecture of Fuse ESB kernel.

Figure 1.1.  Fuse ESB kernel Architecture

Fuse ESB kernel is based on Apache Karaf, a powerful, lightweight, OSGi-based runtime container for deploying and managing bundles to facilitate componentization of applications. Fuse ESB kernel also provides native OS integration and can be integrated into the operating system as a service so that the lifecycle is bound to the operating system.

As shown in Figure 1.1, Fuse ESB kernel extends the OSGi layers with:

The OSGi Alliance is an independent organization responsible for defining the features and capabilities of the OSGi Service Platform Release 4. The OSGi Service Platform is a set of open specifications that simplify building, deploying, and managing complex software applications.

OSGi technology is often referred to as the dynamic module system for Java. OSGi is a framework for Java that uses bundles to modularly deploy Java components and handle dependencies, versioning, classpath control, and class loading. OSGi's lifecycle management allows you to load, start, and stop bundles without shutting down the JVM.

OSGi provides the best runtime platform for Java, a superior class loading architecture, and a registry for services. Bundles can export services, run processes, and have their dependencies managed. Each bundle can have its requirements managed by the OSGi container.

Fuse ESB kernel uses Equinox as its default OSGi implementation. Fuse ESB kernel can also use any standard OSGi container, such as Apache Felix. The framework layers form the container where you install bundles. The framework manages the installation and updating of bundles in a dynamic, scalable manner, and manages the dependencies between bundles and services.

As shown in Figure 1.1, the OSGi framework contains the following:

Each layer in the framework depends on the layer beneath it. For example, the lifecycle layer requires the module layer. The module layer can be used without the lifecycle and service layers.

An OSGi service is a Java class or service interface with service properties defined as name/value pairs. The service properties differentiate among service providers that provide services with the same service interface.

An OSGi service is defined semantically by its service interface, and it is implemented as a service object. A service's functionality is defined by the interfaces it implements. Thus, different applications can implement the same service.

Service interfaces allow bundles to interact by binding interfaces, not implementations. A service interface should be specified with as few implementation details as possible.

In the OSGi framework, the service layer provides communication between bundles and their contained components using the publish, find, and bind service model. The service layer contains a service registry where:

Services are owned by, and run within, a bundle. The bundle registers an implementation of a service with the framework service registry under one or more Java interfaces. Thus, the service’s functionality is available to other bundles under the control of the framework, and other bundles can look up and use the service. Lookup is performed using the Java interface and service properties.

Each bundle can register multiple services in the service registry using the fully qualified name of its interface and its properties. Bundles use names and properties with LDAP syntax to query the service registry for services.

A bundle is responsible for runtime service dependency management activities including publication, discovery, and binding. Bundles can also adapt to changes resulting from the dynamic availability (arrival or departure) of the services that are bound to the bundle.

Service interfaces are implemented by objects created by a bundle. Bundles can:

The OSGi framework provides an event notification mechanism so service requesters can receive notification events when changes in the service registry occur. These changes include the publication or retrieval of a particular service and when services are registered, modified, or unregistered.

The OSGi framework services are described in detail in separate chapters in the OSGi Service Platform Release 4 specification available from the release 4 download page on the OSGi Alliance web site.

In addition to the OSGi framework services, the OSGi Alliance defines a set of optional, standardized compendium services. The OSGi compendium services provide APIs for tasks such as logging and preferences. These services are described in the OSGi Service Platform, Service Compendium available from the release 4 download page on the OSGi Alliance Web site.

The Configuration Admin compendium service is like a central hub that persists configuration information and distributes it to interested parties. The Configuration Admin service specifies the configuration information for deployed bundles and ensures that the bundles receive that data when they are active. The configuration data for a bundle is a list of name-value pairs. See Fuse ESB kernel.

With OSGi, you modularize applications into bundles. Each bundle is a tightly coupled, dynamically loadable collection of classes, JARs, and configuration files that explicitly declare any external dependencies. In OSGi, a bundle is the primary deployment format. Bundles are applications that are packaged in JARs, and can be installed, started, stopped, updated, and removed.

OSGi provides a dynamic, concise, and consistent programming model for developing bundles. Development and deployment are simplified by decoupling the service's specification (Java interface) from its implementation.

The OSGi bundle abstraction allows modules to share Java classes. This is a static form of reuse. The shared classes must be available when the dependent bundle is started.

A bundle is a JAR file with metadata in its OSGi manifest file. A bundle contains class files and, optionally, other resources and native libraries. You can explicitly declare which packages in the bundle are visible externally (exported packages) and which external packages a bundle requires (imported packages).

The module layer handles the packaging and sharing of Java packages between bundles and the hiding of packages from other bundles. The OSGi framework dynamically resolves dependencies among bundles. The framework performs bundle resolution to match imported and exported packages. It can also manage multiple versions of a deployed bundle.

Figure 1.2 shows an overview of the OSGi transaction architecture in Fuse ESB. The core of the architecture is a JTA transaction manager based on Apache Geronimo, which exposes various transaction interfaces as OSGi services.

Figure 1.2. OSGi Transaction Architecture

The JTA Transaction Services Specification section of the OSGi Service Platform Enterprise Specification describes the kind of transaction support that can (optionally) be provided by an OSGi container. Essentially, OSGi mandates that the transaction service is accessed through the Java Transaction API (JTA).

The transaction service exports the following JTA interfaces as OSGi services (the JTA services):

Only one JTA provider should be made available in an OSGi container. In other words, the JTA services are registered only once and the objects obtained by importing references to the JTA services must be unique.

The Fuse ESB transaction service exports the following additional interfaces as OSGi services:

By obtaining a reference to the PlatformTransactionManager OSGi service, it is possible to integrate application bundles written using the Spring transaction API into the Fuse ESB transaction architecture.

Fuse ESB provides an OSGi-compliant implementation of the transaction service in the following bundle (which is installed in the OSGi container by default):

org.apache.aries.transaction.manager

The Fuse ESB transaction bundle exports exports a variety of transaction interfaces as OSGi services (making them available to other bundles in the container), as follows:

The PlatformTransactionManager OSGi service and the JTA services access the same underlying transaction manager.

The underlying implementation of the Fuse ESB transaction service is provided by the Apache Geronimo transaction manager. Apache Geronimo is a full implementation of a J2EE server and, as part of the J2EE implementation, Geronimo has developed a sophisticated transaction manager with the following features:

The transaction recovery feature depends on a transaction log, which records the status of all pending transactions in persistent storage.

The implementation of the transaction log is provided by HOWL, which is a high speed persistent logger that is optimized for XA transaction logs.

Normally, it is recommended that application bundles access the transaction service through the JTA interface. To use the transaction service in a JTA-based application bundle, import the relevant JTA service as an OSGi service and use the JTA service to begin, commit, or rollback transactions.

If you have already implemented an application bundle using the Spring transaction API, you might find it more convenient to access the transaction service through the Spring API (represented by the PlatformTransactionManager Java interface). This means that you are able to deploy the same source code either in a pure Spring container or in an OSGi container, by changing only the configuration snippet that obtains a reference to the transaction service.

In order to enlist multiple resources in the same transaction (where a transaction is committed through the 2-phase commit protocol), it is necessary for each participating resource to provide an XA switch. An XA switch is an object that enables the transaction manager to control a resource manager through the XA interface, javax.transaction.xa.XAResource.

The JTA provides a method for enlisting XAResource objects in the current transaction. Using this approach, it is possible to enlist multiple XA resources in the current transaction.

The standard JTA approach to enlisting XA resources is to add the XA resource to the current javax.transaction.Transaction object (representing the current transaction). In other words, you must explicitly enlist an XA resource every time a new transaction starts.

If you are familiar with how transactions work in J2EE containers, you might find this approach surprising: a J2EE container automatically enlists the relevant XA resource in the current transaction whenever you access a data source. In contrast to the J2EE approach, however, the OSGi container does not automatically enlist XA resources in the current transaction. You must write the code to enlist the XA resources yourself or implement a custom wrapper layer.

In the case of JMS XA resources, Fuse Message Broker provides an XA pool wrapper class that implements auto-enlistment for you. Use the following JMS connection factory class:

Fuse Message Broker supports the standard JMS framework for managing transactions. The approach to managing transactions in JMS depends on whether you use local transactions (where the broker is the only participating resource) or global transactions (where multiple resources participate in the transaction), as follows:

Through the ActiveMQXAConnectionFactory JMS connection factory, Fuse Message Broker can provide an XA resource that represents the underlying message broker. This means that messages will not be added to or removed from the broker's persistent storage, unless the current transaction completes successfully. The following broker persistence layers provide full support for the XA protocol (including a persistent transaction log that enables recovery):

To obtain a reference to the Fuse Message Broker XA resource, you must use the ActiveMQXAConnectionFactory JMS connection factory to access the broker.

Fuse Mediation Router provides a Camel JMS component, which is capable of integrating with the JTA transaction service with full support for XA transactions. In order to support XA transactions, you must configure the Camel JMS component's JMS connection factory and transaction manager as follows:

In principle, you can replace the default transaction manager with an alternative transaction manager, but this requires you to write a significant amount of custom code. If you want to replace the Geronimo transaction manager with a different transaction manager implementation, you could do so as follows:

The following specifications are relevant to the transaction architecture in Fuse ESB:

One of the most important principles of the Maven build system is that there are standard locations for all of the files in the Maven project. There are several advantages to this principle. One advantage is that Maven projects normally have an identical directory layout, making it easy to find files in a project (once you are familiar with the standard layout). Another advantage is that the various tools integrated with Maven need almost no initial configuration. For example, the Java compiler knows that it should compile all of the source files under src/main/java and put the results into target/classes.

Example 2.1 shows the elements of the standard Maven directory layout that are relevant to building OSGi bundle projects. In addition, the standard locations for Spring-DM and Blueprint configuration files (which are not defined by Maven) are also shown.

ProjectDir/
    pom.xml
    src/
        main/
            java/
                ...
            resources/
                META-INF/
                    spring/
                        *.xml
                OSGI-INF/
                    blueprint/
                        *.xml
        test/
            java/
            resources/
    target/
        ...

The pom.xml file is the Project Object Model (POM) for the current project, which contains a complete description of how to build the current project. A pom.xml file can be completely self-contained, but frequently (particular for more complex Maven projects) it can import settings from a parent POM file.

The src/ directory contains all of the code and resource files that you will work on while developing the project.

The target/ directory contains the result of the build (typically a JAR file), as well as all all of the intermediate files generated during the build. For example, after performing a build, the target/classes/ directory will contain a copy of the resource files and the compiled Java classes.

The main/ directory contains all of the code and resources needed for building the artifact.

The test/ directory contains all of the code and resources for running unit tests against the compiled artifact.

The java/ directory contains Java source code (*.java files) with the standard Java directory layout (that is, where the directory pathnames mirror the Java package names, with / in place of the . character). The src/main/java/ directory contains the bundle source code and the src/test/java/ directory contains the unit test source code.

If you have any configuration files, data files, or Java properties to include in the bundle, these should be placed under the src/main/resources/ directory. The files and directories under src/main/resources/ will be copied into the root of the JAR file that is generated by the Maven build process.

The files under src/test/resources/ are used only during the testing phase and will not be copied into the generated JAR file.

By default, Fuse ESB installs and activates support for Spring Dynamic Modules (Spring DM), which integrates Spring with the OSGi container. This means that it is possible for you to include Spring configuration files, META-INF/spring/*.xml, in your bundle. One of the key consequences of having Spring DM enabled in the OSGi container is that the lifecycle of the Spring application context is automatically synchronized with the OSGi bundle lifecycle:

In practice, this means that you can treat your Spring-enabled bundle as if it is being deployed in a Spring container. Using Spring DM, the features of the OSGi container and a Spring container are effectively merged. In addition, Spring DM provides additional features to support the OSGi container environment—some of these features are discussed in Deploying an OSGi Service.

OSGi R4.2 defines a blueprint container, which is effectively a standardized version of Spring DM. Fuse ESB has built-in support for the blueprint container, which you can enable simply by including blueprint configuration files, OSGI-INF/blueprint/*.xml, in your project. For more details about the blueprint container, see Deploying an OSGi Service.

The simplest way to get started with Maven is to generate a new project using a Maven archetype. This section describes how to set up Maven to use the Fuse ESB archetypes, which can generate starting points for different kinds of bundle application.

In order to build a project using Maven, you must have the following prerequisites:

In order to access artifacts from the ESB Maven repository, you need to add the fusesource repository to Maven's settings.xml file. Maven looks for your settings.xml file in the following standard location:

If there is currently no settings.xml file at this location, you need to create a new settings.xml file. Modify the settings.xml file by adding the repository element for fusesource, as shown in bold text in the following example:

<settings>
    <profiles>
        <profile>
            <id>my-profile</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
                <repository>
                    <id>fusesource</id>
                    <url>http://repo.fusesource.com/maven2</url>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
               <repository>
                    <id>fusesource.snapshot</id>
                    <url>http://repo.fusesource.com/maven2-snapshot</url>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                    <releases>
                        <enabled>false</enabled>
                    </releases>
                </repository>
                <repository>
                    <id>apache-public</id>
                    <url>https://repository.apache.org/content/groups/public/</url>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
                ...
            </repositories>
        </profile>
    </profiles>
    ...
</settings>

The preceding example also shows repository element for the following repositories:

The basic building block in the Maven build system is an artifact. When using Maven to build an OSGi project, there is a natural mapping between an OSGi bundle and a Maven artifact: a bundle is simply an artifact whose packaging type is set to bundle.

A key aspect of Maven functionality is the ability to locate artifacts and manage the dependencies between them. Maven defines the location of an artifact using the system of Maven coordinates, which uniquely define the location of a particular artifact. A basic coordinate tuple has the form, {groupId, artifactId, version}. Sometimes Maven augments the basic set of coordinates with the additional coordinates, packaging and classifier. A tuple can be written with the basic coordinates, or with the additional packaging coordinate, or with the addition of both the packaging and classifier coordinates, as follows:

groupdId:artifactId:version
groupdId:artifactId:packaging:version
groupdId:artifactId:packaging:classifier:version

Each coordinate can be explained as follows:

The group ID, artifact ID, packaging, and version are defined by the corresponding elements in an artifact's POM file. For example:

<project ... >
  ...
  <groupId>org.fusesource.example</groupId>
  <artifactId>bundle-demo</artifactId>
  <packaging>bundle</packaging>
  <version>1.0-SNAPSHOT</version>
  ...
</project>

For example, to define a dependency on the preceding artifact, you could add the following dependency element to a POM:

<project ...>
  ...
  <dependencies>
    <dependency>
      <groupId>org.fusesource.example</groupId>
      <artifactId>bundle-demo</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
  ...
</project>

To help you get started quickly, you can invoke a Maven archetype to generate the initial outline of a Maven project (a Maven archetype is analogous to a project wizard). The following Maven archetypes can generate projects for building OSGi bundles:

The Fuse Service Framework code-first archetype creates a project for building a service from Java. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-cxf-code-first-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

The Fuse Service Framework WSDL-first archetype creates a project for building a service from WSDL. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-cxf-wsdl-first-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

The Fuse Mediation Router OSGi archetype creates a project for building a route that can be deployed into the OSGi container. To generate a Maven project with the coordinates, GroupId:ArtifactId:Version, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-camel-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=GroupId
-DartifactId=ArtifactId
-Dversion=Version

By default, the preceding archetypes create a project in a new directory, whose names is the same as the specified artifact ID, ArtifactId. To build the bundle defined by the new project, open a command prompt, go to the project directory (that is, the directory containing the pom.xml file), and enter the following Maven command:

mvn install

The effect of this command is to compile all of the Java source files, to generate a bundle JAR under the ArtifactId/target directory, and then to install the generated JAR in the local Maven repository.

If you already have a Maven project and you want to modify it so that it generates an OSGi bundle, perform the following steps:

Configure Maven to generate an OSGi bundle by changing the package type to bundle in your project's pom.xml file. Change the contents of the packaging element to bundle, as shown in the following example:

<project ... >
  ...
  <packaging>bundle</packaging>
  ...
</project>

The effect of this setting is to select the Maven bundle plug-in, maven-bundle-plugin, to perform packaging for this project. This setting on its own, however, has no effect until you explicitly add the bundle plug-in to your POM.

To add the Maven bundle plug-in, copy and paste the following sample plugin element into the project/build/plugins section of your project's pom.xml file:

<project ... >
  ...
  <build>
    <defaultGoal>install</defaultGoal>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
            <Import-Package>*</Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Where the bundle plug-in is configured by the settings in the instructions element. For a general guide to customizing bundle instructions, see Configuring the Bundle Plug-In, and for specific recommendations, see Packaging a Web Service in a Bundle and Packaging Routes in a Bundle.

It is almost always necessary to specify the JDK version in your POM file. If your code uses any modern features of the Java language—such as generics, static imports, and so on—and you have not customized the JDK version in the POM, Maven will fail to compile your source code. It is not sufficient to set the JAVA_HOME and the PATH environment variables to the correct values for your JDK, you must also modify the POM file.

To configure your POM file, so that it accepts the Java language features introduced in JDK 1.5, add the following maven-compiler-plugin plug-in settings to your POM (if they are not already present):

<project ... >
  ...
  <build>
    <defaultGoal>install</defaultGoal>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source>
          <target>1.5</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

If you are using JDK 1.6, you can change the contents of the source element and the target element to 1.6. But this has the drawback that you would be unable to deploy the artifact on JDK 1.5. Typically, it is more convenient to build on JDK 1.5, which produces an artifact that can be deployed either on JDK 1.5 or on JDK 1.6.

A bundle plug-in requires very little information to function. All of the required properties use default settings to generate a valid OSGi bundle.

While you can create a valid bundle using just the default values, you will probably want to modify some of the values. You can specify most of the properties inside the plug-in's instructions element.

Some of the commonly used configuration properties are:

To specify your own value for the bundle's symbolic name, add a Bundle-SymbolicName child in the plug-in's instructions element, as shown in Example 2.2.

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
     ...
    </instructions>
  </configuration> 
</plugin>

To specify your own value for the bundle's name, add a Bundle-Name child to the plug-in's instructions element, as shown in Example 2.3.

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Name>JoeFred</Bundle-Name>
     ...
    </instructions>
  </configuration> 
</plugin>

To specify your own value for the bundle's version, add a Bundle-Version child to the plug-in's instructions element, as shown in Example 2.4.

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Version>1.0.3.1</Bundle-Version>
     ...
    </instructions>
  </configuration> 
</plugin>

The Private-Package element works similarly to the Export-Package element in that you specify a list of packages to be included in the bundle. The bundle plug-in uses the list to find all classes on the project's classpath that are to be included in the bundle. These packages are packaged in the bundle, but not exported (unless they are also selected by the Export-Package instruction).

Example 2.5 shows the configuration for including a private package in a bundle

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
     ...
    </instructions>
  </configuration> 
</plugin>

To specify a list of packages to be imported by the bundle, add an Import-Package child to the plug-in's instructions element. The syntax for the package list is the same as for the Export-Package element and the Private-Package element.

Example 2.6 shows the configuration for specifying the packages imported by a bundle

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Import-Package>javax.jws,
         javax.wsdl,
         org.apache.cxf.bus,
         org.apache.cxf.bus.spring,
         org.apache.cxf.bus.resource,
         org.apache.cxf.configuration.spring,
         org.apache.cxf.resource,
         org.springframework.beans.factory.config,
         *
     </Import-Package>
     ...
   </instructions>
  </configuration> 
</plugin>

For more information on configuring a bundle plug-in, see:

Fuse ESB kernel monitors JAR files in the InstallDir/deploy directory and hot deploys everything in this directory. Each time a JAR file is copied to this directory, it is installed in the runtime and also started. You can subsequently update or delete the JARs, and the changes are handled automatically.

For example, if you have just built the bundle, ProjectDir/target/foo-1.0-SNAPSHOT.jar, you can deploy this bundle by copying it to the InstallDir/deploy directory as follows (assuming you are working on a UNIX platform):

% cp ProjectDir/target/foo-1.0-SNAPSHOT.jar InstallDir/deploy

You can manually deploy and undeploy bundles by issuing commands at the Fuse ESB console.

Use the osgi:install command to install one or more bundles in the OSGi container. This command has the following syntax:

osgi:install [-s] [--start] [--help] UrlList

Where UrlList is a whitespace-separated list of URLs that specify the location of each bundle to deploy. The following command arguments are supported:

For example, to install and start the bundle, ProjectDir/target/foo-1.0-SNAPSHOT.jar, enter the following command at the Karaf console prompt:

osgi:install -s file:ProjectDir/target/foo-1.0-SNAPSHOT.jar

To uninstall a bundle, you must first obtain its bundle ID using the osgi:list command. You can then uninstall the bundle using the osgi:uninstall command (which takes the bundle ID as its argument).

For example, if you have already installed the bundle named named A Camel OSGi Service Unit, entering osgi:list at the console prompt might produce output like the following:

...
[ 175] [Active     ] [            ] [Started] [   60] ServiceMix :: FTP (2009.02.0.psc-01-00RC1)
[ 181] [Resolved   ] [            ] [       ] [   60] A Camel OSGi Service Unit (1.0.0.SNAPSHOT)

You can now uninstall the bundle with the ID, 181, by entering the following console command:

osgi:uninstall 181

When specifying the location URL to the osgi:install command, you can use any of the URL schemes supported by Fuse ESB, which includes the following scheme types:

When you install a bundle using the osgi:install command (without the -s flag), the kernel installs the specified bundle and attempts to put it into the resolved state. If the resolution of the bundle fails for some reason (for example, if one of its dependencies is unsatisfied), the kernel leaves the bundle in the installed state.

At a later time (for example, after you have installed missing dependencies) you can attempt to move the bundle into the resolved state by invoking the osgi:resolve command, as follows:

osgi:resolve 181

Where the argument (181, in this example) is the ID of the bundle you want to resolve.

You can start one or more bundles (from either the installed or the resolved state) using the osgi:start command. For example, to start the bundles with IDs, 181, 185, and 186, enter the following console command:

osgi:start 181 185 186

You can stop one or more bundles using the osgi:stop command. For example, to stop the bundles with IDs, 181, 185, and 186, enter the following console command:

osgi:stop 181 185 186

You can restart one or more bundles (that is, moving from the started state to the resolved state, and then back again to the started state) using the osgi:restart command. For example, to restart the bundles with IDs, 181, 185, and 186, enter the following console command:

osgi:restart 181 185 186

A start level is associated with every bundle. The start level is a positive integer value that controls the order in which bundles are activated/started. Bundles with a low start level are started before bundles with a high start level. Hence, bundles with the start level, 1, are started first and bundles belonging to the kernel tend to have lower start levels, because they provide the prerequisites for running most other bundles.

Typically, the start level of user bundles is 60 or higher.

Use the osgi:bundle-level command to set the start level of a particular bundle. For example, to configure the bundle with ID, 181, to have a start level of 70, enter the following console command:

osgi:bundle-level 181 70

The OSGi container itself has a start level associated with it and this system start level determines which bundles can be active and which cannot: only those bundles whose start level is less than or equal to the system start level can be active.

To discover the current system start level, enter osgi:start-level in the console, as follows:

karaf@root> osgi:start-level
Level 100

If you want to change the system start level, provide the new start level as an argument to the osgi:start-level command, as follows:

osgi:start-level 200

Essentially, a feature is created by adding a new feature element to a special kind of XML file, known as a feature repository. To create a feature, perform the following steps:

If you have not already defined a custom feature repository, you can create one as follows. Choose a convenient location for the feature repository on your file system—for example, C:\Projects\features.xml—and use your favorite text editor to add the following lines to it:

<?xml version="1.0" encoding="UTF-8"?>
<features name="CustomRepository">
</features>

Where you can optionally specify a name for the repository, CustomRepository, by setting the name attribute. The default repository name is repo-0.

To add a feature to the custom feature repository, insert a new feature element as a child of the root features element. You must give the feature a name and you can list any number of bundles belonging to the feature, by inserting bundle child elements. For example, to add a feature named example-camel-bundle containing the single bundle, C:\Projects\camel-bundle\target\camel-bundle-1.0-SNAPSHOT.jar, add a feature element as follows:

<?xml version="1.0" encoding="UTF-8"?>
<features>
  <feature name="example-camel-bundle">
    <bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
  </feature>
</features>

The contents of the bundle element can be any valid URL, giving the location of a bundle (see Appendix A). You can optionally specify a version attribute on the feature element, to assign a non-zero version to the feature (you can then specify the version as an optional argument to the features:install command).

To check whether the features service successfully parses the new feature entry, enter the following pair of console commands:

karaf@root> features:refreshUrl
karaf@root> features:list
...
[uninstalled] [0.0.0                 ] example-camel-bundle                 repo-0
...

The features:list command typically produces a rather long listing of features, but you should be able to find the entry for your new feature (in this case, example-camel-bundle) by scrolling back through the listing. The features:refreshUrl command forces the kernel to reread all the feature repositories: if you did not issue this command, the kernel would not be aware of any recent changes that you made to any of the repositories (in particular, the new feature would not appear in the listing).

To avoid scrolling through the long list of features, you can grep for the example-camel-bundle feature as follows:

karaf@root> features:list | grep example-camel-bundle
[uninstalled] [0.0.0                 ] example-camel-bundle                 repo-0

Where the grep command (a standard UNIX pattern matching utility) is built into the shell, so this command also works on Windows platforms.

In order to make the new feature repository available to Apache Karaf, you must add the feature repository using the features:addUrl console command. For example, to make the contents of the repository, C:\Projects\features.xml, available to the kernel, you would enter the following console command:

features:addUrl file:C:/Projects/features.xml

Where the argument to features:addUrl can be specified using any of the supported URL formats (see Appendix A).

You can check that the repository's URL is registered correctly by entering the features:listUrl console command, to get a complete listing of all registered feature repository URLs, as follows:

karaf@root> features:listUrl
mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0-fuse-01-00/xml/features
mvn:org.apache.servicemix.camel/features/4.4.1-fuse-00-08/xml/features
file:C:/Projects/features.xml
mvn:org.apache.ode/ode-jbi-karaf/1.3.3-fuse-01-00/xml/features
mvn:org.apache.felix.karaf/apache-felix-karaf/1.2.0-fuse-01-00/xml/features
mvn:org.apache.servicemix/apache-servicemix/4.4.1-fuse-00-08/xml/features

If your feature depends on other features, you can specify these dependencies by adding feature elements as children of the original feature element. Each child feature element contains the name of a feature on which the current feature depends. When you deploy a feature with dependent features, the dependency mechanism checks whether or not the dependent features are installed in the container. If not, the dependency mechanism automatically installs the missing dependencies (and any recursive dependencies).

For example, for the custom Fuse Mediation Router feature, example-camel-bundle, you can specify explicitly which standard Fuse Mediation Router features it depends on. This has the advantage that the application could now be successfully deployed and run, even if the OSGi container does not have the required features pre-deployed. For example, you can define the example-camel-bundle feature with Apache Camel dependencies as follows:

<?xml version="1.0" encoding="UTF-8"?>
<features>
  <feature name="example-camel-bundle">
    <bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
    <feature version="4.4.1-fuse-00-08">camel-core</feature>
    <feature version="4.4.1-fuse-00-08">camel-spring-osgi</feature>
    <feature version="4.4.1-fuse-00-08">servicemix-camel</feature>
  </feature>
</features>

Specifying the version attribute is optional. When present, it enables you to select the specified version of the feature.

If your application uses the OSGi Configuration Admin service, you can specify configuration settings for this service using the config child element of your feature definition. For example, to specify that the prefix property has the value, MyTransform, add the following config child element to your feature's configuration:

<?xml version="1.0" encoding="UTF-8"?>
<features>
  <feature name="example-camel-bundle">
    <config name="org.fusesource.fuseesb.example">
      prefix=MyTransform
    </config>
  </feature>
</features>

Where the name attribute of the config element specifies the persistent ID of the property settings (where the persistent ID acts effectively as a name scope for the property names). The content of the config element is parsed in the same way as a Java properties file.

The settings in the config element can optionally be overriden by the settings in the Java properties file located in the InstallDir/etc directory, which is named after the persistent ID, as follows:

InstallDir/etc/org.fusesource.fuseesb.example.cfg

As an example of how the preceding configuration properties can be used in practice, consider the following Spring XML file that accesses the OSGi configuration properties using Spring DM:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ctx="http://www.springframework.org/schema/context"
       xmlns:osgi="http://camel.apache.org/schema/osgi"
       xmlns:osgix="http://www.springframework.org/schema/osgi-compendium" ...>
    ...
    <bean id="myTransform" class="org.fusesource.fuseesb.example.MyTransform">
      <property name="prefix" value="${prefix}"/>
    </bean>
   
    <osgix:cm-properties id="preProps" persistent-id="org.fusesource.fuseesb.example">
        <prop key="prefix">DefaultValue</prop>
    </osgix:cm-properties>

    <ctx:property-placeholder properties-ref="preProps" />

</beans>

When this Spring XML file is deployed in the example-camel-bundle bundle, the property reference, ${prefix}, is replaced by the value, MyTransform, which is specified by the config element in the feature repository.

You can deploy a feature in one of the following ways:

After you have created a feature (by adding an entry for it in a feature repository and registering the feature repository), it is relatively easy to deploy the feature using the features:install console command. For example, to deploy the example-camel-bundle feature, enter the following pair of console commands:

karaf@root> features:refreshUrl
karaf@root> features:install example-camel-bundle

It is recommended that you invoke the features:refreshUrl command before calling features:install, in case any recent changes were made to the features in the feature repository which the kernel has not picked up yet. The features:install command takes the feature name as its argument (and, optionally, the feature version as its second argument).

To uninstall a feature, invoke the features:uninstall command as follows:

karaf@root> features:uninstall example-camel-bundle

You can hot deploy all of the features in a feature repository simply by copying the feature repository file into the InstallDir/deploy directory.

As it is unlikely that you would want to hot deploy an entire feature repository at once, it is often more convenient to define a reduced feature repository or feature descriptor, which references only those features you want to deploy. The feature descriptor has exactly the same syntax as a feature repository, but it is written in a different style. The difference is that a feature descriptor consists only of references to existing features from a feature repository.

For example, you could define a feature descriptor to load the example-camel-bundle feature as follows:

<?xml version="1.0" encoding="UTF-8"?>
<features name="CustomDescriptor">
  <repository>RepositoryURL</repository>
  <feature name="hot-example-camel-bundle">
    <feature>example-camel-bundle</feature>
  </feature>
</features>

The repository element specifies the location of the custom feature repository, RepositoryURL (where you can use any of the URL formats described in Appendix A). The feature, hot-example-camel-bundle, is just a reference to the existing feature, example-camel-bundle.

If you want to provision copies of the Apache Karaf for deployment on multiple hosts, you might be interested in adding a feature to the boot configuration, which determines the collection of features that are installed when Apache Karaf boots up for the very first time.

The configuration file, /etc/org.apache.felix.karaf.features.cfg, in your install directory contains the following settings:

...               
#
# Comma separated list of features repositories to register by default
#
featuresRepositories=mvn:org.apache.felix.karaf/apache-felix-karaf/1.1.0.3-fuse-SNAPSHOT/xml/features,
mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0-fuse-SNAPSHOT/xml/features,
mvn:org.apache.servicemix/apache-servicemix/4.2.0-fuse-SNAPSHOT/xml/features,
mvn:org.apache.camel.karaf/apache-camel/2.x-fuse-SNAPSHOT/xml/features,
mvn:org.apache.ode/ode-jbi-karaf/1.3.3-fuse-SNAPSHOT/xml/features

#
# Comma separated list of features to install at startup
#

# Will put these back in when we decide to include these components
# servicemix-smpp,servicemix-snmp,servicemix-vfs,

featuresBoot=activemq,activemq-broker,camel,jbi-cluster,web,servicemix-cxf-bc,servicemix-file,
servicemix-ftp,servicemix-http,servicemix-jms,servicemix-mail,servicemix-bean,servicemix-camel,
servicemix-cxf-se,servicemix-drools,servicemix-eip,servicemix-osworkflow,servicemix-quartz,
servicemix-scripting,servicemix-validation,servicemix-saxon,servicemix-wsn2005,camel-cxf,camel-jms

This configuration file has two properties:

You can modify the configuration to customize the features that are installed as Fuse ESB kernel starts up. You can also modify this configuration file, if you plan to distribute Fuse ESB kernel with pre-installed features.

The Bnd tool is a an open source utility for creating and diagnosing OSGi bundles. It has been developed by Peter Kriens and is freely downloadable from the aQute Web site (subject to an Apache version 2.0 open source license). The key feature of the Bnd tool is that it automatically generates Manifest headers for the OSGi bundle, thus relieving you of this tedious task. The main tasks that Bnd can perform are:

You have the option of invoking Bnd in any of the following ways: from the command line; as an Ant task; or through the Maven bundle plug-in, maven-bundle-plugin. In fact, the approach to building bundles described in Building Bundles with Maven is based on the Maven bundle plug-in and therefore, implicitly, is also based on the Bnd tool.

You can download Bnd from the aQute Web site at the following location:

http://www.aqute.biz/Code/Download#bnd

Download the Bnd JAR file, bnd-Version.jar, to a convenient location. There is no installation involved: the JAR file is all that you need to use the Bnd tool. For convenience, however, it is advisable to rename the JAR file to bnd.jar, so you won't have to do so much typing when you invoke it from the command line (for example, as in java -jar bnd.jar Cmd Options)

To learn more about the Bnd tool, consult the following references:

This section describes how to convert a vanilla JAR file into an OSGi bundle using the Bnd tool's wrap command. You can choose either to perform the conversion with default settings (which works in most cases) or to perform a custom conversion with the help of a Bnd properties file.

To demonstrate how to convert a plain JAR into a bundle, we will consider the example of the commons-logging-Version.jar, which is available from the Apache Commons project and can be downloaded from the following location:

http://commons.apache.org/downloads/download_logging.cgi

The Bnd print command is a useful diagnostic tool that displays most of the information about a JAR that is relevant to bundle creation. For example, to print the Manifest headers and package dependencies of the commons logging JAR, you can invoke the Bnd print command as follows:

java -jar bnd.jar print commons-logging-1.1.1.jar

The preceding command produces the following output:

[MANIFEST commons-logging-1.1.1.jar]
Archiver-Version                        Plexus Archiver
Build-Jdk                               1.4.2_16
Built-By                                dlg01
Created-By                              Apache Maven
Extension-Name                          org.apache.commons.logging
Implementation-Title                    Commons Logging
Implementation-Vendor                   Apache Software Foundation
Implementation-Vendor-Id                org.apache
Implementation-Version                  1.1.1
Manifest-Version                        1.0
Specification-Title                     Commons Logging
Specification-Vendor                    Apache Software Foundation
Specification-Version                   1.0
X-Compile-Source-JDK                    1.2
X-Compile-Target-JDK                    1.1

[IMPEXP]

[USES]
org.apache.commons.logging              org.apache.commons.logging.impl
org.apache.commons.logging.impl         javax.servlet
                                        org.apache.avalon.framework.logger
                                        org.apache.commons.logging
                                        org.apache.log
                                        org.apache.log4j
One error
1 : Unresolved references to [javax.servlet, org.apache.avalon.framework.logger,
 org.apache.log, org.apache.log4j] by class(es) on the Bundle-Classpath[Jar:comm
ons-logging-1.1.1.jar]: [org/apache/commons/logging/impl/AvalonLogger.class, org
/apache/commons/logging/impl/ServletContextCleaner.class, org/apache/commons/log
ging/impl/LogKitLogger.class, org/apache/commons/logging/impl/Log4JLogger.class]

From this output, you can see that the JAR does not define any bundle manifest headers. The output consists of the following sections:

To convert the plain commons logging JAR into an OSGi bundle, invoke the Bnd wrap command as follows:

java -jar bnd.jar wrap commons-logging-1.1.1.jar

The result of running this command is a bundle file, commons-logging-1.1.1.bar, which consists of the original JAR augmented by the Manifest headers required by a bundle.

To display the Manifest headers and package dependencies of the newly created bundle JAR, enter the following Bnd print command:

java -jar bnd.jar print commons-logging-1.1.1.bar

The preceding command should produce output like the following:

[MANIFEST commons-logging-1.1.1-bnd.jar]
Archiver-Version                        Plexus Archiver
Bnd-LastModified                        1263987809524
Build-Jdk                               1.4.2_16
Built-By                                dlg01
Bundle-ManifestVersion                  2
Bundle-Name                             commons-logging-1.1.1
Bundle-SymbolicName                     commons-logging-1.1.1
Bundle-Version                          0
Created-By                              1.5.0_08 (Sun Microsystems Inc.)
Export-Package                          org.apache.commons.logging;uses:="org.ap
ache.commons.logging.impl",org.apache.commons.logging.impl;uses:="org.apache.ava
lon.framework.logger,org.apache.commons.logging,org.apache.log4j,org.apache.log,
javax.servlet"
Extension-Name                          org.apache.commons.logging
Implementation-Title                    Commons Logging
Implementation-Vendor                   Apache Software Foundation
Implementation-Vendor-Id                org.apache
Implementation-Version                  1.1.1
Import-Package                          javax.servlet;resolution:=optional,org.a
pache.avalon.framework.logger;resolution:=optional,org.apache.commons.logging;re
solution:=optional,org.apache.commons.logging.impl;resolution:=optional,org.apac
he.log;resolution:=optional,org.apache.log4j;resolution:=optional
Manifest-Version                        1.0
Originally-Created-By                   Apache Maven
Specification-Title                     Commons Logging
Specification-Vendor                    Apache Software Foundation
Specification-Version                   1.0
Tool                                    Bnd-0.0.384
X-Compile-Source-JDK                    1.2
X-Compile-Target-JDK                    1.1


[IMPEXP]
Import-Package
  javax.servlet                         {resolution:=optional}
  org.apache.avalon.framework.logger    {resolution:=optional}
  org.apache.log                        {resolution:=optional}
  org.apache.log4j                      {resolution:=optional}
Export-Package
  org.apache.commons.logging
  org.apache.commons.logging.impl

[USES]
org.apache.commons.logging              org.apache.commons.logging.impl
org.apache.commons.logging.impl         javax.servlet
                                        org.apache.avalon.framework.logger
                                        org.apache.commons.logging
                                        org.apache.log
                                        org.apache.log4j

By default, the Bnd wrap command behaves as if it was configured to use the following Bnd property file:

Export-Package: * 
Import-Package: AllReferencedPackages

The result of this configuration is that the new bundle imports all of the packages referenced by the JAR (which is almost always what you need) and all of the packages defined in the JAR are exported. Sometimes you might want to hide some of the packages in the JAR, however, in which case you would need to define a custom property file.

If you want to have more control over the way the Bnd wrap command generates a bundle, you can define a Bnd properties file to control the conversion process. For a detailed description of the syntax and capabilities of the Bnd properties file, see the Bnd tool documentation.

For example, in the case of the commons logging JAR, you might decide to hide the org.apache.commons.logging.impl package, while exporting the org.apache.commons.logging package. You could do this by creating a Bnd properties file called commons-logging-1.1.1.bnd and inserting the following lines using a text editor:

version=1.1.1
Export-Package: org.apache.commons.logging;version=${version}
Private-Package: org.apache.commons.logging.impl
Bundle-Version: ${version}

Notice how a version number is assigned to the exported package by substituting the version variable (any properties starting with a lowercase letter are interpreted as variables).

To wrap a JAR file using the custom property file, specify the Bnd properties file using the -properties option of the wrap command. For example, to wrap the vanilla commons logging JAR using the instructions contained in the commons-logging-1.1.1.bnd properties file, enter the following command:

java -jar bnd.jar wrap -properties commons-logging-1.1.1.bnd commons-logging-1.1.1.jar

You also have the option of converting a JAR into a bundle using the wrap scheme, which can be prefixed to any existing URL format. The wrap scheme is also based on the Bnd utility.

The wrap scheme has the following basic syntax:

wrap:LocationURL

The wrap scheme can prefix any URL that locates a JAR. The locating part of the URL, LocationURL, is used to obtain the (non-bundlized) JAR and the URL handler for the wrap scheme then converts the JAR automatically into a bundle.

Because the wrap scheme is based on the Bnd utility, it uses exactly the same default properties to generate the bundle as Bnd does—see Default property file.

The following example shows how you can use a single console command to download the plain commons-logging JAR from a remote Maven repository, convert it into an OSGi bundle on the fly, and then install it and start it in the OSGi container:

karaf@root> osgi:install -s wrap:mvn:commons-logging/commons-logging/1.1.1

Example 5.1 shows how the example-jpa-osgi feature combines the mvn scheme and the wrap scheme in order to download the plain HyperSQL JAR file and convert it to an OSGi bundle on the fly.

<feature name="examples-jpa-osgi" version="4.4.1-fuse-00-08">
    <feature version="4.4.1-fuse-00-08">jpa-hibernate</feature>
    <bundle>wrap:mvn:hsqldb/hsqldb/1.8.0.7</bundle>
    <bundle>mvn:org.apache.servicemix.examples.jpa-osgi/wsdl-first-cxfbc-bundle/4.4.1-fuse-00-08</bundle>
    <bundle>mvn:org.apache.servicemix.examples.jpa-osgi/wsdl-first-cxfse-bundle/4.4.1-fuse-00-08</bundle>
</feature>

The wrap scheme is provided by the Pax project, which is the umbrella project for a variety of open source OSGi utilities. For full documentation on the wrap scheme, see the Wrap Protocol reference page.

To convert a WAR file into a bundle suitable for deployment in the OSGi container, add the war: prefix to the WAR URL. The PAX War URL handler acts as a wrapper, which adds the requisite manifest headers to the WAR file.

The war scheme has the following basic syntax:

war:LocationURL[?Options]

The location URL, LocationURL, can be any of the location URLs described in Appendix A (for example, an mvn: or a file: URL). Options can be appended to the URL in the following format:

?Option=Value&Option=Value&...

Or if the war URL appears in an XML file:

?Option=Value&Option=Value&...

If the WAR file is stored in a Maven repository, you can deploy it into the OSGi container using the osgi:install command, taking a war:mvn: URL as its argument. For example, to deploy the wicket-example WAR file from a Maven repository, where the application should be accessible from the wicket Web application context, enter the following console command:

karaf@root> install war:mvn:org.apache.wicket/wicket-examples/1.4.7/war?Web-ContextPath=wicket

Alternatively, if the WAR file is stored on the filesystem, you can deploy it into the OSGi container by specifying a war:file: URL. For example, to deploy the WAR file, wicket-example-1.4.6.war, enter the following console command:

karaf@root> install war:file://wicket-examples-1.4.7.war?Web-ContextPath=wicket

The WAR file is automatically installed into a Web container, which listens on the IP port 8181 by default, and the Web container uses the Web application context specified by the Web-ContextPath option. For example, the wicket-example WAR deployed in the preceding examples, would be accessible from the following URL:

http://localhost:8181/wicket

The PAX War URL handler converts a WAR file to a special kind of OSGi bundle, which includes additional Manifest headers to support WAR deployment (for example, the Web-ContextPath Manifest header). By default, the deployed WAR is configured as an isolated bundle (neither importing nor exporting any packages). This mimics the deployment model of a WAR inside a J2EE container, where the WAR is completely self-contained, including all of the JAR files it needs.

For details of the default conversion parameters, see Table A.2.

The PAX War URL handler is layered over Bnd. If you want to customize the bundle headers in the Manifest file, you can either add a Bnd instruction as a URL option or you can specify a Bnd instructions file for the War URL handler to use—for details, see War URL Handler.

In particular, you might sometimes find it necessary to customize the entry for the Bundle-ClassPath, because the default value of Bundle-ClassPath does not include all of the resources in the WAR file (see Table A.2).

Support for running WARs in the OSGi container is provided by the PAX WAR Extender, which monitors each bundle as it starts and, if the bundle contains a web.xml file, automatically deploys the WAR in a Web container. The War Protocol page has the original reference documentation for the War URL handler.

Fuse ESB automatically deploys WAR files into a Web container, which is implemented by the PAX Web library. You can configure the Web container through the OSGi Configuration Admin service.

The Web container uses the following configuration file:

EsbInstallDir/etc/org.ops4j.pax.web.cfg 

You must create this file, if it does not already exist in the EsbInstallDir/etc/ directory.

By default, the Web container listens on the IP port, 8181. You can change this value by editing the etc/org.ops4j.pax.web.cfg file and setting the value of the org.osgi.service.http.port property, as follows:

# Configure the Web container
org.osgi.service.http.port=8181

The Web container is also used for deploying the Fuse ESB Web console. The instructions for securing the Web container with SSL/TLS are identical to the instructions for securing the Web console with SSL/TLS. See ???? for details.

The properties that you can set in the Web container's configuration file are defined by the PAX Web library. You can set the following kinds of property:

If you want to deploy your routes in a blueprint configuration file, you must first install the camel-blueprint feature (it is not installed by default). To install the camel-blueprint feature, enter the following console command:

karaf@root> features:install camel-blueprint

If you have an existing Fuse Mediation Router XML configuration file, you can deploy the routes by copying the configuration file into the following hot deploy directory:

InstallDir/deploy

After deploying, the configured routes start up immediately.

For a detailed example of hot deployed routes, see JMS Endpoints in a Router Application.

You can hot deploy Fuse Mediation Router routes using either of the following types of configuration file:

You can deploy a camelContext using a Spring configuration file, where the root element is a Spring beans element and the camelContext element is a child of the beans element. In this case, the camelContext namespace must be http://camel.apache.org/schema/spring.

For example, the following Spring configuration defines a route that generates timer messages every two seconds, sending the messages to the ExampleRouter log (which get incorporated into the console log file, InstallDir/data/log/servicemix.log):

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       >

  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="timer://myTimer?fixedRate=true&amp;period=2000"/>
      <to uri="log:ExampleRouter"/>
    </route>
  </camelContext>

</beans>

It is not necessary to specify schema locations in the configuration. But if you are editing the configuration file with an XML editor, you might want to add the schema locations in order to support schema validation and content completion in the editor. For the preceding example, you could specify the schema locations as follows:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
    ...

Before deploying routes in a blueprint configuration file, check that the camel-blueprint feature is already installed.

You can deploy a camelContext using a blueprint configuration file, where the root element is blueprint and the camelContext element is a child of the blueprint element. In this case, the camelContext namespace must be http://camel.apache.org/schema/blueprint.

For example, the following blueprint configuration defines a route that generates timer messages every two seconds, sending the messages to the ExampleRouter log (which get incorporated into the console log file, InstallDir/data/log/servicemix.log):

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    >

  <camelContext xmlns="http://camel.apache.org/schema/blueprint">
    <route>
      <from uri="timer://myTimer?fixedRate=true&amp;period=2000"/>
      <to uri="log:ExampleRouter"/>
    </route>
  </camelContext>

</blueprint>

This section explains how to modify an existing Maven project for a Fuse Mediation Router application, so that the project generates an OSGi bundle suitable for deployment in the Fuse ESB OSGi container. To convert the Maven project, you need to modify the project POM file.

To configure a Maven POM file to generate a bundle, there are essentially two changes you need to make: change the POM's package type to bundle; and add the Maven bundle plug-in to your POM. For details, see Modifying an Existing Maven Project.

There are two kinds of file that you can use to configure your project:

If you decide to use the blueprint configuration, you can embed camelContext elements in the blueprint file, as described in Blueprint configuration file.

If you decide to configure your Fuse Mediation Router application using blueprint, you must ensure that the camel-blueprint feature is installed (it is not installed by default). If necessary, install it by entering the following console command:

karaf@root> features:install camel-blueprint

The OSGi Configuration Admin service defines a mechanism for passing configuration settings to an OSGi bundle. You do not have to use this service for configuration, but it is typically the most convenient way of configuring bundle applications. Spring DM provides support for OSGi configuration, enabling you to substitute variables in a Spring XML file using values obtained from the OSGi Configuration Admin service.

Example 7.1 shows how to pass the value of the prefix variable to the constructor of the MyTransform bean, where the value of prefix can be set by the OSGi Configuration Admin service:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ctx="http://www.springframework.org/schema/context"
       xmlns:osgi="http://camel.apache.org/schema/osgi"
       xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
       ... >
  ...
  <bean id="myTransform" class="org.fusesource.example.MyTransform">
    <property name="prefix" value="${prefix}"/>
  </bean>
   
  <osgix:cm-properties id="preProps" persistent-id="org.fusesource.example">
    <prop key="prefix">MyTransform</prop>
  </osgix:cm-properties>

  <ctx:property-placeholder properties-ref="preProps" />

</beans>

This section explains how to generate, build, and run a complete Fuse Mediation Router example in the OSGi container, where the starting point code is generated with the help of a Maven archetype.

In order to generate a project using an Fuse ESB Maven archetype, you must have the following prerequisites:

The servicemix-camel-osgi-bundle archetype creates a project for building a route that can be deployed into the OSGi container. To generate a Maven project with the coordinates, org.fusesource.example:camel-bundle, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-camel-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=org.fusesource.example
-DartifactId=camel-bundle

The result of this command is a directory, ProjectDir/camel-bundle, containing the files for the generated bundle project.

To install and run the generated camel-bundle project, perform the following steps:

This section explains how to modify an existing Maven project for a Fuse Service Framework application, so that the project generates an OSGi bundle suitable for deployment in the Fuse ESB OSGi container. To convert the Maven project, you need to modify the project's POM file and the project's Spring XML file(s) (located in META-INF/spring).

To configure a Maven POM file to generate a bundle, there are essentially two changes you need to make: change the POM's package type to bundle; and add the Maven bundle plug-in to your POM. For details, see Modifying an Existing Maven Project.

The Fuse Service Framework runtime components are included in Fuse ESB as an OSGi bundle called org.apache.cxf.bundle. The dependency on this bundle can conveniently be expressed by adding the Require-Bundle element to the Maven bundle plug-in's instructions, as highlighted in the following sample POM:

<project ... >
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        ...
                        <Require-Bundle>org.apache.cxf.bundle</Require-Bundle>
                        ...
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

In order for your application to use the Fuse Service Framework components, you need to import their packages into the application's bundle. Because of the complex nature of the dependencies in Fuse Service Framework, you cannot rely on the Maven bundle plug-in, or the bnd tool, to automatically determine the needed imports. You will need to explicitly declare them.

You need to import the following packages into your bundle:

Example 8.1 shows how to configure the Maven bundle plug-in in your POM to import the mandatory packages. The mandatory import packages appear as a comma-separated list inside the Import-Package element. Note the appearance of the wildcard, *, as the last element of the list. The wildcard ensures that the Java source files from the current bundle are scanned to discover what additional packages need to be imported.

<project ... >
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        ...
                        <Import-Package>
                            javax.jws,
                            javax.wsdl,
                            javax.xml.bind,
                            javax.xml.bind.annotation,
                        			    javax.xml.namespace,
                        			    javax.xml.ws,
                        			    META-INF.cxf,
                            META-INF.cxf.osgi,
                            org.apache.cxf.bus,
                            org.apache.cxf.bus.spring,
                            org.apache.cxf.bus.resource,
                            org.apache.cxf.configuration.spring,
                            org.apache.cxf.resource,
                            org.apache.cxf.jaxws,
                            org.apache.cxf.transport.http_osgi,
                            org.springframework.beans.factory.config,
                            *
                        </Import-Package>
                        ...
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

The OSGi Configuration Admin service defines a mechanism for passing configuration settings to an OSGi bundle. You do not have to use this service for configuration, but it is typically the most convenient way of configuring bundle applications. Both Spring DM and Blueprint provide support for OSGi configuration, enabling you to substitute variables in a Spring XML file or a Blueprint file using values obtained from the OSGi Configuration Admin service.

For details of how to use OSGi configuration properties, see Use OSGi configuration properties (optional) and Add OSGi configurations to the feature.

This section explains how to generate, build, and run a complete Fuse Service Framework example in the OSGi container, where the starting point code is generated with the help of a Maven archetype.

In order to generate a project using a Fuse ESB Maven archetype, you must have the following prerequisites:

The servicemix-cxf-code-first-osgi-bundle archetype creates a project for building a Java-first JAX-WS application that can be deployed into the OSGi container. To generate a Maven project with the coordinates, org.fusesource.example:cxf-code-first-bundle, enter the following command:

mvn archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-cxf-code-first-osgi-bundle
-DarchetypeVersion=2011.02.1-fuse-00-08
-DgroupId=org.fusesource.example
-DartifactId=cxf-code-first-bundle

The result of this command is a directory, ProjectDir/cxf-code-first-bundle, containing the files for the generated bundle project.

Typically, you will need to modify the instructions for the Maven bundle plug-in in the POM file. In particular, the default Import-Package element generated by the servicemix-cxf-code-first-osgi-bundle archetype is not configured to scan the project's Java source files. In most cases, however, you would want the Maven bundle plug-in to perform this automatic scanning in order to ensure that the bundle imports all of the packages needed by your code.

To enable the Import-Package scanning feature, simply add the wildcard, *, as the last item in the comma-separated list inside the Import-Package element, as shown in the following example:

<project ... >
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        ...
                        <Import-Package>
                            javax.jws,
                            javax.wsdl,
                            javax.xml.bind,
                            javax.xml.bind.annotation,
                        			    javax.xml.namespace,
                        			    javax.xml.ws,
                        			    META-INF.cxf,
                            META-INF.cxf.osgi,
                            org.apache.cxf.bus,
                            org.apache.cxf.bus.spring,
                            org.apache.cxf.bus.resource,
                            org.apache.cxf.configuration.spring,
                            org.apache.cxf.resource,
                            org.apache.cxf.jaxws,
                            org.apache.cxf.transport.http_osgi,
                            org.springframework.beans.factory.config,
                            *
                        </Import-Package>
                        ...
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

To install and run the generated cxf-code-first-bundle project, perform the following steps:

When you start up the OSGi container for the first time, it automatically installs and activates a default broker instance. The default broker creates an Openwire port that listens on IP port 61616 and a Stomp port that listens on IP port 61613. The broker remains installed in the OSGi container and activates whenever you restart the OSGi container.

You can examine the broker configuration by looking at the contents of the file InstallDir/etc/activemq-broker.xml, which contains a copy of the default broker's configuration. It is not possible to change the default broker's configuration by editing this file, however. The active copy of the default broker configuration is already deployed as a bundle in the OSGi container.

The default broker is deployed as the bundle named, activemq-broker.xml. To discover the default broker's bundle ID, enter the following console command:

osgi:list | grep activemq

You should see some output like the following:

[  42] [Active     ] [Created     ] [       ] [   60] activemq-core (5.4.0.fuse-00-00)
[  44] [Active     ] [            ] [       ] [   60] activemq-console (5.4.0.fuse-00-00)
[  45] [Active     ] [            ] [       ] [   60] activemq-ra (5.4.0.fuse-00-00)
[  46] [Active     ] [            ] [       ] [   60] activemq-pool (5.4.0.fuse-00-00)
[  47] [Active     ] [Created     ] [       ] [   60] activemq-karaf (5.4.0.fuse-00-00)
[  52] [Resolved   ] [            ] [       ] [   60] activemq-blueprint (5.4.0.fuse-00-00)
[  53] [Active     ] [Created     ] [       ] [   60] activemq-broker.xml (0.0.0)

In this example, the default broker has the bundle ID, 53.

The default broker is configured to store its data in the following directory:

InstallDir/data/activemq/default

If you decide that you don't want to use the default broker, you can disable it by stopping its bundle. For example, assuming that the default broker has the bundle ID, 53, you can disable the default broker by entering the following console command:

osgi:stop 53

The default broker will remain de-activated, even if you stop and restart the OSGi container.

Before deploying a JMS broker, the activemq feature must be installed in the OSGi container. Normally, this feature is installed by default in Fuse ESB, so it should already be available. If the feature was uninstalled at some point, you can re-install it by entering the following command at the console:

karaf@root> features:install activemq

If you have an existing Fuse Message Broker XML configuration file, you can deploy the broker by copying the configuration file into the following hot deploy directory:

InstallDir/deploy

After deploying, the configured broker starts up immediately.

After deploying the BrokerName broker, Fuse ESB automatically creates a data directory at the following location:

InstallDir/activemq-data/BrokerName

You can hot deploy a broker using either of the following types of configuration file:

You can deploy your broker using a Spring configuration file, where the root element is {http://www.springframework.org/schema/beans}beans. The broker element is a child of the beans element and the broker's namespace is http://activemq.apache.org/schema/core.

For example, the following Spring configuration instantiates a broker named simple-spring, which creates an Openwire connector on the IP port 61000:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       >

    <broker xmlns="http://activemq.apache.org/schema/core"
        brokerName="simple-spring">
        <transportConnectors>
            <transportConnector name="openwire" uri="tcp://localhost:61000"/>
        </transportConnectors>
    </broker>

</beans>

It is not necessary to specify schema locations in the configuration. But if you are editing the configuration file with an XML editor, you might want to add the schema locations in order to support schema validation and content completion in the editor. For the preceding example, you could specify the schema locations as follows:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.0.xsd"
       >
    ...

You can deploy your broker using a blueprint configuration file, where the root element is {http://www.osgi.org/xmlns/blueprint/v1.0.0}blueprint. The broker element is a child of the blueprint element and the broker's namespace is http://activemq.apache.org/schema/core.

For example, the following blueprint configuration instantiates a broker named simple-blueprint, which creates an Openwire connector on the IP port 61001:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    >
    <broker xmlns="http://activemq.apache.org/schema/core"
        brokerName="simple-blueprint">
        <transportConnectors>
            <transportConnector name="openwire" uri="tcp://localhost:61001"/>
        </transportConnectors>
    </broker>
</blueprint>

It is not necessary to specify schema locations in the configuration. But if you are editing the configuration file with an XML editor, you might want to add the schema locations in order to support schema validation and content completion in the editor. For the preceding example, you could specify the schema locations as follows:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
    http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.0.xsd
    http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd"
    >
    ...

As well as installing the libraries needed for running a Fuse Message Broker broker, the activemq feature also provides a set of console commands for managing and monitoring broker instances.

If you do not already have a broker configuration file, the activemq:create-broker console command provides a simple way of creating a new broker instance with default settings. To create a new broker with the broker name, test, enter the following console command:

karaf@root> activemq:create-broker --name test

After executing this command, you should see the broker configuration file, test-broker.xml, in the InstallDir/deploy directory. You can edit the settings in this file in order to change the broker configuration. As soon as any changes are saved to the test-broker.xml file, the OSGi container re-reads the broker configuration.

Broker instances created using the activemq:create-broker command are configured to store their data in the following directory:

InstallDir/data/activemq/BrokerName

You can use the activemq:destroy-broker console command to remove a broker instance. For example, to destroy the broker named test, enter the following console command.

karaf@root> activemq:destroy-broker --name test

Alternatively, you can simply delete the file, test-broker.xml, from the hot deploy directory, InstallDir/deploy.

You can use the activemq:query console command to monitor the status of the broker (or possibly brokers) currently deployed in the container. The following command connects to the container's JMX port and downloads all of the broker's status:

karaf@root> activemq:query --jmxlocal

Typically, the amount of data retrieved by this command is unwieldy. It is better to filter the data by selecting specific queues or topics. For example, to view the status of all queues whose name starts with camel., enter the following command:

karaf@root> activemq:query --jmxlocal -QQueue=camel.*

For more details, see the activemq:query help text, by entering activemq:query --help.

As an alternative to querying the broker with the activemq:query command, you can monitor the broker through any JMX monitoring tool, such as JConsole (a standard utility provided with Sun's Java Development Kit). For an example of how to monitor the broker using JConsole, see JMS Endpoints in a Router Application.

The following example shows how you can integrate a JMS broker into a router application. The example generates messages using a timer; sends the messages through the camel.timer queue in the JMS broker; and then writes the messages to a specific directory in the file system.

In order to run the sample router application, you need to have the camel-activemq feature installed in the OSGi container. The camel-activemq component is needed for defining Fuse Message Broker-based JMS endpoints in Fuse Mediation Router. This feature is not installed by default, so you must install it using the following console command:

karaf@root> features:install camel-activemq

You also need the activemq feature, but this feature is normally available, because Fuse ESB installs it by default.

Example 9.1 gives an example of a Fuse Mediation Router route defined using the Spring XML DSL. Messages generated by the timer endpoint are propagated through the JMS broker and then written out to the file system.

<?xml version="1.0"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:util="http://www.springframework.org/schema/util"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:camel="http://camel.apache.org/schema/spring"
  xmlns:osgi="http://www.springframework.org/schema/osgi"
  xsi:schemaLocation="
         http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans.xsd
         http://www.springframework.org/schema/util
         http://www.springframework.org/schema/util/spring-util.xsd
         http://www.springframework.org/schema/osgi
         http://www.springframework.org/schema/osgi/spring-osgi.xsd
         http://www.springframework.org/schema/osgi-compendium
         http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd
         http://camel.apache.org/schema/spring
         http://camel.apache.org/schema/spring/camel-spring.xsd
         http://www.springframework.org/schema/osgi
         http://www.springframework.org/schema/osgi/spring-osgi.xsd">

  <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="tcp://localhost:61616"/>
  </bean>

  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="timer://MyTimer?fixedRate=true&amp;period=4000"/>
      <setBody><constant>Hello World!</constant></setBody>
      <to uri="activemq:camel.timer"/>
    </route>
    <route>
      <from uri="activemq:camel.timer"/>
      <to uri="file:C:/temp/sandpit/timer"/>
    </route>
  </camelContext>
	
</beans>

In general, it is necessary to create a custom instance of the Fuse Mediation Router activemq component, because you need to specify the connection details for connecting to the broker. The preceding example uses Spring syntax to instantiate the activemq bean which connects to the broker URL, tcp://localhost:61616. The broker URL must correspond to one of the transport connectors defined in the broker configuration file, deploy/test-broker.xml.

Example 9.1 defines two routes, as follows:

To run the sample router application, perform the following steps:

This section explains how to generate, build, and deploy a simple OSGi service in the OSGi container. The service is a simple Hello World Java class and the OSGi configuration is defined using a blueprint configuration file.

In order to generate a project using the Maven Quickstart archetype, you must have the following prerequisites:

The maven-archetype-quickstart archetype creates a generic Maven project, which you can then customize for whatever purpose you like. To generate a Maven project with the coordinates, org.fusesource.example:osgi-service, enter the following command:

mvn archetype:create
-DarchetypeArtifactId=maven-archetype-quickstart
-DgroupId=org.fusesource.example
-DartifactId=osgi-service

The result of this command is a directory, ProjectDir/osgi-service, containing the files for the generated project.

You must customize the POM file in order to generate an OSGi bundle, as follows:

Create the ProjectDir/osgi-service/src/main/java/org/fusesource/example/service sub-directory. In this directory, use your favorite text editor to create the file, HelloWorldSvc.java, and add the code from Example 10.3 to it.

// Java
package org.fusesource.example.service;

public interface HelloWorldSvc 
{
    public void sayHello();
}

Create the ProjectDir/osgi-service/src/main/java/org/fusesource/example/service/impl sub-directory. In this directory, use your favorite text editor to create the file, HelloWorldSvcImpl.java, and add the code from Example 10.4 to it.

package org.fusesource.example.service.impl;

import org.fusesource.example.service.HelloWorldSvc;


public class HelloWorldSvcImpl implements HelloWorldSvc {
    
    public void sayHello()
    {
        System.out.println( "Hello World!" );
    }

}

The blueprint configuration file is an XML file stored under the OSGI-INF/blueprint directory on the class path. To add a blueprint file to your project, first create the following sub-directories:

ProjectDir/osgi-service/src/main/resources
ProjectDir/osgi-service/src/main/resources/OSGI-INF
ProjectDir/osgi-service/src/main/resources/OSGI-INF/blueprint

Where the src/main/resources is the standard Maven location for all JAR resources. Resource files under this directory will automatically be packaged in the root scope of the generated bundle JAR.

Example 10.5 shows a sample blueprint file that creates a HelloWorldSvc bean, using the bean element, and then exports the bean as an OSGi service, using the service element.

Under the ProjectDir/osgi-service/src/main/resources/OSGI-INF/blueprint directory, use your favorite text editor to create the file, config.xml, and add the XML code from Example 10.5.

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="hello" class="org.fusesource.example.service.impl.HelloWorldSvcImpl"/>
  
  <service ref="hello" interface="org.fusesource.example.service.HelloWorldSvc"/>

</blueprint>

To install and run the osgi-service project, perform the following steps:

This section explains how to generate, build, and deploy a simple OSGi client in the OSGi container. The client finds the simple Hello World service in the OSGi registry and invokes the sayHello() method on it.

In order to generate a project using the Maven Quickstart archetype, you must have the following prerequisites:

The maven-archetype-quickstart archetype creates a generic Maven project, which you can then customize for whatever purpose you like. To generate a Maven project with the coordinates, org.fusesource.example:osgi-client, enter the following command:

mvn archetype:create
-DarchetypeArtifactId=maven-archetype-quickstart
-DgroupId=org.fusesource.example
-DartifactId=osgi-client

The result of this command is a directory, ProjectDir/osgi-client, containing the files for the generated project.

You must customize the POM file in order to generate an OSGi bundle, as follows:

To add a blueprint file to your client project, first create the following sub-directories:

ProjectDir/osgi-client/src/main/resources
ProjectDir/osgi-client/src/main/resources/OSGI-INF
ProjectDir/osgi-client/src/main/resources/OSGI-INF/blueprint

Under the ProjectDir/osgi-client/src/main/resources/OSGI-INF/blueprint directory, use your favorite text editor to create the file, config.xml, and add the XML code from Example 10.6.

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  
  <reference id="helloWorld"
        interface="org.fusesource.example.service.HelloWorldSvc"/>
  
  <bean id="client"
        class="org.fusesource.example.client.Client"
        init-method="init">
    <property name="helloWorldSvc" ref="helloWorld"/>
  </bean>

</blueprint>

Under the ProjectDir/osgi-client/src/main/java/org/fusesource/example/client directory, use your favorite text editor to create the file, Client.java, and add the Java code from Example 10.7.

// Java
package org.fusesource.example.client;

import org.fusesource.example.service.HelloWorldSvc;

public class Client {
    HelloWorldSvc helloWorldSvc;
    
    // Bean properties
    public HelloWorldSvc getHelloWorldSvc() {
        return helloWorldSvc;
    }

    public void setHelloWorldSvc(HelloWorldSvc helloWorldSvc) {
        this.helloWorldSvc = helloWorldSvc;
    }

    public void init() {
        System.out.println("OSGi client started.");
        if (helloWorldSvc != null) {
            System.out.println("Calling sayHello()");
            helloWorldSvc.sayHello();  // Invoke the OSGi service!
        }
    }

}

To install and run the osgi-client project, perform the following steps:

Fuse Mediation Router provides a simple way to invoke OSGi services using the Bean language. This feature is automatically available whenever a Fuse Mediation Router application is deployed into an OSGi container and requires no special configuration.

When a Fuse Mediation Router route is deployed into the OSGi container, the CamelContext automatically sets up a registry chain for resolving bean instances: the registry chain consists of the OSGi registry, followed by the blueprint (or Spring) registry. Now, if you try to reference a particular bean class or bean instance, the registry resolves the bean as follows:

Consider the OSGi service defined by the following Java interface, which defines the single method, getGreeting():

// Java
package org.fusesource.example.hello.boston;

public interface HelloBoston {
    public String getGreeting();
}

When defining the bundle that implements the HelloBoston OSGi service, you could use the following blueprint configuration to export the service:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

  <bean id="hello" class="org.fusesource.example.hello.boston.HelloBostonImpl"/>
  
  <service ref="hello" interface="org.fusesource.example.hello.boston.HelloBoston"/>

</blueprint>

Where it is assumed that the HelloBoston interface is implemented by the HelloBostonImpl class (not shown).

After you have deployed the bundle containing the HelloBoston OSGi service, you can invoke the service from a Fuse Mediation Router application using the Java DSL. In the Java DSL, you invoke the OSGi service through the Bean language, as follows:

from("timer:foo?period=5000")
  .bean(org.fusesource.example.hello.boston.HelloBoston.class, "getGreeting")
  .log("The message contains: ${body}")

In the bean command, the first argument is the OSGi interface or class, which must match the interface exported from the OSGi service bundle. The second argument is the name of the bean method you want to invoke. For full details of the bean command syntax, see Bean Integration in Implementing Enterprise Integration Patterns.

In the XML DSL, you can also use the Bean language to invoke the HelloBoston OSGi service, but the syntax is slightly different. In the XML DSL, you invoke the OSGi service through the Bean language, using the method element, as follows:

<beans ...>
  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="timer:foo?period=5000"/>
      <setBody>
          <method ref="org.fusesource.example.hello.boston.HelloBoston"
                  method="getGreeting"/>
      </setBody>
      <log message="The message contains: ${body}"/>
    </route>
  </camelContext>
</beans>

Fuse ESB uses Maven as the primary mechanism for locating features, bundles, and their dependencies. By default, Maven is an inherently online tool: if Maven is unable to find a required artifact in its local repository, it automatically searches remote repositories on the Internet and downloads the required artifacts on demand.

If you start up a Fuse ESB console and enter the command:

karaf@root> features:list

You will see a complete list of the available features. The first column of the listing indicates whether each feature is [installed] or [uninstalled]. If you run this command immediatetly after installing Fuse ESB, the installed features are the core Fuse ESB features. These core features and all of their dependencies are provided in the Fuse ESB installation under the following directory:

EsbInstallDir/system

In other words, none of the core features need to fetched online, they are all provided in the system repository.

If you run features:list immediately after installing Fuse ESB, the features listed as uninstalled are the optional Fuse ESB features. In contrast to the core features, the optional features are not provided in the system repository. If you try to install one of the optional features, for example:

karaf@root> features:install camel-jms

The Fuse ESB container now attempts to locate and to download the camel-jms feature and, all of its dependencies, from remote repositories over the Internet.

If you are working in an offline environment, you need to make sure that all of the Fuse ESB features you require are available locally, from internal repositories. One way to achieve this is to create a smaller custom offline repository, which contains just the features and artifacts you need to run your application. For more details, see Generating a Custom Offline Repository.

This section explains how Maven locates artifacts at build time. Essentially, Maven implements a simple caching scheme: artifacts are downloaded from remote repositories on the Internet and then cached in the local repository. Figure 11.1 shows an overview of the procedure that Maven follows when locating artifacts at build time.

Figure 11.1. How Maven Locates Artifacts at Build Time

While building a project, Maven locates required artifacts (dependencies, required plugins, and so on) as follows:

You can configure the following kinds of repository for locating Maven artifacts at build time:

Maven resolves the location of the local repository, by checking the following settings:

Maven enables you to specify the location of internal repositories either in your settings.xml file (which applies to all projects) or in a pom.xml (which applies to that project only). Typically, the location of an internal repository is specified using either a file:// URL or a http:// URL (assuming you have set up a local Web server to serve up the artifacts) and you should generally ensure that internal repositories are listed before remote repositories. Otherwise, there is nothing special about an internal repository: it is just a repository that happens to be located in your internal network.

For an example of how to specify a repository in your settings.xml file, see Adding the fusesource repository.

Remote repositories are configured in the same way as internal repositories, except that they should be listed after any internal repositories.

This section explains how the Fuse ESB container locates artifacts at run time. The container strikes a balance between accessing artifacts locally and downloading artifacts from remote repositories: all of the features installed by default are provided locally, in the system repository; whereas non-default features are downloaded from remote repositories the first time they are used. Figure 11.2 shows an overview of the procedure that Fuse ESB follows when locating artifacts at run time.

Figure 11.2. How the Container Locates Artifacts at Run Time

Whenever a feature is installed (using features:install) or a Maven artifact is installed (using osgi:install MvnURL) at run time, the Fuse ESB container locates the required Maven artifacts as follows:

You can configure the following kinds of repository for locating Maven artifacts at run time:

The default repositories are always checked first. After installing Fuse ESB, the list of default repositories contains just a single entry, for the Fuse ESB system repository. For example, the etc/org.ops4j.pax.url.mvn.cfg file contains the following setting to configure the default repository list:

org.ops4j.pax.url.mvn.defaultRepositories=file:${karaf.home}/${karaf.default.repository}@snapshots

The defaultRepositories property takes a comma-separated list, enabling you to specify multiple default repositories. You can specify the repository location using a URL with a file:, http:, or https: scheme and you can optionally add the @snapshots suffix to allow snapshot versions to be read from the repository.

The container resolves the location of the local repository, by checking the following settings:

The remote repositories checked by the container are specified by the org.ops4j.pax.url.mvn.repositories property in the etc/org.ops4j.pax.url.mvn.cfg file. The repositories are specified in the form of a comma-separated list—for example:

org.ops4j.pax.url.mvn.repositories= \
    http://repo1.maven.org/maven2, \
    http://repo.fusesource.com/maven2, \
    http://repo.fusesource.com/maven2-snapshot@snapshots@noreleases, \
    http://repo.fusesource.com/nexus/content/repositories/releases, \
    http://repo.fusesource.com/nexus/content/repositories/snapshots@snapshots@noreleases, \
    http://repository.apache.org/content/groups/snapshots-group@snapshots@noreleases, \
    http://repository.ops4j.org/maven2, \
    http://svn.apache.org/repos/asf/servicemix/m2-repo, \
    http://repository.springsource.com/maven/bundles/release, \
    http://repository.springsource.com/maven/bundles/external

A repository URL in this list can optionally include one or more of the following suffixes:

When you move from the development phase of a project to the deployment phase, it is typically more convenient to pre-install all of the artifacts required by your application, rather than downloading them from the Internet on demand. In this case, the ideal solution is to create a custom offline repository, which contains the artifacts needed for your deployment. Creating a custom offline repository by hand, however, would be difficult, because it would need to include all of the transitive dependencies associated with your application bundles and features.

The ideal way to create a custom offline repository is to generate it, with the help of the Apache Karaf features-maven-plugin plug-in.

The features-maven-plugin plug-in from Apache Karaf is a utility that is used internally by the Apache Karaf developer community and the Fuse ESB development team to create distributions of the Apache Karaf OSGi container. Some of the goals of this plug-in are also useful for application developers, however, and this section explains how you can use the add-features-to-repo goal to generate your own custom offline repository.

To generate and install a custom offline repository for specific Apache Karaf features, perform the following steps:

In a convenient location—for example, ProjectDir—create a new directory, ProjectDir/custom-repo to hold the Maven project. Using a text editor, create the project's POM file, pom.xml, in the custom-repo directory and add the following contents to the file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>org.acme.offline-repo</groupId>
    <artifactId>custom-repo</artifactId>
    <version>1.0.0</version>
    <name>Generate offline features repository</name>
    
</project>

This is the bare bones of a Maven POM, which will be added to in the following steps. There is no need to specify a Maven package type here (it defaults to jar), because no package will be generated for this project.

Continue editing the pom.xml and add the features-maven-plugin as shown (where the build element is inserted as a child of the project element):

<project ...>
    ...
    <build>
        <plugins>
          <plugin>
            <groupId>org.apache.karaf.tooling</groupId>
            <artifactId>features-maven-plugin</artifactId>
            <version>2.2.1</version>

            <executions>
              <execution>
                <id>add-features-to-repo</id>
                <phase>generate-resources</phase>
                <goals>
                  <goal>add-features-to-repo</goal>
                </goals>
                <configuration>
                  <descriptors>
                    <!-- List the URLs of required feature repositories here -->
                  </descriptors>
                  <features>
                    <!-- List features you want in the offline repo here -->
                  </features>
                  <repository>target/features-repo</repository>
                </configuration>
              </execution>
            </executions>
          </plugin>
        </plugins>
    </build>

</project>

Subsequent steps will explain how to specify the descriptor list (of features repositories) and the features list.

In this example scenario, it is assumed that you want to make the camel-jms feature and the camel-quartz feature available in offline mode. List all of the features you want to download and store in the offline repository in the features element, which is a child of the configuration element of the features-maven-plugin.

To make the camel-jms and camel-quartz features available offline, add the following features element as a child of the feature-maven-plugin's configuration element:

<features>
  <feature>camel-jms</feature>
  <feature>camel-quartz</feature>
</features>

A feature repository is a location that stores feature descriptor files. Generally, because features can depend recursively on other features and because of the complexity of the dependency chains, the project normally requires access to all of the standard Fuse ESB feature repositories.

To see the full list of standard feature repositories used by your installation of Fuse ESB, open the etc/org.apache.karaf.features.cfg configuration file and look at the featuresRepository setting, which is a comma-separated list of feature repositories, like the following:

...
#
# Comma separated list of feature repositories to register by default
#
featuresRepositories=mvn:org.apache.karaf/apache-karaf/2.1.3-fuse-00-00/xml/features,
mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.4.0-fuse-00-00/xml/features,mvn
:org.apache.servicemix/apache-servicemix/4.3.1-fuse-00-00/xml/features,mvn:org.apache
.camel.karaf/apache-camel/2.6.0-fuse-00-00/xml/features,mvn:org.apache.servicemix/ode
-jbi-karaf/1.3.4/xml/features,mvn:org.apache.activemq/activemq-karaf/5.4.2-fuse-01-00
/xml/features
...

Now, add the listed feature repositories to the configuration of the features-maven-plugin in your POM file. Open the project's pom.xml file and add a descriptor element (as a child of the descriptors element) for each of the standard feature repositories. For example, given the preceding value of the featuresRepositories list, you would define the features-maven-plugin descriptors list in pom.xml as follows:

<descriptors>
  <!-- List taken from featuresRepositories in etc/org.apache.karaf.features.cfg -->
  <descriptor>mvn:org.apache.karaf/apache-karaf/2.1.3-fuse-00-00/xml/features</descriptor>
  <descriptor>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.4.0-fuse-00-00/xml/features</descriptor>
  <descriptor>mvn:org.apache.servicemix/apache-servicemix/4.3.1-fuse-00-00/xml/features</descriptor>
  <descriptor>mvn:org.apache.camel.karaf/apache-camel/2.6.0-fuse-00-00/xml/features</descriptor>
  <descriptor>mvn:org.apache.servicemix/ode-jbi-karaf/1.3.4/xml/features</descriptor>
  <descriptor>mvn:org.apache.activemq/activemq-karaf/5.4.2-fuse-01-00/xml/features</descriptor>
</descriptors>

Add the Fuse ESB system repository, EsbInstallDir/system, to the list of repositories in the pom.xml file. This is necessary for two reasons: first of all, it saves you from downloading Maven artificats that are already locally available from your Fuse ESB installation; and secondly, some of the artifacts in the system repository might not be available from any of the other repositories.

Using a text editor, open pom.xml and add the following repositories element as a child of the project element, customizing the file URL to point at your local system repository:

<project ...>
    ...
    <repositories>
      <repository>
        <id>esb.system.repo</id>
        <name>Fuse ESB internal system repo</name>
        <url>file:///E:/Programs/FUSE/apache-servicemix-4.4.1-fuse-00-08/system</url>
        <snapshots>
          <enabled>false</enabled>
        </snapshots>
        <releases>
          <enabled>true</enabled>
        </releases>
      </repository>
    </repositories>
    ...
</project>

Generally, the project requires access to all of the standard Fuse ESB remote repositories. To see the full list of standard remote repositories, open the etc/org.ops4j.pax.url.mvn.cfg configuration file and look at the org.ops4j.pax.url.mvn.repositories setting, which is a comma-separated list of URLs like the following:

org.ops4j.pax.url.mvn.repositories= \
    http://repo1.maven.org/maven2, \
    http://repo.fusesource.com/maven2, \
    http://repo.fusesource.com/maven2-snapshot@snapshots@noreleases, \
    http://repo.fusesource.com/nexus/content/repositories/releases, \
    http://repo.fusesource.com/nexus/content/repositories/snapshots@snapshots@noreleases, \
    http://repository.apache.org/content/groups/snapshots-group@snapshots@noreleases, \
    http://repository.ops4j.org/maven2, \
    http://svn.apache.org/repos/asf/servicemix/m2-repo, \
    http://repository.springsource.com/maven/bundles/release, \
    http://repository.springsource.com/maven/bundles/external

Each entry in this list must be converted into a repository element, which is then inserted as a child element of the respositories element in the project's pom.xml file. The preceding repository URLs have slightly different formats and must be converted as follows:

To generate the custom offline repository, open a new command prompt, change directory to ProjectDir/custom-repo, and enter the following Maven command:

mvn generate-resources

Assuming that the Maven build completes successfully, the custom offline repository should now be available in the following location:

ProjectDir/custom-repo/target/features-repo

To install the custom offline repository in the Fuse ESB container, edit the etc/org.ops4j.pax.url.mvn.cfg file and append the offline repository directory to the list of default repositories, as follows:

org.ops4j.pax.url.mvn.defaultRepositories=file:${karaf.home}/${karaf.default.repository}@snapshots,ProjectDir/custom-repo/target/features-repo@snapshots

The @snapshots suffix can be added to the offline repository URL, if there is a possibility that some of the artifacts in it are snapshot versions.

Figure 12.1 shows a general overview of the NMR architecture, which spans both the OSGi container and the JBI container.

Figure 12.1. NMR Architecture

In Figure 12.1, the NMR is represented as a horizontal graphical element in order to emphasize its role linking together various application bundles. In practice, however, the NMR is deployed as a collection of bundles, just like any other application in the OSGi container.

The Fuse ESB NMR is a general-purpose message bus used for transmitting messages between bundles in the OSGi container. It is modelled on the Normalized Message Router (NMR) defined in the Java Business Integration (JBI) specification. Hence, the Fuse ESB NMR can be used to transmit XML messages, optionally augmented with properties and attachments.

Unlike the standard NMR, however, the Fuse ESB NMR is not restricted to the JBI container. You can use the NMR to transmit messages inside the OSGi container or, if the JBI container is also deployed, to transmit messages between the two containers.

A key feature of the NMR message bus is that messages are transmitted in a standard, normalized form. The JBI standard defines a normalized message, which is based on the Web Services Description Language (WSDL) message format (both WSDL 1.1 and WSDL 2.0 formats are supported). A complete normalized message has the following aspects:

In the OSGi container, normalized messages have a standard layout, as follows:

Fuse ESB provides a simple Java API for accessing the NMR. You can use this API to define endpoints that process messages received from the NMR and you can write clients that send messages to NMR endpoints. To see how to use this API in practice, take a look at the examples/nmr demonstration code.

To enable integration with the NMR, Fuse Mediation Router provides an NMR component, which lets you define NMR endpoints either at the beginning (for example, as in from("nmr:ExampleEndpoint")) or at the end (for example, to("nmr:ExampleEndpoint")) of a route. For full details of how to use the NMR component, see The Fuse Mediation Router NMR Component.

The NMR component is an adapter to the NMR, enabling Fuse Mediation Router applications to send messages to other bundles within the OSGi container or to components within the JBI container.

Normally, the NMR feature is pre-installed in the OSGi container. If you need to install the NMR feature, however, you can do so by entering the following console command:

karaf@root> features:install nmr

To make NMR endpoints available to your Fuse Mediation Router application, you need to create an instance of the NMR component. Add the code shown in Example 12.1 to your bundle's Spring configuration file (located in META-INF/spring/*.xml) in order to instantiate the NMR component.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xmlns:camel-osgi="http://camel.apache.org/schema/osgi"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/osgi  http://www.springframework.org/schema/osgi/spring-osgi.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/camel/schema/spring/camel-spring.xsd
       http://camel.apache.org/schema/osgi http://camel.apache.org/schema/osgi/camel-osgi.xsd">

    <bean id="nmr" class="org.apache.servicemix.camel.nmr.ServiceMixComponent">
        <property name="nmr">
            <osgi:reference interface="org.apache.servicemix.nmr.api.NMR" />
        </property>
    </bean>

</beans>

The bean element creates an instance of the NMR component with the bean ID, nmr, where this bean ID can then be used as the scheme prefix to create or reference NMR endpoints in your Fuse Mediation Router routes. The bean definition references two external Java packages—org.apache.servicemix.camel.nmr and org.apache.servicemix.nmr.api—which must therefore be imported by this bundle. Because the packages do not occur in Java source code, you must add them explicitly to the list of imported packages in the bundle instructions in the POM—see Configuring the bundle instructions for details.

The NMR component enables you to create endpoints with the following URI format:

nmr:EndpointId

Where EndpointId is a string that identifies the endpoint uniquely. In particular, when used within the OSGi container, the endpoint ID string is not restricted to have any particular format. The scheme prefix, nmr, is actually determined by the ID of the bean that instantiates the NMR component—for example, see Example 12.1.

If you want to use the NMR component to send messages between the OSGi container and the JBI container, you need to be aware that NMR endpoints inside the JBI container requires a special syntax for the endpoint IDs. You can address an NMR endpoint inside the JBI container using the following URI format:

nmr:JBIAddressingURI

Where JBIAddressingURI conforms to the URI format described in ServiceMix URIs.

An NMR consumer endpoint automatically determines the message exchange pattern (for example, In or InOut) from the incoming message and sets the message exchange pattern in the current exchange accordingly.

The camel-nmr demonstration is located in the following directory:

InstallDir/examples/camel-nmr

The demonstration defines two routes in XML, where the routes are joined together using an NMR endpoint, as follows:

The route is deployed into the Fuse ESB container as an OSGi bundle.

Example 12.2 shows the routes for the camel-nmr demonstration, taken from the Spring XML configuration file, META-INF/spring/beans.xml.

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xmlns:camel-osgi="http://camel.apache.org/schema/osgi"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/osgi  http://www.springframework.org/schema/osgi/spring-osgi.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
       http://camel.apache.org/schema/osgi http://camel.apache.org/schema/osgi/camel-osgi.xsd">

  <import resource="classpath:org/apache/servicemix/camel/nmr/camel-nmr.xml" /> 

  <camel-osgi:camelContext xmlns="http://camel.apache.org/schema/spring">
    <!-- Route periodically sent events into the NMR -->
    <route>
      <from uri="timer://myTimer?fixedRate=true&amp;period=2000"/>
      <to uri="nmr:ExampleRouter"/> 
    </route>
    <!-- Route exchange from the NMR endpoint to a log endpoint -->
    <route>
      <from uri="nmr:ExampleRouter"/> 
      <bean ref="myTransform" method="transform"/>
      <to uri="log:ExampleRouter"/>
    </route>
  </camel-osgi:camelContext>

  <bean id="myTransform" class="org.apache.servicemix.examples.camel.MyTransform">
    <property name="prefix" value="MyTransform"/>
  </bean>

</beans>

Not all of the packages required by the NMR component can be automatically detected by the Maven bundle plug-in. Some of the package dependencies arise from settings in the Spring configuration file (see Example 12.1), which are not automatically taken into account by the bundle plug-in. In particular, you must ensure that the following additional packages are imported by the bundle:

For example, the following sample configuration of the Maven bundle plug-in shows how to add an Import-Package element that contains a list of the packages required for the NMR component:

<project ...>
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
                        <Import-Package>org.apache.servicemix.camel.nmr,org.apache.servicemix.nmr.api,*</Import-Package>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

The Import-Package list also includes the wildcard, *, which instructs the bundle plug-in to scan the Java source code in order to discover further package dependencies.

Pax-Exam is an automated testing framework for running tests in an OSGi container. Consider the manual steps that would be needed to run tests in an OSGi container:

Using Pax-Exam you can automate and simplify this testing procedure. Initialization options and provisioning options are performed by a configuration method in the test class. The Pax-Exam framework takes care of starting the OSGi container and before running the test class bundle.

This section gives a brief introduction to the Pax-Exam testing framework and explains how to write a basic example using Apache Karaf.

JUnit 4 is the latest version of the JUnit Java testing suite. What distinguishes JUnit 4 from earlier versions is that JUnit 4 defines a test by applying Java annotations (in contrast to earlier versions of JUnit, which used inherited classes and naming conventions).

The simplest JUnit tests require just two steps:

To integrate JUnit 4 with Pax-Exam, perform the following steps:

Theoretically, Pax-Exam provides all of the features that are needed to run an OSGi framework embedded in Apache Karaf. In practice, however, there are a lot of Java system properties and configuration options that need to be set in order to initialize Apache Karaf. It would be a nuisance, if all of these properties and options needed to be specified explicitly in the Pax-Exam configuration method.

In order to simplify running Pax-Exam in Apache Karaf, helper classes are provided, which automatically take care of initializing the OSGi framework for you. The following classes are provided:

Example 13.1 shows the Maven dependencies you need in order to run the Pax-Exam testing framework. You must specify dependencies on JUnit 4, Pax-Exam, and Apache Karaf tooling.

<project ...>
  ...
  <properties>
    <junit-version>4.4</junit-version>
    <pax-exam-version>1.2.0</pax-exam-version>
    <felix.karaf.version>1.4.0-fuse-01-00</felix.karaf.version>
    ...
  </properties>

  <dependencies>
      <!-- Pax-Exam dependencies -->
      <dependency>
        <groupId>org.ops4j.pax.exam</groupId>
        <artifactId>pax-exam</artifactId>
        <version>${pax-exam-version}</version>
      </dependency>
      <dependency>
        <groupId>org.ops4j.pax.exam</groupId>
        <artifactId>pax-exam-junit</artifactId>
        <version>${pax-exam-version}</version>
      </dependency>
      <dependency>
        <groupId>org.ops4j.pax.exam</groupId>
        <artifactId>pax-exam-container-default</artifactId>
        <version>${pax-exam-version}</version>
      </dependency>
      <dependency>
        <groupId>org.ops4j.pax.exam</groupId>
        <artifactId>pax-exam-junit-extender-impl</artifactId>
        <version>${pax-exam-version}</version>
      </dependency>

      <!-- JUnit dependencies -->
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>${junit-version}</version>
      </dependency>

      <!-- Apache Karaf integration --> 
      <dependency>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>org.apache.karaf.tooling.testing</artifactId>
        <version>${felix.karaf.version}</version>
        <scope>test</scope>
      </dependency>
  </dependencies>
  ...
</project>

To learn more about using the Pax-Exam testing framework, consult the following references:

Example 13.2 shows an example of how to write a test class for Apache Karaf in the Pax-Exam testing framework. The FeaturesText class configures the Apache Karaf environment, installs the obr and wrapper features, and then runs a test against the two features (where the obr and wrapper features implement particular sets of commands in the Apache Karaf command console).

// Java
/*
 * Licensed to the Apache Software Foundation (ASF)
 * ...
 */
package org.apache.karaf.shell.itests;

import org.apache.karaf.testing.AbstractIntegrationTest;
import org.apache.karaf.testing.Helper;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.ops4j.pax.exam.Option;
import org.ops4j.pax.exam.junit.Configuration;
import org.ops4j.pax.exam.junit.JUnit4TestRunner;
import org.osgi.service.blueprint.container.BlueprintContainer;
import org.osgi.service.command.CommandProcessor;
import org.osgi.service.command.CommandSession;

import static org.junit.Assert.assertNotNull;
import static org.ops4j.pax.exam.CoreOptions.equinox;
import static org.ops4j.pax.exam.CoreOptions.felix;
import static org.ops4j.pax.exam.CoreOptions.maven;
import static org.ops4j.pax.exam.CoreOptions.systemProperty;
import static org.ops4j.pax.exam.CoreOptions.waitForFrameworkStartup;
import static org.ops4j.pax.exam.OptionUtils.combine;
import static org.ops4j.pax.exam.container.def.PaxRunnerOptions.scanFeatures;

import static org.ops4j.pax.exam.container.def.PaxRunnerOptions.workingDirectory;

@RunWith(JUnit4TestRunner.class) 
public class FeaturesTest extends AbstractIntegrationTest { 

    @Test 
    public void testFeatures() throws Exception {
        // Make sure the command services are available
        assertNotNull(getOsgiService(BlueprintContainer.class, "osgi.blueprint.container.symbolicname=org.apache.karaf.shell.obr", 20000));
        assertNotNull(getOsgiService(BlueprintContainer.class, "osgi.blueprint.container.symbolicname=org.apache.karaf.shell.wrapper", 20000));
        // Run some commands to make sure they are installed properly
        CommandProcessor cp = getOsgiService(CommandProcessor.class); 
        CommandSession cs = cp.createSession(System.in, System.out, System.err);
        cs.execute("obr:listUrl");
        cs.execute("wrapper:install --help");
        cs.close();
    }

    @Configuration 
    public static Option[] configuration() throws Exception{
        return combine( 
            // Default karaf environment
            Helper.getDefaultOptions( 
                // this is how you set the default log level when using pax logging (logProfile)
                systemProperty("org.ops4j.pax.logging.DefaultServiceLog.level").value("DEBUG")),

            // add two features
            scanFeatures( 
                    maven().groupId("org.apache.karaf").artifactId("apache-felix-karaf").type("xml").classifier("features").versionAsInProject(),
                    "obr", "wrapper"
            ),

            workingDirectory("target/paxrunner/features/"), 

            waitForFrameworkStartup(), 
            
            // Test on both equinox and felix
            equinox(), felix() 
        );
    }

}