Using the NMR Component

Overview

The NMR component is an adapter to the NMR, which is a general-purpose message bus that applications can use in order to communicate within the FUSE ESB OSGi container. It is modelled on the Normalized Message Router (NMR) defined in the Java Business Integration (JBI) specification. Hence, the FUSE ESB NMR can be used to transmit XML messages, along with properties and attachments. Unlike the standard NMR, however, the FUSE ESB NMR is not restricted to the JBI container. You can use the NMR to transmit messages inside the OSGi container, even if JBI is not deployed. Moreover, if you do deploy the JBI container, you can use the NMR for communicating between the two containers.

Installing the NMR component

The NMR component is installed in FUSE ESB as an OSGi bundle. The NMR component gets installed along with the NMR feature, which you can install by entering the following command:

features install nmr

Normally, the NMR feature is pre-installed in the OSGi container. In addition to installing the NMR feature, however, you also need to edit your application's Spring XML configuration file, META-INF/spring/*.xml, in order to instantiate the NMR component. The following XML import inserts a chunk of XML that takes care of instantiating the NMR component:

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

<beans xmlns="http://www.springframework.org/schema/beans" ... >
  ...
  <import resource="classpath:org/apache/servicemix/camel/camel-nmr.xml" />
  ...
</beans>

Because this import statement references the external package, org.apache.servicemix.camel, you also need to import this package in the Import-Package bundle header—see Example 1.6 for details.

URI format for the NMR component

The NMR component enables you to create and to reference endpoints using a JBI style of addressing. The general form of an NMR endpoint URI is as follows:

nmr:JBIAddressingURI

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

Specifying an InOut message exchange pattern

By default, an NMR endpoint supports oneway exchanges (In messages only). If you want to enable an NMR endpoint to send back a reply, you must explicitly enable this using the mep query option. To enable the InOut message exchange protocol on an NMR endpoint, simply append ?mep="in-out" to the URI. For example:

nmr:ExampleRouter?mep=in-out

camel-nmr demonstration

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

InstallDir/examples/camel-nmr

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

At the start of the route is a timer endpoint, which generates a heartbeat event every two seconds.
At the end of the route is an NMR endpoint, which transmits the messages to the next route.

The second route is defined as follows:

At the start of the second route is an NMR endpoint, which receives the messages sent by the first route.
Next comes a callout to a transformer bean (implemented in Java), which transforms the hearbeat into a message containing the current date and time.
At the end of the route is a log endpoint, which sends the transformed message to Jakarta commons logger.

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

Defining the route in a Spring XML file

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

Example 1.5. Spring XML Defining a Route with an NMR Endpoint

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

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://activemq.apache.org/camel/schema/osgi"
       xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
       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
       http://activemq.apache.org/camel/schema/osgi http://activemq.apache.org/camel/schema/osgi/camel-osgi.xsd
       http://www.springframework.org/schema/osgi-compendium http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd">

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

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

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

</beans>

This Spring import element imports a snippet of XML that instantiates and initializes the NMR component. The NMR component is exceptional in this respect: for most of the non-core components, you can put the relevant XML snippet directly into your Spring configuration file instead of importing it.

The location of the XML snippet is specified using the classpath URI, classpath:org/apache/servicemix/camel/camel-nmr.xml, which indicates that the XML file can be found on the current CLASSPATH. As a matter of fact, the camel-nmr.xml file is located in a separate bundle: that is, it is part of the org.apache.servicemix.camel.component bundle. Hence, it is necessary to import the org.apache.servicemix.camel bundle, in order to make this XML file accessible (see Example 1.6 for details of how this is done).

At the end of the first route, messages are sent to the NMR endpoint, nmr:ExampleRouter.

When you specify an NMR endpoint in the uri attribute of the <from> tag, a new NMR endpoint is created by the NMR component. In this example, the <from> tag implicitly creates the NMR endpoint, nmr:ExampleRouter, which is then capable of receiving the messages sent by the first route.

	Note
	The NMR is a general purpose message bus that operates independently of the JBI container. Hence, it is possible to create NMR endpoints outside the JBI container, as is done in this example.

Configuring the bundle headers

The bundle headers are defined in the JAR's manifest file, which is stored in the following location:

META-INF/MANIFEST.MF

Example 1.6 shows the manifest for the camel-nmr bundle (for a more detailed explanation of these manifest entries, see Example 1.3).

Example 1.6. Manifest for the camel-nmr Demonstration

Manifest-Version: 1.0
Built-By: YOURUSERNAME
Created-By: Apache Maven Bundle Plugin
Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
Import-Package: org.apache.commons.logging,org.apache.servicemix.camel
 .nmr,org.apache.servicemix.nmr.api
Bnd-LastModified: 1222082014067
Bundle-Version: 4.0.0.fuse
Bundle-Name: Apache ServiceMix Example :: Camel NMR
Bundle-Description: This pom provides project information that is comm
 on to all ServiceMix branches.
Build-Jdk: 1.5.0_08
Private-Package: org.apache.servicemix.examples.camel
Bundle-DocURL: http://www.apache.org/
Bundle-ManifestVersion: 2
Bundle-Vendor: The Apache Software Foundation
Bundle-SymbolicName: camel-nmr
Tool: Bnd-0.0.255

The important entries are the bundle headers that affect the interaction between the bundle and the OSGi container and these are, as follows:

Bundle-Name:: A human-readable name for the current bundle.
Bundle-SymbolicName:: A unique name for the current bundle.
Import-Package: