Fuse ESB - Deploying into the OSGi Container - The Fuse Mediation Router NMR Component

Overview

The NMR component is an adapter to the NMR, enabling Fuse Mediation Router applications to send messages to other bundles within the OSGi container or to components within the JBI container.

Installing the NMR feature

Normally, the NMR feature is pre-installed in the OSGi container. If you need to install the NMR feature, however, you can do so by entering the following console command:

karaf@root> features:install nmr

Instantiating the NMR component

To make NMR endpoints available to your Fuse Mediation Router application, you need to create an instance of the NMR component. Add the code shown in Example 12.1 to your bundle's Spring configuration file (located in META-INF/spring/*.xml) in order to instantiate the NMR component.

Example 12.1. Creating the NMR Component Bean

<?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://www.springframework.org/schema/osgi"
       xmlns:camel-osgi="http://camel.apache.org/schema/osgi"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/osgi  http://www.springframework.org/schema/osgi/spring-osgi.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/camel/schema/spring/camel-spring.xsd
       http://camel.apache.org/schema/osgi http://camel.apache.org/schema/osgi/camel-osgi.xsd">

    <bean id="nmr" class="org.apache.servicemix.camel.nmr.ServiceMixComponent">
        <property name="nmr">
            <osgi:reference interface="org.apache.servicemix.nmr.api.NMR" />
        </property>
    </bean>

</beans>

The bean element creates an instance of the NMR component with the bean ID, nmr, where this bean ID can then be used as the scheme prefix to create or reference NMR endpoints in your Fuse Mediation Router routes. The bean definition references two external Java packages—org.apache.servicemix.camel.nmr and org.apache.servicemix.nmr.api—which must therefore be imported by this bundle. Because the packages do not occur in Java source code, you must add them explicitly to the list of imported packages in the bundle instructions in the POM—see Configuring the bundle instructions for details.

URI format for the NMR component

The NMR component enables you to create endpoints with the following URI format:

nmr:EndpointId

Where EndpointId is a string that identifies the endpoint uniquely. In particular, when used within the OSGi container, the endpoint ID string is not restricted to have any particular format. The scheme prefix, nmr, is actually determined by the ID of the bean that instantiates the NMR component—for example, see Example 12.1.

Addressing JBI endpoints

If you want to use the NMR component to send messages between the OSGi container and the JBI container, you need to be aware that NMR endpoints inside the JBI container requires a special syntax for the endpoint IDs. You can address an NMR endpoint inside the JBI container using the following URI format:

nmr:JBIAddressingURI

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

Determining the message exchange pattern

An NMR consumer endpoint automatically determines the message exchange pattern (for example, In or InOut) from the incoming message and sets the message exchange pattern in the current exchange accordingly.

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, as follows:

The first route is defined as follows:
1. At the start of the route is a timer endpoint, which generates a heartbeat event every two seconds.
2. 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:

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

Defining the route in a Spring XML file

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

Example 12.2. 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://www.springframework.org/schema/osgi"
       xmlns:camel-osgi="http://camel.apache.org/schema/osgi"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/osgi  http://www.springframework.org/schema/osgi/spring-osgi.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
       http://camel.apache.org/schema/osgi http://camel.apache.org/schema/osgi/camel-osgi.xsd">

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

  <camel-osgi:camelContext xmlns="http://camel.apache.org/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>
  </camel-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. In fact, the content of this snippet is identical to the XML code shown in Example 12.1.
	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.

Configuring the bundle instructions

Not all of the packages required by the NMR component can be automatically detected by the Maven bundle plug-in. Some of the package dependencies arise from settings in the Spring configuration file (see Example 12.1), which are not automatically taken into account by the bundle plug-in. In particular, you must ensure that the following additional packages are imported by the bundle:

org.apache.servicemix.camel.nmr
org.apache.servicemix.nmr.api

For example, the following sample configuration of the Maven bundle plug-in shows how to add an Import-Package element that contains a list of the packages required for the NMR component:

<project ...>
    ...
    <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.servicemix.camel.nmr,org.apache.servicemix.nmr.api,*</Import-Package>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

The Import-Package list also includes the wildcard, *, which instructs the bundle plug-in to scan the Java source code in order to discover further package dependencies.