Lighting the fuse

Tutorial: Managing Apache ServiceMix clusters with Fuse Fabric - Part 2

          

Walkthrough

Having introduced the concepts of Fabric, this last section aims to provide a quick introduction on how to practically use Fuse Fabric for deploying an integration project. Although one could download and run Fuse Fabric from its project web site, this part uses Fuse ESB Enterprise 7.1 as released by Red Hat. Fuse ESB Enterprise is based on Apache ServiceMix and already includes Fabric out-of-the-box. It is fully documented here. The default workflow when working with Fabric is as follows:

  1. Create a new Fabric. This starts the Fabric Registry and imports the default profiles.

  2. Create the Integration or SOA application using the technologies offered by ServiceMix.

  3. Define the deployment of the application plus its configuration in one or more Fabric Profiles.

  4. Create the required number of ESB containers and configure these containers for one or many profiles.

  5. Test or run the deployed application.

Lets go through these steps one by one.

Create a new Fabric

After installing Fuse ESB Enterprise 7.1, it can be started using the script ‘bin/fuseesb’. A few seconds later the welcome screen of the shell console is displayed.

 

|  ___|                 |  ___|/  ___|| ___ \ 
| |_  _   _  ___   ___  | |__  \ `--. | |_/ / 
|  _|| | | |/ __| / _ \ |  __|  `--. \| ___ \ 
| |  | |_| |\__ \|  __/ | |___ /\__/ /| |_/ / 
\_|   \__,_||___/ \___| \____/ \____/ \____/ 

  Fuse ESB (7.1.0.fuse-047) 
  http://fusesource.com/products/fuse-esb-enterprise/ 

Hit '<tab>' for a list of available commands 
and '[cmd] --help' for help on a specific command. 
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown Fuse ESB. 

FuseESB:karaf@root>

 

Tip: All Karaf shell commands take the --help argument which displays a quick man page of the command.

On its first start up this ESB container does not have a Fabric pre-configured. Its only a standalone ServiceMix installation with a number of OSGi bundles deployed. It is necessary to create a Fabric first using the Karaf shell commandfabric:create’. This reconfigures the current ESB container, deploys and starts the Fabric registry and imports the default profiles into the registry. Alternatively a container can join an existing fabric cluster using the command ‘fabric:join’ providing the URL of the already running Fabric registry. This Fabric enabled ESB container does not deploy any ESB functionality by default (use the command ‘osgi:list’ to verify). ESB functions get enabled by deploying the relevant profiles.

Create the Integration or SOA Application

Fuse ESB Enterprise 7.1 also comes with a couple of demos from which this article picks the examples/jms demo. It demonstrates how to connect to an ActiveMQ broker and use JMS messaging between two Camel based integration routes. The demo works in a plain ServiceMix environment but in this part it will be deployed to a Fabric enabled ESB container. This demo has only one interesting file, which is the Camel route definition located in ‘examples/jms/src/main/resources/OSGI-INF/blueprint/camel-context.xml’.

 

<camelContext xmlns="http://camel.apache.org/schema/blueprint" 
              xmlns:order="http://fusesource.com/examples/order/v7" 
              id="jms-example-context"> 

  <route id="file-to-jms-route"> 
    <from uri="file:work/jms/input" /> 
      <log message="Receiving order ${file:name}"/> 
      <to uri="activemq:incomingOrders" /> 
  </route> 

  <route id="jms-cbr-route"> 
    <from uri="activemq:incomingOrders" /> 
      <choice> 
        <when> 
          <xpath>/order:order/order:customer/order:country = 'UK'</xpath> 
          <log message="Sending order ${file:name} to the UK"/> 
          <to uri="file:work/jms/output/uk"/> 
        </when> 
        <when> 
          <xpath>/order:order/order:customer/order:country = 'US'</xpath> 
          <log message="Sending order ${file:name} to the US"/> 
          <to uri="file:work/jms/output/us"/> 
        </when> 
        <otherwise> 
          <log message="Sending order ${file:name} to another country"/> 
          <to uri="file:work/jms/output/others"/> 
        </otherwise> 
      </choice> 
    <log message="Done processing ${file:name}"/> 
  </route> 
</camelContext> 

 

This Camel context defines two Camel routes. The first route with the id=file-to-jms-route consumes a message from a file location on the local file system (directory work/jms/input). It then logs the file name and sends the content of the file to the incomingOrders queue on an external ActiveMQ broker.

The second Camel route with id=jms-cbr-route consumes messages from the incomingOrders JMS queue and runs a content-based routing. Depending on the XML payload of the message it gets routed to different target directories on the local file system. This is a simple yet fairly common integration use-case. Some small additional configuration is needed to tell Camel how to connect to the external ActiveMQ broker.

 

<!-- connects to the ActiveMQ broker --> 
<bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent"> 
  <property name="brokerURL" value="discovery:(fabric:default)"/> 
  <property name="userName" value="admin"/> 
  <property name="password" value="admin"/> 
</bean> 

Notice the brokerURL property. Rather than using a hard coded url like tcp://localhost:61616 the real broker address is queried from the Fabric registry at runtime using the Fabric MQ Extension. That way the broker can be moved to a different physical machine and clients automatically reconnect to the new broker address.

The demo can be build by running ‘mvn install’. This will install the generated OSGi bundle to the local Maven repository.

Define deployment

Now it's time to create the Fabric profiles that will deploy this integration project. Let’s assume there is a requirement to run the ActiveMQ broker externally in its own ESB container, which can be useful for various reasons like providing a common messaging infrastructure to a number of deployed applications. Therefore two ESB containers are required: one running the ActiveMQ broker, the other running the Camel integration route.

For running an ActiveMQ broker there is already a profile with the name mq provided out of the box. That ActiveMQ broker has a default configuration, which is sufficient for running this demo. The mq profile can simply be re-used so there is no need to create a new profile. The command ‘fabric:profile-list’ lists all available profiles. ‘fabric:profile-display profilename’ shows the content of a profile.

For running the Camel integration demo, the Camel runtime needs to be deployed to the ESB container. Furthermore, both Camel routes connect to the external ActiveMQ broker. So it's also necessary to deploy the ActiveMQ client libraries to this ESB container. ‘fabric:profile-list’ lists the following three profiles among others

 

FuseESB:karaf@root> profile-list 
[id]                                     [# containers] [parents] 
activemq-client                          0              default 
camel                                    0              karaf 
camel-jms                                0              camel, activemq-client
...

The profile activemq-client deploys the ActiveMQ client libraries needed for connecting to an ActiveMQ broker. The profile camel deploys the core Camel runtime (but not the many Camel components). Finally the profile camel-jms has two parent profiles named camel and activemq-client, so it deploys both of the ActiveMQ client libraries – the Camel core runtime and camel-jms component. When using the profile camel-jms as a parent, it will automatically deploy the Camel runtime and ActiveMQ client runtime.

fabric:profile-create --parents camel-jms camel-jms-demo

This command creates a new profile called camel-jms-demo and uses the profile camel-jms as its parent., which also needs to deploy the OSGi bundle of the ServiceMix demo. This can be added using the demo's Maven coordinates (the demo was previously built and installed to the local Maven repository) by invoking

fabric:profile-edit --bundles mvn:org.fusesource.examples/jms/7.1.0.fuse-047 camel-jms-demo

It modifies the camel-jms-demo profile and adds the demo's OSGi bundle that is identified by its Maven coordinates org.fusesource.examples/jms/7.1.0.fuse-047. That's all! Thanks to the out-of-the-box profiles it took only two Fabric shell commands to create a profile that fully deploys the Camel integration demo.

Create ESB containers

The last step is to create the two ESB containers that run the ActiveMQ broker and the Camel demo. For running the ActiveMQ broker in its own ESB container this command is all that is needed:

fabric:container-create-child --profile mq root activemq-broker

It creates a new local ESB container called ‘activemq-broker’ (using the existing installation of Fuse ESB Enterprise) with the parent container being the root container. It also deploys the mq profile, which runs the ActiveMQ broker. The ESB container could be created on a different machine, using the command ‘fabric:container-create-ssh. Running fabric:container-list’ verifies that the new ESB container got started. It is possible to connect to that container using ‘fabric:container-connect activemq-broker and check the log file using log:tail’. If the ActiveMQ broker got started successfully, the log will contain a line like:

Apache ActiveMQ 5.7.0.fuse-71-047 (activemq-broker, ID:XPS-49463-1357740918210-0:1) started.

With the broker running its time to deploy the camel-jms-demo profile to another ESB container. The existing root container only runs the Fabric Registry so the demo can be deployed to the root container using the command

fabric:container-add-profile camel-jms-demo root

This reconfigured the root container to also deploy the camel-jms-demo profile (the jms demo).

Test the application

The demo can finally be tested by copying a sample XML message to the work/jms/input folder that the first Camel route listens on. Fortunately some sample messages are provided with the demo. On a plain Unix or Windows shell run

cp examples/jms/src/test/data/order2.xml instances/camel-jms-demo/work/jms/input/

Right after copying the file will be picked up by Camel, get routed through the two Camel routes via JMS and is finally put into the target directory instances/camel-jms-demo/work/jms/output/uk/order2.xml. This verifies that the demo works correctly.

For users that aren't fans of command line tools, it is also possible to manage all aspects of a Fabric using the Fuse Management Console (FMC). The FMC is a graphical, browser based management tool for Fabric and a full alternative to using the Karaf Shell. It can be installed directly to the root ESB container using the command:

fabric:container-add-profile fmc root

Thereafter, it can be accessed from a browser using the url http://localhost:8181/index.html (see Figure 4). Discussing the details of the Fuse Management Console is outside of the scope of this article.

Figure 4: Fuse Management Console

Conclusion

Anyone who needs to manage multiple instances of ServiceMix should look into Fuse Fabric. The ability to describe all deployments centrally and roll them out to any number of ESB instances can greatly increase productivity and reduce management complexity.

Author Bio: 

Torsten Mielke works as a Senior Technical Support Engineer at Red Hat. He is part of the global professional support team at Red Hat and a specialist in open source enterprise integration and messaging systems. Torsten actively works on open source projects such as Apache ActiveMQ, Apache ServiceMix, Apache Camel and Apache CXF and is a committer on the Apache ActiveMQ project.

This article appeared in JAX Magazine: Socket to them!. For other articles and issues, click here.

Image courtesy of Razor512

Torsten Mielke
Torsten Mielke

What do you think?

JAX Magazine - 2014 - 03 Exclucively for iPad users JAX Magazine on Android

Comments

Latest opinions