A Look Inside FUSE ESB 4: An OSGi-Based Integration Platform

DZone 's Guide to

A Look Inside FUSE ESB 4: An OSGi-Based Integration Platform

· Integration Zone ·
Free Resource

Recently, version 4 of the FUSE ESB was released, which is the enterprise support version of Apache ServiceMix 4, rebranded by Progress Software (previously IONA), but still fully open source and Apache licensed. This new major version of the FUSE ESB is founded on OSGi and introduces a number of new deployment models, in addition to JBI 1.0, which makes your life as an integration developer far easier.

In this article I’ll introduce you to the new version of FUSE ESB by explaining the new functionality of the ServiceMix Kernel and NMR projects with a number of hands-on examples. In order to try the examples covered in this article, you can download a copy of FUSE ESB from http://fusesource.com

Didn’t FUSE ESB support JBI?

Yes, in version 3 of FUSE ESB (based on Apache ServiceMix 3.x), the architecture is based on JBI 1.0. This means that the integration functionality provided by FUSE ESB can be implemented with service engines (SEs) and binding components (BCs), which are connected via a normalized message router. And with services assemblies (SAs) and service units (SUs) you can deploy integration functionality via Ant tasks or Maven plugins to the ServiceMix container. For more detailed information about version Apache ServiceMix 3 you can read another article I wrote for DZone, Pattern Based Development with ServiceMix.

But did this all change in version 4 of FUSE ESB? Well, yes and no. Version 4 is based on OSGi bundles and the classloading model of JBI 1.0 has been superseded by OSGi. You can now deploy your integration artifacts as OSGi bundles on the ServiceMix container; however, JBI 1.0 is still supported with version 4 and the JBI components like the JMS BC, File BC, Validation SE and the Bean SE are still there. So you can still deploy your good old service assemblies to the ServiceMix 4 container without any need to change the implementation from ServiceMix 3.

FUSE ESB 4 architecture

But let’s not stick too much in comparing version 3 and 4, and have a look at the new architecture of FUSE ESB 4. Fuse ESB 4 consists of two main projects: the kernel and the NMR, as shown in figure 1.

Figure 1 The architecture of FUSE ESB 4, which is based on OSGi.

The kernel component is the foundation of FUSE ESB 4. The kernel provides an OSGi-based platform using Apache Felix (although other OSGi containers can also be used) with a number of components on top. First there is the console, which is the central tool to interact with the kernel. When you start FUSE ESB, the console is started automatically, so you can manage the ESB environment. Starting the FUSE ESB is very easy, just open a command prompt and go to the installation directory of the FUSE ESB, e.g. c:\fuse-esb- Then enter the following command to start the ESB.

Windows: bin\servicemix.bat

Linux/Unix: bin/servicemix.sh

When the FUSE ESB has started, a console similar to figure 2 is shown.

Figure 2 A screenshot of the Fuse ESB console, which is started with the Fuse ESB.

The console is very intuitive and easy to use. There’s a handy ‘help’ option that you can use to get familiar with the commands. A command that you’ll be using quite often when using FUSE ESB is the ‘osgi list’ command. This shows an overview of all installed OSGi bundles on the container. To manage the bundles there are several commands that you can use like ‘osgi install’, ‘osgi uninstall’, ‘osgi start’ and ‘osgi stop’. An overview of all the OSGi related commands can be retrieved with the ‘osgi help’ command.

Instead of discussing all the components shown in figure 1 one-by-one, let’s first look at a small example to get familiar with the basic components of the FUSE ESB.

A short Camel ride

One of the main changes between version 3 and 4 of FUSE ESB is the integration with Apache Camel (http://activemq.apache.org/camel) to implement routing functionality. In version 3 there was already support for Camel with the Camel service engine, but in version 4 Camel is integrated in the core of the ServiceMix container. So let’s explore the use of Camel routing inside the FUSE ESB a bit.

With Camel, we have two options to implement the integration logic, a Java class using the Java domain specific language (DSL) or a Spring XML configuration file using the Camel XSD. For this first example we’ll use the Spring XML configuration option, because we can deploy this directly to the FUSE ESB without any packaging. Let’s look at a very simple example, where a file is moved from one directory, camel-test-in, to another directory, camel-test-out, in listing 1.

Listing 1 Spring configuration file, camel-file-test.xml, using Camel to move a file to another directory.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<camel-osgi:camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
<from uri="file:camel-test-in"/>
<to uri="file:camel-test-out"/>

As you can see in listing 1, we can define a Camel route configuration directly in a Spring XML configuration file. In this Camel configuration the Camel OSGi module is used. In the route element definition a source directory is configured with the from element and a target directory with the to element.

Before we can deploy this Camel example, we first have to install the Camel component on the FUSE ESB container. This is a good time to talk about the provisioning component implemented in the FUSE ESB kernel, also shown in figure 1. To provide a flexible way of installing new OSGi bundles to the FUSE ESB container, the kernel provides several sources, including Maven artifacts, URLs and local file paths. To interact with the provisioning component the features command can be used in the console of the FUSE ESB container. To get an overview of features that can be installed on the FUSE ESB container you can use the ‘features list’ command. A feature consists of one or more OSGi bundles and provides specific functionality that can be used to develop integration functionality. By default, the result of the ‘features list’ command is an substantial number of components, including Camel, ActiveMQ, the JBI components that we could already use in FUSE ESB 3, and the NMR project.

To get our simple Camel example running, we need to install the Camel functionality. The installation of a specific feature is very simple to do with the console. Just run the command ‘feature install camel’, where camel can of course be replaced by other features you may wish to install. The feature name should be exactly the same as the name you see as a result of the ‘feature list’ command. When the Camel feature is installed, the Camel file example can easily be deployed on the FUSE ESB by copying the Camel configuration file, camel-file-test.xml, to the deploy directory in the FUSE ESB installation directory.

If the FUSE ESB has been started you can now see that the Camel file example has been installed by executing the ‘osgi list’ command. The last OSGi bundle that is showed in the list is now the camel-file-test.xml bundle with a status of active. This means that the FUSE ESB has already started the Camel file example OSGi bundle and is polling the camel-test-in directory for files. If you copy a file to the camel-test-in directory it is consumed by the FUSE ESB container and a new file with the same content is created in the camel-test-out directory. So, we can use the components provided by Camel out-of-the-box in the FUSE ESB container, and we don’t have to create a JAR file or another deployment package, we can use a Spring XML configuration and your mediation flow is deployed and running.

Well, this is almost true. By default the following Camel components are installed with the Camel feature:

Camel component

Short description

Bean component

Bind Spring beans to a message exchange.


Use a data set to send large number of messages to stress test a message flow.


Synchronous call to another endpoint.


Consume and produce files from a specified directory.


A List can be used to test and debug message exchanges.


Log the message exchange with Jakarta Commons Logging.


Use the mock component to test a message flow.


Asynchronous call to another endpoint in the same Camel Context.


Send a message on a specific time interval.


Validates the message payload with XML Schema and JAXP validation.


Asynchronous call to another endpoint in the same JVM.


Transforms the message using a XSLT stylesheet.

In the simple file example we used the Camel file component. As you can see on the Camel website, there are a lot of other Camel components available (http://activemq.apache.org/camel/components.html). So if we would like to use the Camel JMS component in the FUSE ESB we should do an additional installation. But the Camel JMS component is not available by default in the features list. To make other Camel components available in the features list we should add a features URL where the provisioning component can retrieve the additional components. Execute the following command to do this using a URL that matches the version of FUSE ESB that you are using:

features addUrl http://repo.fusesource.com/maven2/org/apache/servicemix/camel/org.apache.servicemix.camel.features/

When we execute the ‘features list’ command now, a large number of additional Camel components is available to install, including the Camel JMS component. So to enable the Camel JMS component functionality just execute the ‘features install camel-jms’ command. So now let’s look at a bit more complex example using the Camel Java DSL implemented with an OSGi bundle.

Deploying an OSGi bundle

In the first example we showed how to use the Camel Spring XML configuration. But when we want to implement a Camel Java DSL route or use Java beans in the integration logic, we need another deployment mechanism. In FUSE ESB 4 the most obvious choice would be an OSGi bundle utilizing the Spring dynamic modules (Spring DM) framework. Figure 3 shows an example we’ll implement with an OSGi bundle.

Figure 3 Camel example that consumes a JMS message and validates it against an XML Schema definition. There is a standard target queue and an error queue in case of validation errors.

We’ll implement a ValidationRouter class with the Camel Java DSL that consumes a hello message from the camel.jms.in JMS queue. The message exchange will be logged and then it will be validated against the hello.xsd XML Schema definition file. When there are no validation errors, the hello message will be sent to the camel.jms.out queue and in the case of validation errors, the message will be forwarded to the camel.jms.error queue.

Note that ActiveMQ is included in FUSE ESB 4 by default and the ActiveMQ broker is started automatically when you start the FUSE ESB container. The ActiveMQ configuration that’s used by FUSE can be found in the deploy directory in the activemq-broker.xml file. So in this example we’ll make use of this default ActiveMQ broker. In listing 2, the implementation of the ValidationRouter is shown.

Listing 2 Implementation of the ValidationRouter class.

package com.fusesource.camel;

import org.apache.camel.ValidationException;
import org.apache.camel.builder.RouteBuilder;
public class ValidationRouter extends RouteBuilder {
public void configure() throws Exception {

Listing 2 shows the really powerful configuration language of the Camel Java DSL. With only a few lines of code you can define quite a bit of logic. With the from method the source JMS queue is configured, where a listener will consume newly arrived messages. Then, with the Camel log component, the message exchange is logged to the container log file. In this case the showAll configuration is used, which means the whole message exchange is logged. There are other logging configurations available which log for example the message headers or the message payload. You can also configure a log level, such as the info level which is used in this example.

Then a tryBlock method is used to be able to catch possible validation errors that may occur in the validator component. With the handle method exceptions can be caught and handled with a piece of integration logic. When a ValidationException occurs the message is forwarded to the camel.jms.error queue. To make the ValidationRouter class available within the Camel context and to start the JMS polling, we need to define a Camel XML configuration file similar to the first example shown in listing 1. But, in this second example we implemented the routing logic in a Java class, so let’s look at how to configure a Java DSL example in listing 3.

Listing 3 Camel XML configuration file, beans.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<camel-osgi:camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
<bean id="jms" class="org.apache.camel.component.jms.JmsComponent">
<property name="connectionFactory">
<osgi:reference id="connectionFactory" interface="javax.jms.ConnectionFactory" />
Instead of the route element definition we saw in the camelContext definition in the first example, we now define a package element, which contains the ValidationRouter class. When we deploy this second example to the FUSE ESB container, the com.fusesource.camel package will be scanned for Camel classes like the RouteBuilder class we defined with the ValidationRouter. Because we use the Camel JMS component, we have to define a Spring bean with a connection factory. We can define an ActiveMQConnectionFactory with a brokerURL property with a value of tcp://localhost:61616. But the connection factory is already defined in the activemq-broker.xml file that can be found in the deploy directory.
<osgi:service ref="pooledConnectionFactory">
<entry key="name" value="default"/>

 So we can also define an OSGi reference to this connection factory with the osgi:reference element. To be complete, listing 4 shows the XML Schema definition that will be used to validate the incoming message.

 Listing 4 The XML Schema definition file, hello.xsd.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<xsd:element name="hello-request">
<xsd:element name="name" type="xsd:string" minOccurs="1" maxOccurs="1"/>

This concludes the implementation of the Camel JMS example. The source code can of course be downloaded at the link shown at the end of this article, but let’s have a quick look at the project structure in figure 4.

Figure 4 Project structure of the Camel JMS example.

The camel-jms-example project is Maven based and therefore a pom.xml file is defined at the root of the project directory. The ValidationRouter is defined where you would expect a Java file in a Maven project, the src/main/java directory. The Camel XML configuration file beans.xml is defined in the src/main/resources directory under META-INF/spring. The XML Schema definition hello.xsd is defined at the root of the src/main/resources directory.

Now let’s get this example running on the FUSE ESB container. First we’ve to build the camel-jms-example project with the mvn clean install Maven command. A camel-jms-example-1.0.jar OSGi bundle file will be created in the target directory of the project. This jar file can be deployed to the FUSE ESB container by copying it to the deploy directory, just like we did in the first example. Remember that we’ve already installed the camel-jms feature, because we’ll need this feature to be installed before this example is deployed. When you now run the ‘osgi list’ command in the FUSE ESB console, you can see that the example OSGi bundle is deployed and active under the name ‘Fuse example : : Camel JMS’. In the source code of the camel-jms-example project you can find the hello-test.xml and hello-test2.xml test files. With the HermesJMS tool (http://www.hermesjms.com) you can use these files to add a message to the camel.jms.in queue to trigger the example. When you have produced a message to the queue you can see the log file of the FUSE ESB container by executing the ‘log d’ or ‘log display’ command in the console. You can see that the incoming message content is logged here.

In the first two examples we focused on the Camel functionality available in FUSE ESB. But FUSE ESB also provides an easy to use definition for web services with Apache CXF. But to communicate between Camel routes and these web services we need an interaction layer. So we need a bus inside the ESB, which is named the NMR in FUSE ESB 4.

Introducing the NMR

The NMR project enables the interaction between different components in the OSGi container. This is quite similar to the normalized message router which is defined in the JBI specification, but it’s more flexible and not only dedicated to JBI. The main purpose of the NMR is to mediate between service consumers and service providers. In the example shown in figure 5, you can see that the NMR can be used to communicate between a Camel route definition and a JAX-WS endpoint. This example is provided with FUSE ESB 4 with the name cxf-camel-nmr.

Figure 5 An overview of the cxf-camel-nmr example provided with FUSE ESB 4. This example shows the use of a NMR to mediate between a Camel route and a JAX-WS endpoint.

For a change we don’t trigger the integration logic with a file or a JMS message in the cxf-camel-nmr example, but with a timer. The timer is defined as part of the Camel route definition. Then a Spring bean, MyTransform, is invoked with its transform method, which basically returns the message that can be sent as a request to the web service. Then the web service is invoked via the NMR and the result is passed on, again to the MyTransform Spring bean, which logs the web service response with the display method. Now let’s take a look at the XML configuration in listing 5.

Listing 5 The XML configuration for the Camel route and JAX-WS endpoint definition.

<beans xmlns="http://www.springframework.org/schema/beans"
<import resource="classpath:META-INF/cxf/cxf.xml" />
<import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
<import resource="classpath:META-INF/cxf/transport/nmr/cxf-transport-nmr.xml" />
<import resource="classpath:org/apache/servicemix/camel/nmr/camel-nmr.xml" />
<camel-osgi:camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
<!-- Route periodically sent events into the NMR -->
uri="timer://myTimer?fixedRate=true&period=5000&exchangePattern=InOut" />
<bean ref="myTransform" method="transform"/>
<to uri="nmr:{http://cxfcamel.examples.servicemix.apache.org/}HelloWorldImplPort"/>
<bean ref="myTransform" method="display" />
<bean id="myTransform" class="org.apache.servicemix.examples.cxfcamel.MyTransform">
<property name="value">
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<ns1:sayHi xmlns:ns1="http://cxf.examples.servicemix.apache.org/">
<jaxws:endpoint id="helloWorld"
address="nmr:HelloWorld" />

We’ll start with the timer definition in the Camel route. The timer triggers the Camel route at a fixed rate of 5 seconds and produces an InOut exchange pattern. We need this InOut exchange pattern to communicate with the web service, because we need to send a request (In) and receive a response (Out). In the next step the transform method of the MyTransform Spring bean is invoked. In listing 6 we’ll look at the implementation of the MyTransform class in detail, but this method returns the SOAP envelope as configured with the value property of the myTransform Spring bean definition. So this produces a message with an element of sayHi and a value of Guillaume.

Then the hello world web service is invoked which is configured with the jaxws:endpoint. We’ll look at the implementation of the HelloWorldImpl in listing 7, but this method returns the obvious “hello” message. Then the MyTransform bean is called again, but now with the display method, which logs the web service response. Notice that we need to import several XML files at the top of the XML configuration file, to initialize Apache CXF and the NMR.The implementation of the MyTransform class is shown in listing 6, but this will not be too complex.

Listing 6 The MyTransform implementation which produces the web service request and logs the response.

package org.apache.servicemix.examples.cxfcamel;
import java.util.logging.Logger;
import javax.xml.transform.Source;
import org.apache.camel.converter.jaxp.StringSource;
import org.apache.camel.converter.jaxp.XmlConverter;
public class MyTransform {
private static final transient Logger LOG = Logger.getLogger(MyTransform.class);
private String value;
public Object transform(Object body) {
LOG.info(">>>> " + value);
return new StringSource(value);
public void display(Source body) throws Exception {
String str = new XmlConverter().toString(body);
LOG.info("<<<< " + str);
// omitted the getter and setter for the value property

The HelloWorldImpl class is very simple and is annotated with the @WebService annotation which sets the web service interface class, which just defines the sayHi method in this example.

To run this example you can use the provisioning component in FUSE ESB. Just execute the features install examples-cxf-camel-nmr command and the example will automatically be made active, so the timer will produce a new InOut exchange every 5 seconds.

In the first three examples we mainly focused on the Camel, CXF and NMR functionality available in FUSE ESB. But we can also use the JBI components that were already available in the version 3. Let’s implement an example where we create an OSGi bundle that’s using JBI components and the Camel functionality we already used.

Using JBI components in an OSGi bundle

In the second example we used the JMS functionality provided by Camel. But as you may know, ServiceMix also offers JMS functionality via the JMS binding component. You are free to choose your favorite JMS implementation when using FUSE ESB 4, but the JBI components often provide additional functionality on top of the functionality provided by the corresponding Camel components. In FUSE ESB 3 we had to construct a service assembly and implement service units to use the JBI binding components and service engines. In FUSE ESB 4, we can also use an OSGi bundle with a single XML configuration file, just like we did in the earlier examples, to make use of the JBI components provided by ServiceMix. This eases our effort to develop an integration solution using these JBI components. Be aware that not every JBI component available in FUSE ESB 3 has been made OSGi-ready yet, for example the Apache Ode BPEL service engine can only be used with a service assembly deployment model and the same goes for the JSR181 service engine.

In the next example we’ll configure the File binding component using Camel routing functionality to show the new OSGi bundle deployment model capability for the use of JBI components. A schematic overview of the example is shown in figure 6.

Figure 6 A simple example using the File binding component to show the OSGi bundle deployment model for JBI component configurations.

The main difference with the other examples is that we mainly used Camel functionality there. In this example there is a file poller component which consumes files from the insuranceIn directory and forwards the file contents as a JBI message to the Camel route definition. Then the Camel route definition sends the message on to the file sender, which writes a new file to the insuranceOut directory. To keep things simple we only used the file binding component, but you can imagine that you use all the JBI components which are available in FUSE ESB 4.

Let’s look at the implementation of this simple example. First, the XML configuration of the file poller and sender and the Camel route definition is shown in listing 8.

Listing 8 The XML configuration that defines a file poller, file sender and a Camel route.

<?xml version="1.0"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<camel-osgi:camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
<file:poller service="esb:insuranceFileService"
<file:sender service="esb:insuranceFileService"
<osgi:reference id="jbi" interface="org.apache.camel.Component"/>
<bean class="org.apache.servicemix.common.osgi.EndpointExporter" />

The Camel route definition is already shown in a previous example. What’s new here is the file poller and file sender definition. For JBI components you always have to configure a service and endpoint name because this uniquely identifies the JBI component in the container. For the file poller a targetService attribute is configured which defines the target component where the consumed file content is sent to. So this makes sure that the file content is sent to the Camel router.

In addition to the file poller and sender, we need to define an EndpointExporter bean that registers the poller and sender service and endpoint name in the OSGi registry. We also need to define an OSGi reference with an identifier of jbi, which enables the Camel route definition to talk with the JBI components. In the RouteBuilder class shown in listing 9, this jbi identifier is used.

Listing 9 The InsuranceRouter implementation which talks with the file poller and sender.

package com.fusesource.camel;

import org.apache.camel.builder.RouteBuilder;
public class InsuranceRouter extends RouteBuilder {
public void configure() throws Exception {

In the from method we can define a JBI service address, which enables JBI components, such as the file poller in this example, to send messages to this InsuranceRouter. Notice that you need to define the fully qualified service name, including the namespace and the service name. In this example, we log the incoming message and sent it to the insuranceFileService JBI service. This is, of course, the file sender we defined in listing 8.

To get this example running, we first need to install several components on the container using the features install command. Execute the following commands to install the necessary components:

features install jbi

features install servicemix-shared

features install servicemix-file

features install servicemix-camel

Now we can build the OSGi bundle. The jbi-camel-test project structure is similar to figure 4, so we can build the OSGi bundle using Maven with the mvn clean install command. In the target directory of the project the jbi-camel-test-1.0.jar is then created, so this file can be copied to the deploy directory of the FUSE ESB 4. Now you can trigger the example by copying the insurance-request.xml message to the insuranceIn directory created in the root of the FUSE ESB installation. This file is moved to the insuranceOut directory and the message content is logged to the FUSE ESB container. You can look at this log file with the log display command in the console.


In this article we’ve shown the new architecture of FUSE ESB 4 and the new capabilities this brings for developers. The new FUSE ESB console provides a nice management tool to interact with the container. And the provisioning component provides a really flexible way to install and remove components from the container, so you can create the ESB you need in your environment. The integration with Maven is really helpful to developers.

We looked at two main deployment models with the Spring XML configuration file and OSGi bundle in several examples. In the examples we showed that the role of Camel is pretty dominant in FUSE ESB 4 and this makes implementing routing logic very easy. You can choose if you want to define this logic with XML configuration or the Java DSL.

And of course we can still use JBI within FUSE ESB 4, so we can reuse the JBI components that are already available in FUSE ESB 3. You can choose to use OSGi bundles with a single configuration file or a service assembly consisting of several service units.

I hope you enjoyed this introduction into FUSE ESB 4 and working with the given examples. I really think the new OSGi bundle deployment model and the ease to configure Camel routes and CXF services is a step forward. FUSE ESB 4 is ready to be used and should ease your life as an integration developer. Keep integrating!

Additional resources

1. Fuse ESB – http://fusesource.com/products/enterprise-servicemix4/

2. ServiceMix 4 – http://servicemix.apache.org/SMX4/index.html

3. Fuse website – http://www.fusesource.com

3. Enterprise Integration Patterns – http://www.enterpriseintegrationpatterns.com

4. Apache Camel – http://activemq.apache.org/camel

5. Download article source code – http://www.esbinaction.com/files/osgi_article.zip

Tijs Rademakers

Tijs is a software architect working for Atos Origin and specializing in enterprise integration. Tijs is the co-author of the Manning book “Open Source ESBs in Action” (http://www.manning.com/rademakers). He speaks frequently at Java conferences about open source enterprise integration projects like ServiceMix, Mule, Apache Synapse and Apache Tuscany.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}