Chapter 9. Inter-Bundle Communication

Chapter 9. Inter-Bundle Communication with the NMR While the OSGi framework provides a model of synchronous communication between bundles (through method invocations on OSGi services), it currently does not provide a model of asynchronous communication. FUSE ESB therefore provides a non-standard mechanism to support asynchronous messaging, known as the Normalized Message Router (NMR), which is loosely based on the NMR defined in the JBI standard. Architecture of the NMR... 124 The FUSE Mediation Router NMR Component... 127 123

Chapter 9. Inter-Bundle Communication with the NMR Architecture of the NMR Overview Figure 9.1 on page 124 shows a general overview of the NMR architecture, which spans both the OSGi container and the JBI container. Figure 9.1. NMR Architecture In Figure 9.1 on page 124, the NMR is represented as a horizontal graphical element in order to emphasize its role linking together various application 124

Architecture of the NMR bundles. In practice, however, the NMR is deployed as a collection of bundles, just like any other application in the OSGi container. NMR The FUSE ESB NMR is a general-purpose message bus used for transmitting messages between bundles in the OSGi container. It is modelled on the Normalized Message Router (NMR) defined in the Java Business Integration (JBI) specification 1. Hence, the FUSE ESB NMR can be used to transmit XML messages, optionally augmented with properties and attachments. NMR for OSGi 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 or, if the JBI container is also deployed, to transmit messages between the two containers. Normalized messages A key feature of the NMR message bus is that messages are transmitted in a standard, normalized form. The JBI standard defines a normalized message, which is based on the Web Services Description Language (WSDL) message format (both WSDL 1.1 and WSDL 2.0 formats are supported). A complete normalized message has the following aspects: Content the main content of a normalized message must be in XML format, where the layout of a particular message is defined in a WSDL service description. Attachments for sending binary content, you can add attachments to the normalized message. Properties consist of name/value pairs. Security subject identifies the sender, if security features are enabled. Note When transmitting messages solely within the OSGi container, the normalization of message content is not enforced. That is, the OSGi container does not impose any restrictions on the format of the 1 http://www.jcp.org/en/jsr/detail?id=208 125

Chapter 9. Inter-Bundle Communication with the NMR message content. If messages are transmitted to an endpoint in the JBI container, however, message normalization must be observed. NMR API FUSE ESB provides a simple Java API for accessing the NMR. You can use this API to define endpoints that process messages received from the NMR and you can write clients that send messages to NMR endpoints. To see how to use this API in practice, take a look at the examples/nmr demonstration code. NMR component for FUSE Mediation Router To enable integration with the NMR, FUSE Mediation Router provides an NMR component, which lets you define NMR endpoints either at the beginning (for example, as in from("nmr:exampleendpoint")) or at the end (for example, to("nmr:exampleendpoint")) of a route. For full details of how to use the NMR component, see "The FUSE Mediation Router NMR Component" on page 127. Note The NMR component is designed specifically for integrating FUSE Mediation Router with the NMR within the OSGi container. If you deploy a FUSE Mediation Router application in the JBI container, however, NMR integration is provided by the JBI component. The NMR component (for use in an OSGi context) is conventionally identified by the nmr URI scheme, whereas the JBI component (for use in a JBI context) is conventionally identified by the jbi URI scheme. 126

The FUSE Mediation Router NMR Component 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 9.1 on page 127 to your bundle's Spring configuration file (located in META-INF/spring/*.xml) in order to instantiate the NMR component. Example 9.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 ht tp://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://www.springframework.org/schema/osgi ht tp://www.springframework.org/schema/osgi/spring-osgi.xsd http://camel.apache.org/schema/spring ht tp://camel.apache.org/camel/schema/spring/camel-spring.xsd http://camel.apache.org/schema/osgi ht tp://camel.apache.org/schema/osgi/camel-osgi.xsd"> <bean id="nmr" class="org.apache.servicemix.camel.nmr.ser vicemixcomponent"> <property name="nmr"> <osgi:reference interface="org.apache.service mix.nmr.api.nmr" /> </property> 127

Chapter 9. Inter-Bundle Communication with the NMR </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" on page 131 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 9.1 on page 127. 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 2. 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 2 http://servicemix.apache.org/uris.html 128

The FUSE Mediation Router NMR Component 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, as follows: 1. The first route is defined as follows: a. At the start of the route is a timer endpoint, which generates a heartbeat event every two seconds. b. At the end of the route is an NMR endpoint, which transmits the messages to the next route. 2. The second route is defined as follows: a. At the start of the second route is an NMR endpoint, which receives the messages sent by the first route. b. Next comes a callout to a transformer bean (implemented in Java), which transforms the hearbeat into a message containing the current date and time. c. 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 9.2 on page 129 shows the routes for the camel-nmr demonstration, taken from the Spring XML configuration file, META-INF/spring/beans.xml. Example 9.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" 129

Chapter 9. Inter-Bundle Communication with the NMR xmlns:camel-osgi="http://camel.apache.org/schema/osgi" xsi:schemalocation=" http://www.springframework.org/schema/beans ht tp://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://www.springframework.org/schema/osgi ht tp://www.springframework.org/schema/osgi/spring-osgi.xsd http://camel.apache.org/schema/spring ht tp://camel.apache.org/schema/spring/camel-spring.xsd http://camel.apache.org/schema/osgi ht tp://camel.apache.org/schema/osgi/camel-osgi.xsd"> <import resource="classpath:org/apache/service mix/camel/nmr/camel-nmr.xml" /> ❶ <camel-osgi:camelcontext xmlns="ht tp://camel.apache.org/schema/spring"> <!-- Route periodically sent events into the NMR --> <route> <from uri="timer://mytimer?fixedrate=true&peri od=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.ex amples.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 9.1 on page 127. At the end of the first route, messages are sent to the NMR endpoint, nmr:examplerouter. 130

The FUSE Mediation Router NMR Component ❸ 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 9.1 on page 127), 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.service mix.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. 131

132