ServiceMix 4.2

By Jos Dirksen

In the open source community there are many different solutions for each problem. When you look for an open source ESB, however, you don't have that many options. Even though there are many open source ESB projects, not all of them are mature enough to be used to solve enterprise mission critical integration problems. ServiceMix is one of the open source projects that is mature enough to be used in these scenarios. ServiceMix, an Apache project, has been around for a couple of years now. It provides all the features you expect from an ESB such as routing, transformation, etc. The previous version was built based on JBI (JSR-208), but in its latest iteration, which we're discussing in this Refcard, ServiceMix has moved to an OSGi based architecture, which we'll discuss later on.

This DZone Refcard will provide an overview of the core elements of ServiceMix 4.0 and will show you how to use ServiceMix 4 by providing example configurations.

Before we show how to configure ServiceMix 4.0 for use, let us first look at the architecture of ServiceMix 4.0. This figure shows the following components:

ServiceMix Kernel: In this figure you can see that the basis of ServiceMix 4 is the ServiceMix Kernel. This kernel, which is based on the Apache Felix Karaf project (an OSGi based runtime), handles the core features ServiceMix provides, such as hot-deployment, provisioning of libraries or applications, remote access using ssh, JMX management and more.

ServiceMix NMR: This component, a normalized message router, handles all the routing of messages within ServiceMix and is used by all the other components.

>ActiveMQ: ActiveMQ, another Apache project, is the message broker which is used to exchange messages between components. Besides this ActiveMQ can also be used to create a fully distributed ESB.

Web: ServiceMix 4 also provides a web component. You can use this to start ServiceMix 4 embedded in a web application. An example of this is provided in the ServiceMix distribution.

JBI compatibility layer: The previous version of ServiceMix was based on JBI 1.0. For JBI a lot of components (from ServiceMix, but also from other parties), are available. This layer provides compatibility with the JBI specification, so that all the components from the previous version of ServiceMix can run on ServiceMix 4. Be sure though to use the 2009.01 version of these components.

Camel NMR: ServiceMix 4 provides a couple of different ways you can configure routing. You can use the endpoints provided by the ServiceMix NMR, but you can also use more advanced routing engines. One of those is the Camel NMR. This component allows you to run Camel based routes on ServiceMix.

CXF NMR: Besides an NMR based on Camel, ServiceMix also provides an NMR based on CXF. You can use this NMR to expose and route to Java POJOs annotated with JAX-WS annotations.

Before we move on to the next part, let's have a quick look at how a message is processed by ServiceMix. The following figure shows how a message is routed by the NMR. In this case we're showing a reply / response (in-out) message pattern.

In this figure you can see a number of steps being executed:

1. The consumer creates a message exchange for a specific service and sends a request.
2. The NMR determines the provider this exchange needs to be sent to and queus the message for delivery. The provider accepts this message and executes its business logic.
3. After the provider has finished processing, the response message is returned to the NMR.
4. The NMR once again queues the message for delivery. This time to the consumer. The consumer accepts the message.
5. After the response is accepted, the consumer sends a confirmation to the NMR.
6. The NMR routes this confirmation to the provider, who accepts it and ends this message exchange.

Now that we've seen the architecture and how a message is handled by the NMR, we'll have a look at how to configure ServiceMix 4.

ServiceMix 4 configuration is mostly done through Spring XML files supported by XML schemas for easy code completion. Let's look at two simple examples. The first one uses the File Binding component to poll a directory and the second one exposes a Web service using ServiceMix's CXF support.

<beans xmlns:file="http://servicemix.Apache.org/file/1.0"
                xmlns:dzone="http://servicemix.org/dzone/">
        <file:poller service="foo:filePoller"
                endpoint="filePoller"
                targetService="foo:fileSender"
                file="inbox" />
</beans>

In this listing you can see that we define a poller. A poller is one of the standard components that is provided by ServiceMix's file-binding-component. If we deploy this configuration to ServiceMix, ServiceMix will start polling the inbox directory for files. If it finds one, the file will be sent to the specified targetService.

In the following listing, we've again used a simple XML file. This time we've configured a webservice.

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:jaxws="http://cxf.Apache.org/jaxws"
        xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://cxf.Apache.org/jaxws http://cxf.Apache.org/schemas/jaxws.
        xsd">
<import resource="classpath:META-INF/cxf/cxf.xml" /> 1
<import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
<import resource="classpath:META-INF/cxf/cxf-extension-http.xml" />
<import resource="classpath:META-INF/cxf/osgi/cxf-extensionosgi.xml" />
        <jaxws:endpoint id="helloWorld"
                implementor="dzone.refcards.HelloWorld"
                address="/HelloWorld"/>
</beans>

In this listing we use a jaxws:endpoint to define a webservice. The implementor points to a simple POJO annotated with JAX-WS annotations. If this example is deployed to ServiceMix, ServiceMix will register a webservice based on the value in the address attribute.

ServiceMix provides a number of different options which you can use to deploy artifacts. In this section we'll look at these options, and show you how to use these.

ServiceMix 4, deployment options

OSGi bundle deployment
The easiest way to create an OSGi based ServiceMix bundle is by using Maven 2. To create a bundle you need to take a couple of simple steps. The first one is adding the mavenbundle- plugin to your pom.xml file. This is shown in the following code fragment.

...
<dependencies>
        <dependency>
                <groupId>org.Apache.felix</groupId>
                <artifactId>org.osgi.core</name>
                <version>1.0.0</version>
        </dependency>
        ...
</dependencies>
...
<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.camel.osgi</Import-Package>
                                <Private-Package>org.Apache.servicemix.examples.camel</Private-Package>
                                </instructions>
                        </configuration>
                </plugin>
        </plugins>
</build>
...

The important part here is the instructions section. This determines how the plugin packages your project. For more information on these settings see the maven OSGi bundle plugin page at http://cwiki.Apache.org/FELIX/Apachefelixmaven-bundle-plugin-bnd.html.

The next step is to make sure your project is bundled as a OSGi bundle. You do this by setting the <packaging> element in your pom.xml to bundle.

Now you can use mvn install to create an OSGi bundle, which you can copy to the deploy directory of ServiceMix and your bundle will be installed. If you use Spring to configure your application, make sure the Spring configuration files are located in the META-INF/spring directory. That way the Spring application context will be automatically created based on these files.

If you don't want to do this by hand you can also use a Maven archetype. ServiceMix provides a set of archetypes you can use. A good starting point for a project is the Camel OSGi archetype which you can use by executing the following following Maven command:

mvn archetype:create -DarchetypeGroupId=org.Apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-osgi-camel-archetype
-DarchetypeVersion=4.0.0.2-fuse
-DgroupId=com.yourcompany -DartifactId=camel-router
-DremoteRepositories=http://repo.fusesource.com/maven2/

There are many other archetypes available. For an overview of the available archetypes see: http://repo.fusesource.com/maven2/org/Apache/servicemix/tooling/

Spring XML Files Deployment

It's also possible to deploy Spring files without OSGi. Just drop a Spring file into the deploy directory. There are two points to take into account. First, you need to add the following to your Spring configuration file:

<bean class="org.Apache.servicemix.common.osgi.EndpointExporter" />

This will register the endpoints you've configured in your Spring file. The next element is optional but is good practice to add:

<manifest>
        Bundle-Version = 1.0.0
        Bundle-Name = Dzone :: Dzone test application
        Bundle-SymbolicName = dzone.refcards.test
        Bundle-Description = An example for servicemix refcard
        Bundle-Vendor = jos.dirksen@gmail.com
        Require-Bundle = servicemix-file, servicemix-eip
</manifest>

Using a manifest configuration element allows you to specify how your application is registered in ServiceMix.

JBI Artifacts Deployment

If you've already invested in JBI based applications, you can still use ServiceMix 4 to run them in. Just deploy your Service Assembly (SA) in the ServiceMix deploy directory and ServiceMix will deploy your application.

Feature Descriptor Based Deployment

If you've got an application which contains many bundles and that requires additional configuration you can use a feature to easily manage this. A feature contains a set of bundles and configuration which can be easily installed from the ServiceMix console. The following listing shows the feature descriptor of the nmr component.

<features>
        <feature name="nmr" version="1.0.0">
        <bundle>mvn:org.Apache.servicemix.document/org.Apache.servicemix.document/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.api/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.core/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.osgi/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.spring/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.commands/1.0.0</bundle>
        <bundle>mvn:org.Apache.servicemix.nmr/org.Apache.servicemix.nmr.management/1.0.0</bundle>
        </feature>
</features>

If you want to install this feature you can just type features/install nmr from the ServiceMix console.

For routing in ServiceMix you've got two options:

• EIP: ServiceMix provides a JBI component that implements a number of Enterprise Integration Patterns.
• Camel: You can use Camel routes in ServiceMix. Camel provides the most flexible and exhaustive routing options for ServiceMix

EIP Component Routing

This routing is provided by the EIP component. To check whether this is installed in your ServiceMix runtime you can execute features/list from the ServiceMix commandline. This will show you a list of installed features. If you see [installed] [ 2009.01] servicemix-eip the component is installed. If it shows uninstalled instead of installed, you can use the features/install servicemix-eip to install this component. You can now use this router using a simple XML file:

<eip:static-routing-slip service="test:routingSlip"  endpoint="endpoint">
        <eip:targets>
                <eip:exchange-target service="test:echo" />
                <eip:exchange-target service="test:echo" />
        </eip:targets>
</eip:static-routing-slip>

When installed this component provides the following routing options (this information is also available in the XSD of this component):

Camel Routing

Apache Camel is a project which provides a lof of different routing and integration options. In this section we'll show how to use Camel with ServiceMix and give an overview of the routing options it provides. Installing the Camel component in ServiceMix is done in the same way as we did for the EIP component. We use the features/list command to check what's already installed and we can use features/add to add new Camel functionality. Once installed we can use Camel to route messages between our components. Camel provides two types of configuration: XML and Java based DSL, XML configuration was used for the following two listings:

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <import resource="classpath:org/Apache/servicemix/camel/nmr/camel-nmr.xml" />
        <camelContext xmlns="http://camel.Apache.org/schema/spring">
        <route>
                <from uri="ftp://gertv@localhost/testfile?password=secret"/>
                <to uri="nmr:IncomingOrders"/>
        </route>
</beans>                             

<beans xmlns:file="http://servicemix.Apache.org/file/1.0"
        xmlns:dzone="http://servicemix.org/dzone/">
        <import resource="classpath:org/Apache/servicemix/camel/nmr/camel-nmr.xml" />
        <file:sender service="nmr:IncomingOrders" directory="file:target/pollerFiles" />
</beans>                     

In these two listings you can see how we can easily integrate the Camel routes with the other components from ServiceMix. We use the nmr prefix to tell Camel to send the message to the NMR. The other service, which can be seperately deployed will then pick-up this message since it's also configured to listen to a nmr prefixed service.

Now let's look at two listings that use Camel's Java based DSL to configure the routes. For this we need a small XML file describing where the routes can be found, and a Java file which contains the routing.

<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-2.0.xsd
        http://activemq.Apache.org/camel/schema/spring
        http://activemq.Apache.org/camel/schema/spring/camel-spring.xsd">

<import resource="classpath:org/Apache/servicemix/camel/nmr/camelnmr.xml" />
        <camelContext xmlns="http://activemq.Apache.org/camel/schema/spring">
                <package>dzone.refcards.camel.routes</package>
        </camelContext>
</beans>

public class SimpleRouter extends RouteBuilder {
        public void configure() throws Exception {
                from("timer:myTimerEvent?fixedRate=true")
                        .setBody(constant("Hello World!")).
                                to("nmr:someService");
        }
}

Camel itself provides a lot of standard functionality. It doesn't just provide routing, it can also provide connectivity for different technologies. For more information on Camel please see it's website at http://camel.Apache.org/ or look at the "Enterprise Integrations Patterns with Camel" Refcard.

Support for Web services is an important feature for an ESB. ServiceMix uses the CXF project for this. Since CXF is also completely spring based, using CXF to deploy Web services is very easy.

Hosting Web services

When you want to expose a service as a webservice you can easily do this using CXF. Just create a CXF OSGi bundle using the archetype: servicemix-osgicxf-code-first-archetype. This will create an OSGi and CXF enabled maven project which you can use to develop webservices. Now just edit the src/main/ resources/META-INF/spring/beans.xml file and after you've run the mvn install command you can deploy the bundle to ServiceMix. The following listing shows such an example. This will create a Web service and host it on http://localhost:8080/cfx/HelloDzone.

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:jaxws="http://cxf.Apache.org/jaxws"
        xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://cxf.Apache.org/jaxws http://cxf.Apache.org/schemas/jaxws.
        xsd">

        <import resource="classpath:META-INF/cxf/cxf.xml" />
        <import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
        <import resource="classpath:META-INF/cxf/cxf-extension-http.xml" />
        <import resource="classpath:META-INF/cxf/osgi/cxf-extensionosgi.xml" />
        <jaxws:endpoint id="helloDZone"
                implementor="dzone.examples.ws.HelloDZoneImpl"
                        address="/HelloDzone"/>
</beans>     

In the previous example we hoseted a Web service which could be called from outside the container. You can also configure CXF to host the Web service internally by prefixing the address with nmr. That way you can easily expose JAX-WS annotated java beans to the other services inside the ESB. The following example shows this:

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

        <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/cxftransportnmr.xml" />
        <jaxws:endpoint id="helloDzone"
                implementor="dzone.examples.ws.HelloDZoneImpl"
                        address="nmr:helloDZone" />
</beans>     

You can also host a Web services using the servicemix-cxf-bc component.

<beans xmlns:cxfbc="http://servicemix.Apache.org/cxfbc/1.0"
                xmlns:dzone="http://dzone.org/refcard/example">
        <cxfbc:consumer wsdl="classpath:dzone-example.wsdl"
                targetService="dzone:ExampleService"
                targetInterface="dzone:Example"/>
</beans>     

Consuming Web services

Consuming Web services in ServiceMix is just as easy. ServiceMix provides two different options for this. You can use Camel or use the servicemix-cxf-bc component:

<beans xmlns:cxfbc="http://servicemix.Apache.org/cxfbc/1.0"
                xmlns:dzone="http://dzone.org/refcard/example">
        <cxfbc:provider wsdl="classpath:target-service.wsdl"
                locationURI="http://webservice.com/Service"
                endpoint="ServicePort"
                service="dzone:ServicePortService"/>
</beans>     

With this configuration you can consume a Web service which is located at http://webservice.com/Service and which is defined by the WSDL file target-service.wsdl. Other services can use this component by making a call to the dzone:ServicePortService.

You can also consume a Web service using Camel. For more information on how you can configure the Camel route for this look at the Camel CXF integration section of the Camel website: http://camel.Apache.org/cxf.html.

For Web services ServiceMix provides the following useful archetypes:

Besides integration with Web services through CXF, ServiceMix provides a lot of components you can use out of the box to integrate with various other standards and technologies. In this section we'll give an overview of these components. This list is based on the 2009.1 versions. Most of this information can also be found in the XML schemas of these components.

ServiceMix Components