Instant Apache ServiceMix How-to

Before we install ServiceMix, we need to decide the distribution we want to use. ServiceMix comes in two flavors. The first one is a standard open source bundle—usually called ServiceMix. The second popular type of ServiceMix distribution (provided by the commercial vendor FuseSource) is called FuseESB.

In this book we will focus on the standard ServiceMix distribution. The argument behind this decision is that pure ServiceMix is an open source project from the Apache Software Foundation, and for learning purposes, it is always better to stick to the open Apache standards. However, migrating from ServiceMix to FuseESB is a painless process, so if you know how to use ServiceMix, you will also know how to deal with the FuseESB as well.

Before we start, make sure that you have Java JRE Version 6 installed on your machine. Also make sure that you have got at least 100 MB of free hard disk space. ServiceMix can be installed on machines running either Unix or Windows operating systems.

Begin by downloading a ServiceMix distribution from one of the Apache mirror sites. Suggested locations are listed on the ServiceMix download page (http://servicemix.apache.org/downloads.html). The ServiceMix downloads are available in several flavors, called assemblies. For now, we are interested in the latest Default assembly of ServiceMix available for your platform. If you are curious what the other flavors of ServiceMix available for download are, read the There's more… section of this recipe.

After you download the archive appropriate for your operating system, decompress it to the desired directory. From this point onwards, we will refer to this directory as SERVICEMIX_HOME.

If you want to make a quick sanity check of your ServiceMix installation, use the command line to navigate to your SERVICEMIX_HOME directory and execute the following (bin/servicemix.bat if you are running on Windows):

script – bin/servicemix

If you see an output similar to the following, then you can congratulate yourself, as you have just started your very first ServiceMix container.

ServiceMix comes in several flavors and distributions. Some of them are maintained by commercial companies. Here is some extra information that will throw more light on these issues.

In order to use JBI with ServiceMix, download the version of ServiceMix distribution called the JBI assembly. The installation process of the JBI-ready ServiceMix is exactly the same as in the case of a regular ServiceMix distribution described in the previous recipe. The only difference is that you need to download JBI assembly from the ServiceMix downloads page (http://servicemix.apache.org/downloads.html).

The details of the installation process of the ServiceMix bundle is described in the previous recipe.

This section provides some additional information associated to JBI and ServiceMix working together.

In all the recipes of this book, we will refer to the ServiceMix installation directory as SERVICEMIX_HOME. Note that, in fact, there is no environmental variable with such a name. This is just a logical term that will make ServiceMix examples clearer (you can think of it as a variable in a programming language).

So before we start, make sure that you have ServiceMix properly installed on your hard drive. You also need to know the value of your SERVICEMIX_HOME (that is, where ServiceMix has been installed).

Execute ServiceMix's start script (SERVICEMIX_HOME/bin/start for Unix and SERVICEMIX_HOME/bin/start.bat for Windows).

Just after you confirm the start command, ServiceMix will be executed as a background process. That also means that the command-line control will be returned to you almost immediately.

After you start ServiceMix, it should validate that the start command has actually done what it ought to. To check that everything went as we expected, connect to the running ServiceMix instance with the shell. You can do it with the following command-line instruction:

SERVICEMIX_HOME/bin/client -u smx -p smx

If you start ServiceMix on Windows instead of Unix, use the following version of the client command:

SERVICEMIX_HOME/bin/client.bat -u smx -p smx

The following screenshot shows how the ServiceMix shell looks like:

After you connect to ServiceMix with the interactive shell, you can fire the log:tail command to track ServiceMix's log (similarly as you would with Unix's tail command). To stop displaying logs with the tail command, press Ctrl + C in the ServiceMix console. An example of the output of the tail session is shown as follows:

smx@root> log:tail 
22:04:01,608 | INFO  | rint Extender: 3 | TransportServerThreadSupport     | 50 - org.apache.activemq.activemq-core - 5.5.1 | Listening for connections at: stomp://localhost:61613
22:04:01,610 | INFO  | rint Extender: 3 | TransportConnector               | 50 - org.apache.activemq.activemq-core - 5.5.1 | Connector stomp Started
22:04:01,611 | INFO  | rint Extender: 3 | BrokerService                    | 50 - org.apache.activemq.activemq-core - 5.5.1 | ActiveMQ JMS Message Broker (default, ID:drone-48785-1340136241458-0:1) started
^C
smx@root>

It is easy to guess that if you want to stop ServiceMix, you need to use a command similar to the one you used to start it:

SERVICEMIX_HOME/bin/stop

And the following command on the Windows operating system:

SERVICEMIX_HOME/bin/stop.bat

You can check whether ServiceMix has been stopped properly by looking into the container logfile. The location of the ServiceMix logfile is SERVICEMIX_HOME/data/log/servicemix.log. After you stop your ServiceMix instance, information similar to that presented as follows will be appended at the end of the logfile:

22:08:38,615 | INFO  | FelixStartLevel  | Activator                        | 4 - org.ops4j.pax.logging.pax-logging-api - 1.6.3 | Disabling SLF4J API support.
22:08:38,615 | INFO  | FelixStartLevel  | Activator                        | 4 - org.ops4j.pax.logging.pax-logging-api - 1.6.3 | Disabling Jakarta Commons Logging API support.
22:08:38,616 | INFO  | FelixStartLevel  | Activator                        | 4 - org.ops4j.pax.logging.pax-logging-api - 1.6.3 | Disabling Log4J API support.
22:08:38,616 | INFO  | FelixStartLevel  | Activator                        | 4 - org.ops4j.pax.logging.pax-logging-api - 1.6.3 | Disabling Avalon Logger API support.
22:08:38,616 | INFO  | FelixStartLevel  | Activator                        | 4 - org.ops4j.pax.logging.pax-logging-api - 1.6.3 | Disabling JULI Logger API support.

The commands we presented in this recipe are, in fact, administrative commands of the Apache Karaf container. When you start ServiceMix, you actually start a Karaf instance and tell it to load ServiceMix OSGI modules. The typical ServiceMix modules are Camel-based routes, embedded ActiveMQ message brokers, CXF web services, or Spring contexts.

Following is some interesting information that will be useful when you start to work with ServiceMix and Apache Karaf.

Displaying the tail of the logfile is a very convenient way of tracking the ServiceMix activity. You might be interested in some tips that would make working with the tail command even smoother.

tail -f -n 100 SERVICEMIX_HOME/data/log/servicemix.log

The default location of the ServiceMix logfile is SERVICEMIX_HOME/data/log/servicemix.log. You can open this file with your favorite text editor and check that the running ServiceMix instance tells you pretty much about its activity by adding interesting records to its logfile. Unfortunately, logfiles tend to get extremely large as the application continues to append new records to the log. This is the reason why opening logfiles in text editors is considered as a bad practice—the majority of the text editors do not handle large text files well; especially when some other process is still appending to the latter file.

Instead of opening the log in the text editor, we tail it, that is, display only a certain number of lines from the end of the file.

The usual method of displaying application logs is to use Unix's tail command. This command, however, is natively available only for Unix systems. The ServiceMix method of checking its own logs is to use the tail command available in the interactive console.

The log:tail command available in the ServiceMix console works similar to the tail -f command available under Unix systems. It displays the last lines of the logfiles and continues to show the new ones appended to the file, as shown here:

2012-06-23 21:41:42,589 | INFO  | rint Extender: 1 | KarArtifactInstaller  | ?   ? | 42 - org.apache.karaf.deployer.kar - 2.2.4 | Karaf archives will be extracted to /home/hekonsek/Desktop/apache-servicemix-4.4.2/local-repo 2012-06-23 21:41:42,590 | INFO  | rint Extender:1 | KarArtifactInstaller  |  ?  ? | 42 - org.apache.karaf.deployer.kar - 2.2.4 | Timestamps for Karafarchives will be extracted to /home/hekonsek/Desktop/apache-servicemix-4.4.2/local-repo/.timestamps
2012-06-23 21:41:42,637 | INFO  | FelixStartLevel  | ultOsgiApplicationContextCreator | ?  ? | 76 - org.springframework.osgi.extender - 1.2.1 | Discovered configurations {osgibundle:/META-INF/spring/*.xml} in bundle [Apache CXF Bundle Jar (org.apache.cxf.bundle)]To stop displaying the log,press Ctrl+C. The ServiceMix console will stop processing the log file and will return to the prompt.
2012-06-23 21:41:52,178 | INFO  | rint Extender: 3 | TransportServerThreadSupport  | ?  ? | 50 -org.apache.activemq.activemq-core - 5.5.1 | Listening for connections at: stomp://localhost:616132012-06-23 21:41:52,179 | INFO  | rint Extender: 3 | TransportConnector  | ?  ? | 50 - org.apache.activemq.activemq-core - 5.5.1 | Connector stomp Started 2012-06-23 21:41:52,180 |INFO  | rint Extender: 3 | BrokerService  | ?  ? | 50 - org.apache.activemq.activemq-core - 5.5.1 |ActiveMQ JMS Message Broker (default, ID:drone-49934-1340480512024-0:1) started ^C
karaf@root>

The tail of the file includes the last records from the ServiceMix log, to which the container appends by default. Even if the logfile is very long, the tail command displays only the most recent lines. The tailed logfile will also be monitored for new records, which will be displayed on the screen as they appear.

The Log4j (http://logging.apache.org/log4j) configuration file used by ServiceMix to read the logging configuration is located at SERVICEMIX_HOME/etc directory and named org.ops4j.pax.logging.cfg. This file is a regular Log4J configuration file, so all you need to do in order to adjust your logging setting is to change some Log4J properties.

Under the hood, ServiceMix uses Pax Logging (http://www.ops4j.org/projects/pax/logging) as a logger service. Pax is an OSGI-based wrapper for existing logging services. By default, log messages are delegated to the one of the most popular logging frameworks in the Java environment—Log4J (http://logging.apache.org/log4j). This means that you can just edit ServiceMix's Log4j configuration file in order to change the default logging settings.

By default, the root logger of ServiceMix is set to the INFO level. The following is the content of the default Log4J configuration file provided with ServiceMix:

# Root logger
log4j.rootLogger=INFO, out, osgi:VmLogAppender
log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer

If you encounter some kind of problem with your integration solution deployed on ServiceMix, you would probably like to change the logging level to a more fine-grained one. The following is the default ServiceMix logger configuration file with the logging level changed to DEBUG:

# Root logger
log4j.rootLogger=DEBUG, out, osgi:VmLogAppender
log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer

After the configuration file is saved, you will notice that the default logging level is now set to DEBUG instead of INFO. Keep in mind that the DEBUG logging level should be used only for the time of debugging the problem, as it generates much more log information than INFO.

Log4j is not the only logging API available in the Java universe. Take a look at the following information in order to know more about ServiceMix's support for the other logging libraries. You may also be interested in knowing some details related to the startup of the ServiceMix logging system.

Usually a static logger configuration defined in the properties file is not flexible enough for real-life deployment scenarios. A detailed level of logging leads to an excessive number of writes to the application log, which obviously leads to a performance penalty. The high number of messages also makes the application log less readable. That is why you usually would like to stick to the course-grained level of logging, such as info or even warning. Switching to the more detailed (fine-grained) logging (such as debug or trace) is useful when you try to spot a bug or want to analyze an unusual behavior in the system. However, due to performance reasons mentioned earlier, you would like the logger to report detailed information only for the time of the debugging session. With the interactive ServiceMix console, you can temporarily change the logging level to fine-grained, and when you are done with the bug, switch back again to the inexpensive brief one.

The ServiceMix console together with the Pax logging is an excellent tool to adjust the settings of your logger at runtime. In order to change the latter configurations when ServiceMix is running, you need to connect to your container with an interactive Karaf console.

Before you change the logging level of the given logger, you might want to check its current settings. To return to the current level of the given logger, issue the log:get command. The following code listing demonstrates an example of checking the current level of the selected logger.

smx@root> log:get com.example.Logger
Level: INFO

After you check the current level of the logger you are interested in, you can safely change it to the desired value. To change the level of a given logger, use the log:set command. The following code listing demonstrates how to change the logger settings during an interactive ServiceMix console session:

smx@root> log:get com.example.Logger
Level: INFO
smx@root> log:set DEBUG com.example.Logger
smx@root> log:get com.example.Logger
Level: DEBUG

At startup, ServiceMix reads the default settings of the Log4J logger from the SERVICEMIX_HOME/org.ops4j.pax.logging.cfg file. After the default settings are loaded, ServiceMix looks in the SERVICEMIX_HOME/data/cache directory for the changes in the logging configuration that have been made during the runtime of the container. The latter's settings (that is, the cached runtime) overrides the former (read from the static configuration saved in the etc directory). Any changes made to the logger configuration at runtime are immediately applied to ServiceMix and stored in the SERVICEMIX_HOME/data/cache directory.

Before you proceed to the next recipe, take a quick look at the following logging-related hints. You may find them useful when working with ServiceMix in a production environment.

Before you list the OSGI features installed in your running ServiceMix instance, you need to connect to it with the ServiceMix console.

Apache Karaf (the OSGI framework on top of which ServiceMix is built) organizes deployment units into modules called bundles. These modules can be installed, updated, or removed while ServiceMix is up and running (without the need to restart the container). After you install a new OSGI bundle containing your Camel route or CXF web service, you probably would like to see if the bundle together with its dependencies has been properly installed. This recipe demonstrates how you can list bundles deployed into your ServiceMix instance.

If you issue the osgi:list command in the interactive ServiceMix console, it will return results similar to the following output:

karaf@root> osgi:list
START LEVEL 100 , List Threshold: 50
  ID           State       Blueprint        Spring          Level                  Name
[ 43]      [Active]        [Created]          [ ]           [ 60]       activemq-broker.xml (0.0.0)
[ 45]      [Active]           [ ]             [ ]           [ 60]       kahadb (5.5.1)
[ 46]      [Active]           [ ]             [ ]           [ 60]       activemq-pool (5.5.1)
[ 47]      [Active]           [ ]             [ ]           [ 60]       activemq-console (5.5.1)
[ 48]      [Active]           [ ]             [ ]           [ 60]       Apache Aries Transaction Manager(0.2.0.incubating)
[ 49]      [Active]           [ ]             [ ]           [ 60]       activemq-ra (5.5.1)

Now you know how to display the list of the bundles installed into your ServiceMix instance. However, you are probably wondering about the exact meaning of each column displayed in the list:

The volume of output generated by the osgi:list command may be overwhelming. On the other hand, sometimes you will notice that not all bundles are displayed on the listing. The following hints will help you to deal with these problems.

Before you list the features available for your ServiceMix instance, you must connect to it with the interactive console.

After you issue the features:list command, you should see results similar to the following output:

karaf@root> features:listState        Version                 Name              Repository          Description

[installed]                              [2.2.4]             karaf-framework       karaf-2.2.4                    

[uninstalled]                         [2.5.6.SEC02]          spring                karaf-2.2.4                    

[uninstalled]                         [2.5.6.SEC02]          spring-web            karaf-2.2.4                    

[installed]                           [3.0.6.RELEASE]        spring                karaf-2.2.4                    

[uninstalled]                         [3.0.6.RELEASE]        spring-aspects        karaf-2.2.4                    

As you can see, the features:list command displays features available for your ServiceMix instance. If you take a closer look at the resulting output, you will see that a feature is identified by the name and the version (this is an identity technique similar to the one used in the OSGI bundles versioning). As you can also notice, features are located in the repositories (the last column of the listing tells you the name of the repository in which the feature is located). And last but not least, the very first column of the discussed listing indicates whether the given feature has been already installed in your ServiceMix container or not.

At first glance, you may be overwhelmed by the amount of the features available for your ServiceMix instance. The following hints may be useful to work efficiently with the features listings.

For the purpose of this recipe, we will assume that you have your ServiceMix instance already installed and running.

The easiest way to install the desired feature is to use the Apache Karaf console bundled with ServiceMix. After you open the console, list the features available for installation. The way to list features that can be installed into your ServiceMix container is described in the previous recipe.

ServiceMix uses features to group OSGI bundles into logical modules. When you install a given feature, Karaf retrieves all the necessary bundles from the feature repository. Downloaded artifacts are held in the SERVICEMIX_HOME/data/cache directory. For example, if you want to use the jibx data format in your application's routes, type feature:install camel-jibx. This command tells ServiceMix to download the feature and all the related bundles from the Camel features repository and install it into your container.

Working with the features listings can be difficult due to the high number of options available for the installation. The following hints will guide you through some of the tricks that will make browsing through the features listings easier.

karaf@root> features:install camel-
camel-ahc         camel-atom           camel-aws          camel-bam            camel-bean-validator 
camel-bindy       camel-cache          camel-cometd       camel-context        camel-crypto

Before we start, all you need to do is start your ServiceMix container.

In the ServiceMix shell, execute the following command: osgi:install wrap:mvn:groupId/artifactId/version. For example, to install Apache Commons Logging library in Version 1.1 as the OSGI bundle, type osgi:install wrap:mvn:commons-logging/commons-logging/1.1.

ServiceMix uses the OSGI bundles to organize the modules deployed into it (as well as their dependencies). If we want to use a JAR file as the OSGI dependency, it has to be OSGI-ready. We basically say that JAR is OSGI-ready when it contains a special file called META-INF/MANIFEST.MF filled with the proper bundle description. The main purpose of this file is to define the JAR meta-data, such as dependencies of a given OSGI module. The manifest file also includes the export line, which tells which Java packages contained within the JAR should be exposed as the public OSGI packages.

If you want to deploy a plain JAR as the OSGI dependency, you need to convert it into the OSGI bundle. The wrap protocol used in this recipe analyzes the dependencies of the JAR file and tries to create a generic OSGI manifest for it.

OSGI bundles are the main—but not the only—type of artifacts possible to deploy into ServiceMix. The following is some useful information regarding the OSGI bundles in the context of the ServiceMix topic.

In order to get advantage of the ServiceMix web console, install the feature in which it is contained. ServiceMix features are installed using the interactive shell, so connect to your container instance with the ServiceMix console before you proceed.

The Web Console is actually a feature of Apache Karaf. Since ServiceMix is based on Apache Karaf, it can benefit from the ability to monitor the container at runtime. When you install the webconsole feature, ServiceMix starts the embedded Jetty instance on port 8181. When the Web Console feature is installed, it will be automatically started even after ServiceMix is restarted.

The following screenshot shows how the ServiceMix Web Console could look:

The Karaf Web Console is a very powerful tool that can make the administration of ServiceMix much easier. However, there are some issues you should be aware of before you start to use the Web Console in a production environment.

To create a new Camel routing project, we will use the Maven Archetype mechanism (http://maven.apache.org/archetype/maven-archetype-plugin), so make sure that you have Maven properly installed and available in your command-line path.

We will also assume that your ServiceMix instance is already running.

We used the Maven Archetype mechanism to create a new Camel routing project. Archetypes are basically the templates of the projects that can be used to generate the stub of new Maven modules. In this particular case, we create the stub of the Camel routing module.

The Camel module we have created contains the Spring configuration file used to bootstrap it by ServiceMix. The mentioned Spring XML wiring file is located at camel-route/src/main/resources/META-INF/spring/camel-context.xml. By default, this file contains an initial Camel Context configuration and some sample routes that can be used as a base for your custom routing rules. Feel free to experiment a little bit and change the route to make it suitable for your needs. For example, in order to create the Camel route that sends a message to ServiceMix log every 5 seconds, you could replace the Camel Context definition in the camel-context.xml file with the following route:

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

In the preceding example, we used the Timer (http://camel.apache.org/timer.html) and Log (http://camel.apache.org/log.html) components of Apache Camel. To redeploy the route, just build it again with Maven (mvn install) and replace the file in SERVICEMIX_HOME/deploy with the new version of the generated artifact (camel-route/target/camel-route-1.0-SNAPSHOT.jar)

Apache Camel is a Swiss army knife for message routing and system integration. Since this book is focused only on ServiceMix, we will suggest you find more information about Camel itself. We will also write some additional information about how Camel cooperates with Karaf.

In the previous recipe you learned how to create and deploy a new Camel route module into your ServiceMix instance. In this recipe, we will show you how to update the routing module without restarting ServiceMix.

To make this recipe as simple as possible, we will demonstrate how to update the Camel routing module created in the previous recipe. Let's assume that you modified the routing module by changing the camel-context.xml file in the route project (just as a reminder, the file is located at camel-route/src/main/resources/META-INF/spring/camel-context.xml).

Camel routing modules can be deployed to ServiceMix without restarting the container. As soon as ServiceMix detects that a new version of the Camel routing module has been dropped into the deploy directory, it replaces the existing version of the bundle with the new one. For example, you could enrich your Camel context with the following route:

  <camel:route>
     <camel:from uri="file:///home/inbox"/>
     <camel:to uri="log:FROM-DIRECTORY"/>
  </camel:route>

The preceding routing rule reads files from the /home/inbox directory and sends their content as messages to the dedicated logger. After this modification, your Camel context will look liike the following XML snippet:

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

<camel:from uri="file:///home/inbox"/>
   <camel:to uri="log:FROM-DIRECTORY"/>
</camel:route>

After you redeploy the route, you will see that the /home/inbox directory will be automatically created by Camel. If you try to drop a text file into this directory, it will be picked up by Camel and sent to the ServiceMix logger.

Versioning of the modules deployed to ServiceMix is a powerful tool that can be used to simultaneously manage multiple versions of the same module.

ServiceMix comes with an embedded ActiveMQ JMS broker that listens to the client connections on the port 61616. In order to use the embedded broker, you don't have to perform any additional administrative activities. The embedded ActiveMQ broker distributed out of the box with ServiceMix is configured with default settings and is ready to be used.

ServiceMix starts the embedded AcvtiveMQ broker on port 61616. This is also the default port of the Camel ActiveMQ component. This basically means that when you deploy to your Camel route, similar to the one presented here, Camel will automatically connect to the embedded ActiveMQ broker instance:

<camel:route>
<camel:from uri="timer://fireJmsMessage?period=5000"/>
<camel:to uri="activemq:myQueue"/>
</camel:route>

Since Camel ActiveMQ with the default configuration also listens on the same port (and on localhost loopback address), it will by default connect to the ActiveMQ instance embedded in ServiceMix.

In the preceding example, we created the Camel route that sends message to the embedded ActiveMQ broker's queue named myQueue every five seconds.

ActiveMQ itself is a comprehensive and advanced messaging solution. It is possible to configure both your broker and client component (that is, the Camel endpoint) with a variety of parameters and options. This section will describe some of them, but remember that there is much more available out there.

In this recipe, we will assume that you have a standalone ActiveMQ broker installed, started, and is operational. To make the examples as simple as possible, we will also assume that the broker is exposed via the tcp://192.168.1.1:61616 TCP transport.

Connecting to the external ActiveMQ broker is very similar to working with the embedded ActiveMQ broker provided with ServiceMix. The only difference is that instead of using the default settings of the Camel ActiveMQ component, you need to configure your route to consume from (or produce to) the standalone ActiveMQ broker.

The Camel ActiveMQ component can be configured in many ways. One of the possible solutions is to register the component manually in the Spring application context. The following example demonstrates how to register and configure an ActiveMQ component in the Spring context:

<camel:camelContext xmlns="http://camel.apache.org/schema/spring">
  <camel:route>
         <camel:from uri="timer:jmsMessageTrigger?period=5000"/>
         <camel:to uri="activemq:myQueue"/>
   </camel:route>
</camel:camelContext>
<bean id="activemq" 
    class="org.apache.activemq.camel.component.ActiveMQComponent">
      <property name="brokerURL" value="tcp://192.168.1.1:61616"/>
</bean>

You can connect to many types of messaging brokers with ServiceMix. The Camel routing engine allows ServiceMix to integrate with any JMS-compatible messaging solutions. Camel also comes with support for some non-JMS messaging systems (such as XMPP, AMPQ, or Amazon SQS). The following is some additional information regarding the messaging support in ServiceMix.

ServiceMix uses Apache CXF as the preferred engine for its web service stack. In this recipe, we will use the Maven Archetype mechanism to generate a new OSGI module with CXF support enabled. The module with CXF support is the one that starts the CXF endpoint exposing in our service. Before we start our CXF module, we will again use Maven, this time to generate the Java code from the WSDL file.

As you can see, Maven is an essential tool to complete this task, so make sure that you have this useful utility properly installed in your system.

We will also assume that your ServiceMix instance is already installed and running.

A web service created from the WSDL file is called a contract-first web service. Web service created as a Java POJO with WSDL generated from it is called a code-first web service. In this recipe, we will focus on the contract-first services.

At the beginning of this recipe, you should generate the code-first CXF module you will work on. We will use the Maven archetype mechanism (http://maven.apache.org/archetype/maven-archetype-plugin) for this purpose.

The following Maven command can be used to generate a new CXF WSDL-first project:

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-cxf-wsdl-first-osgi-bundle -DgroupId=com.packtpub.servicemixhowto -DartifactId=cxf-wsdl-first-example -Dversion=1.0-SNAPSHOT

We use the servicemix-cxf-wsdl-first-osgi-bundle Maven archetype from the org.apachemix.tooling group as a template for our module. We name our project cxf-wsdl-first-example. We will create our example in the Maven group namespaced as com.packtpub.servicemix and assign it the 1.0-SNAPSHOT version.

The stub of the contract-first module we have just generated with Maven contains the following WSDL file under cxf-code-first-example/src/main/resources/wsdl/person.wsdl path.

This file defines the very simple WSDL contract that exposes the person service to the world. The person service can be used to generate friendly messages for the given name. The fragment of the person service WSDL file should look as the following snippet:

    <wsdl:message name="GetPersonRequest">

        <wsdl:part name="payload" element="typens:GetPerson"/>

    </wsdl:message>
    <wsdl:message name="GetPersonResponse">

        <wsdl:part name="payload" element="typens:GetPersonResponse"/>

    </wsdl:message>

    <wsdl:message name="UnknownPersonFault">

      <wsdl:part name="payload" element="typens:UnknownPersonFault"/>

    </wsdl:message>

    <wsdl:portType name="Person">

        <wsdl:operation name="GetPerson">

            <wsdl:input message="tns:GetPersonRequest"/>

            <wsdl:output message="tns:GetPersonResponse"/>

            <wsdl:fault name="UnknownPerson" message="tns:UnknownPersonFault"/>

        </wsdl:operation>

    </wsdl:portType>

    <wsdl:service name="PersonService">

        <wsdl:port binding="tns:PersonSOAPBinding" name="soap">

           <soap:address location="http://localhost:8080/cxf/PersonService" />

       </wsdl:port>

   </wsdl:service>

As you can see, a WSDL contract, even for the tiniest service, can be pretty long.

We started by generating the stub of the CXF project from the Maven archetype. The template of the project from which the module is built contains a sample WSDL file with a web service contract. What is important to us is that the generated project comes with the Maven CXF plugin configuration and basic Spring context bootstraping CXF endpoint.

Now we can generate classes from the WSDL file provided by us. The CXF Maven plugin will create the stub implementation of the service for us. Execute the following command to create Java classes from the WSDL contract, compile the source, and create a deployable ServiceMix module:

mvn install

If you deploy a JAR created by the preceding command to ServiceMix (cxf-code-first-example /target/cxf-code-first-example-1.0-SNAPSHOT.jar), the person service will be exposed under the http://localhost:8080/cxf/PersonService URL.

You are probably wondering why you should consider using contract-first web services in favor of the code-first approach, and how to deal with WSDL maintenance. The following tips may be useful for you, as they throw some light on these issues.

ServiceMix uses Apache CXF as an engine of its web service stack. In this recipe, we will create a Mavenized ServiceMix module, exposing Java code as a SOAP-based web service via the CXF endpoint. In order to generate such a module, we will use the Maven Archetype mechanism.

As you can see, Maven is an essential tool to complete this task, so make sure that you have this useful utility properly installed in your system. We will also assume that your ServiceMix instance is already installed and running.

We will start the development of our code-first web service module by generating a new Apache CXF code-first project from the Maven Archetype (http:/maven.apache.org/archetype/maven-archetype-plugin). The following Maven command can be used to generate a new module from the archetype named org.apache.servicemix.tooling:servicemix-cxf-code-first-osgi-bundle:

mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-cxf-code-first-osgi-bundle -DgroupId=com.packtpub.servicemix -DartifactId=cxf-code-first-example-Dversion=1.0-SNAPSHOT

The generated project will contain the bootstrap configuration of the OSGI-based ServiceMix module with the Spring configuration, as well as the simple Person web service written in JAX-WS:

package com.packtpub.servicemix;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebParam.Mode;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlSeeAlso;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;
@WebService
@XmlSeeAlso({com.packtpub.servicemix.types.ObjectFactory.class})
public interface Person {

    @RequestWrapper(localName = "GetPerson", className = "com.packtpub.servicemix.types.GetPerson")

    @ResponseWrapper(localName = "GetPersonResponse", className = "com.packtpub.servicemix.types.GetPersonResponse")
    @WebMethod(operationName = "GetPerson")
    public void getPerson(
        @WebParam(mode = WebParam.Mode.INOUT, name = "personId")
        javax.xml.ws.Holder<java.lang.String> personId,
        @WebParam(mode = WebParam.Mode.OUT, name = "ssn")
        javax.xml.ws.Holder<java.lang.String> ssn,
        @WebParam(mode = WebParam.Mode.OUT, name = "name")
        javax.xml.ws.Holder<java.lang.String> name
    ) throws UnknownPersonFault;

}

Maven Archetype also generates the stub implementation of the Person service. The implementation class is responsible for handling the actual business logic of the service:

package com.packtpub.servicemix;

import javax.jws.WebService;
import javax.xml.ws.Holder;
import com.packtpub.servicemix.types.GetPerson;
import com.packtpub.servicemix.types.GetPersonResponse;
@WebService(serviceName = "PersonService", endpointInterface = "com.packtpub.servicemix.Person")
public class PersonImpl implements Person {

    public void getPerson(Holder<String> personId, Holder<String> ssn, Holder<String> name)
        throws UnknownPersonFault
    {
        if (personId.value == null || personId.value.length() == 0) {
            com.packtpub.servicemix.types.UnknownPersonFault fault 
= new com.packtpub.servicemix.types.UnknownPersonFault();
            fault.setPersonId(personId.value);
            throw new UnknownPersonFault(null,fault);
        }
        name.value = "Guillaume";
        ssn.value = "000-000-0000";
    }

}

We will not delve into the details of the JAX-WS annotations here. If you are interested in a good tutorial about JAX-WS web services, I recommend you read the excellent book from O'Reilly Publishing, called Java Web Services: Up and Running, authored by Martin Kalin.

The Person service is exposed via the CXF JAX-WS endpoint in the bean.xml file:

    <jaxws:endpoint id="HTTPEndpoint"

        implementor="com.packtpub.servicemix.PersonImpl"

        address="/PersonServiceCF"/>

When you deploy the generated CXF module to ServiceMix, it starts a new Spring context defined in the beans.xml file. In particular, the CXF endpoint is started and exposes the PersonImpl instance to the outside world via the /cxf/PersonServiceCF URL. If you add the ?WSDL parameter at the end of the service URL (http://localhost:8181/cxf/PersonServiceCF?WSDL), you will see the WSDL file generated by the CXF stack.

To validate that your CXF module has been successfully deployed to ServiceMix, open the URL mentioned above in the browser (as demonstrated in the following screenshot):

If you want to expose a new code-first service via ServiceMix and CXF, all you need to do is to create a new JAX-WS-compatible service and register it in cxf-code-first-example/src/main/resources/META-INF/spring/beans.xml as the JAX-WS endpoint.

Code-first is probably the most popular approach to web services development. If you are interested in the code-first approach with JAX-WS, you might also be interested in the tips presented here.

Let's start by creating a new Camel module for ServiceMix. The recipe titled How to create and deploy a new Camel route explains how to do this. As the name of the generated artifact, choose rest-example. The command you need to execute is presented here.

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes-DarchetypeArtifactId=camel-archetype-spring -DgroupId=com.packtpub.servicemixhowto -DartifactId=rest-example -Dversion=1.0-SNAPSHOT

In order to expose the class via the restful web service, we need to create this class in the first place. Save the following content to the rest-example/src/main/java/c om/packtpub/servicemixhowto/PersonService.java file.

To expose our Java class as a web service, we will use JAX-RS annotations. JAX-RS (Java API for RESTful Web Services) is the JEE standard for exposing REST web services in Java:

package com.packtpub.servicemixhowto;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.xml.bind.annotation.XmlRootElement;

@Path("person")
public class PersonService {

    @GET
    @Produces("application/xml")
    public Person getPersonByName(@QueryParam("name") String name) {
        return new Person(name);
    }
}

@XmlRootElement
class Person {

    private String name;

    public Person(){
    }

    public Person(String name) {
        this.name = name;

    public String getName() {
        return name;
    }


    public void setName(String name) {
        this.name = name;
    }
}

The PersonService class is a simple JAX-RS-compatible class. The Person object is a POJO (Plain Old Java Object) annotated with the JAXB annotations. We use JAXB to tell the Java runtime how the response object generated by the service should be converted to XML. JAXB (Java Architecture for XML Binding) is JEE standard for creating bidirectional mappings between XML and Java objects. For the purpose of this recipe, we assume that you already know the basics of JAX-RS and JAXB specifications.

The following camel-context.xml file demonstrates how Spring together with CXF can be used to expose the PersonService bean via the JAX-RS restful API:

1.	<beans xmlns="http://www.springframework.org/schema/beans"
2.	       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3.	       xmlns:jaxrs="http://cxf.apache.org/jaxrs"
4.	       xsi:schemaLocation="
5.	       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
6.	       http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd">
7.

8.	 <bean id="personService" class="com.packtpub.servicemixhowto.PersonService" />

9.	    <jaxrs:server id="restService"
10.	                  address="http://localhost:9000/rest">
11.	        <jaxrs:serviceBeans>
12.	            <ref bean="personService"/>
13.	        </jaxrs:serviceBeans>
14.	    </jaxrs:server>

15.	</beans>

The line 8 defines the singleton instance of our PersonService class using the standard Spring mechanisms.

Lines 9-14 start the CXF restful server. The restful API will be exposed via the HTTP connector on port 9000. All services will start with the /rest prefix.

In lines 11-13, we wire our instance of the PersonService class into the CXF server. Beans marked with the JAX-RS annotations (such as @Path) and wired to the JAX-RS server are automatically exposed under the appropriate URL. In this particular example, the annotation @Path("person") tells CXF to expose the PersonService class under the http://localhost:9000/rest/person URL.

If you deploy your Camel module into ServiceMix and try to connect to the previously mentioned URL with an HTTP GET method and name parameter (http://localhost:9000/rest/person?name=foo), CXF will call the appropriate method (getPersonByName) of the PersonService class.

The results will be serialized to XML using the JAXB API. The response you will see in the web browser will look like the following XML listing:

<person>
<name>foo</name>
</person>

Remember that in order to compile your JAX-RS-annotated classes (such as PersonService), you need to include the JAX-RS API in your pom.xml file:

  <dependencies>
    ...
        <dependency>
              <groupId>javax.ws.rs</groupId>
              <artifactId>jsr311-api</artifactId>
              <version>1.1</version>
        </dependency>
    …
  </dependencies>

This recipe uses the JAX-RS API in order to expose a simple POJO bean as a web service. In the following, you can find some additional information related to the JAX-RS.

<bean id="jsonProvider" class="org.apache.cxf.jaxrs.provider.json.JSONProvider"/>

    <jaxrs:server id="restService"

                  address="http://localhost:9000/rest">

        <jaxrs:serviceBeans>

            <ref bean="personService"/>
        </jaxrs:serviceBeans>

    <jaxrs:providers>

      <ref bean="jsonProvider"/>

    </jaxrs:providers>

    </jaxrs:server>

@GET

 @Produces("application/json")

 public Person getPersonByName(@QueryParam("name") String name) {

{"person":{"name":"foo"}}

Let's assume that your integration solution reads from several sources of messages and then processes them using some custom processing class:

1.	public class NonClusteredRoute extends RouteBuilder {
2.
3.   public void configure() throws Exception {
4.    
5.    from("direct:processor").process(new BusinessProcessor()).to("jms:processedMessages");
6.	
7.	    from("file:/home/myapp/inbox").to("direct:processor");
8.	    from("jms:incomingMessages").to("direct:processor");
9.	    from("pop3://username@mymailserver.com?password=secret").
10.	      to("direct:processor");
11.	  }
12.	
13.	}

Lines 5-6 tell Camel to use BusinessProcessor in order to process messages incoming to the system.

Line 7 defines the File consumer, which reads data from the local file system and converts it into the messages ready to be consumed by BusinessProcessor.

Line 8 defines a JMS consumer reading messages directly from the queue named incomingMessages.

Lines 9-10 create a POP3 consumer that reads e-mails from the mail.com server and sends them to the same BusinessProcessor as the rest of the system does.

The problem with the integration solution above is that whenever BusinessProcessor processes the messages too slow, reading from the source endpoints will wait idle until our system will process the incoming messages.

What we want to do is to cluster the solution above, so we could split it across many machines. In order to achieve ServiceMix clustering, we will take advantage of the JMS feature called competing consuming.

At some point of the load, your integration solution will become incapable of processing incoming messages. Or at least incapable of processing incoming messages within the required period of time. Such a scenario happens usually when the Camel consumer endpoints start to receive more messages than the processing part of the solution can handle.

One approach to the load issue is to scale your ServiceMix up. Scaling up means basically the same as scaling vertically, that is, adding more hardware resources to the single ServiceMix instance. Of course, more CPU, additional cores, or some extra memory can make your ServiceMix process incoming messages faster.

But you cannot add additional resources to the same physical machine infinitely. At some point, even the strongest (and most terribly expensive) computer will reach its limits. And this will basically mean that all the money invested into your super-computer will become insufficient.

In practice, software architects rarely scale their solutions up. Instead they scale their architecture out (horizontally). Scaling out means adding more processing nodes to the existing software infrastructure. So how can multiple ServiceMix instances communicate with each other in order to process incoming messages concurrently? We have to split our monolithic route into three smaller consumer routes—each one will read from another message source.

The following route demonstrates how can we read from file system and immediately forward processing to the JMS queue.

1.	public class FileRoute extends RouteBuilder {
2.	
3.	  public void configure() throws Exception {
4.	    from("file:/home/myapp/inbox").to("jms:businessQueue");
5.	  }
6.	
7.	}

In line 4 of the preceding route, we read messages from the file system and then send them to the common JMS queue named businessQueue.

The following route applies the same logic to the source JMS queue:

public class JmsRoute extends RouteBuilder {

  public void configure() throws Exception {
   	from("jms:incomingMessages").to("jms:businessQueue");
  }

}

The fourth line of the above route forwards messages from the source JMS queue (incomingMessages) to the same common queue as the rest of the source routes (FileRoute and MailRoute).

public class MailRoute extends RouteBuilder {

  public void configure() throws Exception {
     from("pop3://username@mymailserver.com?password=secret").to("jms:businessQueue");
  }

}

All the source routes (FileRoute, MailRoute, and JmsRoute) delegate the processing logic to the dedicated ServiceMix instances. Messages to be processed are sent to the JMS queue named businessQueue. The following code listing demonstrates how Camel can be used to read from that queue and process the collected messages:

public class BusinessProcessingRoute extends RouteBuilder {

  public void configure() throws Exception {
   	from("jms:businessQueue").
      process(new BusinessProcessor()).
      to("jms:processedMessages");   
  }

}

We can deploy any number of BusinessProcessingRoute classes. JMS will take care of the synchronization of the consumers reading from the queue and guarantee us that each message from the businessQueue queue will be read only by one consumer (this feature of the JMS is called the competing consumers support).

Instead of having a single ServiceMix instance consuming messages from all possible sources, we created separated routes that read from the various sources independently and delegate processing to the JMS queue (businessQueue). If at some point of the message's traffic, two BusinessProcessingRoute routes will not be able to process the messages sufficiently fast, you can start another machine with the additional BusinessProcessingRoute deployed to it.