Setting up WebSphere ESB to Consume Messages from JBoss

Let’s look at how to pick up messages from an external JMS messaging provider (in this example, we’ll use JBoss), using the new Generic JMS Binding support in WebSphere ESB 6.1.

Firstly, create a JMS connection factory and queue (destination) in JBoss, or your external messaging provider.
Then, you need to set up the generic JMS provider administratively in WebSphere. Open the Admin Console for your server, and navigate to Resources / JMS / JMS Providers. Create a new JMS Provider at the scope that’s relevant to you. Give it a name (something simple – in this case, we’ll call it JBoss), and specify the initial context factory and the external provider URL. In our case, these are org.jnp.interfaces.NamingContextFactory and jnp://our.jboss.server.name:1099/. To find out what these are, you’ll need to consult the documentation for your JMS provider.

Next, you’ll next to make sure that the class you specify is available to the WebSphere server. Locate the JAR that contains it (in our case, it is called jbossall-client.jar and is distributed by JBoss). Place that JAR in the lib/ext/ directory of your server (and make sure to restart it).

Next, let’s create the mediation module. Start up WebSphere Integration Developer, and create a new Mediation Module. In our case, we’ll assume that the messages we are picking up from JBoss are JMS Bytes messages, so we are going to take the easy route and use the Simple JMS Bytes Data Binding. You could, of course, use a custom data binding.

Create a Library, and add the ‘Schema for Simple JMS Data Bindings’ to it. Make sure the mediation module depends on the library. Next, create an interface, and give it a single one-way operation, with a single parameter of type JMSBytesBody. This means that the interface will correspond to what the data binding we will use expects.

Add an export to the mediation module, and add the interface you just created to it. Now right-click, and select ‘Generate Binding / Message Binding / Generic JMS Binding…’. Leave the default of ‘Configure new messaging provider resources’. Don’t be fooled, you still need to create everything but the listener port. For ‘Generic JMS provider name’, enter the name you entered earlier in the Admin Console. For the connection factory and recieve destination, enter the JNDI values defined for these resources in JBoss. Add a data binding (as mentioned, in our case we are using the ‘Simple JMS BytesMessage Data Binding’), and a function selector. The default function selector will use the TargetFunctionName JMS header as the native method name – you can write a different function selector by implementing the commonj.connector.runtime.FunctionSelector interface, as we did for our example. Select OK to create the binding. Make sure your method bindings match the behaviour of your function selector.

You’ll probably want to connect your export to a mediation flow – initially, you can just display the SMO to see whether it’s working as intended.

Now, deploy the mediation module to your server. You should find it starts consuming messages from your JMS provider.

Understanding the Message Manipulation Primitives

Version 6.1 of WebSphere ESB has introduced the BO Mapper primitive, which brings the total number of primitives designed to manipulate or modify messages to three. People sometimes ask about the differences, so here they are:

• The Message Element Setter primitive is the simplest. It can be used to set an element in a message, copy a value from one part of a message to another, or delete an element of a message. In fact, the actions it performs are listed in a table, so you can perform an arbitrary combination of these if you wish. It also has the advantage that you can promote the values you use. If you wanted to set a field to a particular value, but you might want to change this later without redeploying the application, this primitive is probably the right one. The Message Element Setter primitive operates directly on the SMO (Service Message Object) flowing through the mediation flow. This primitive cannot change the type of a message.
• The BO (Business Object) Mapper primitive is similar, in that it operates directly on the Service Message Object, but it is designed to be able to map from one message type to another. It is therefore slightly more complicated (and different) to define, as you need to construct an entire mapping, but it effectively provides a superset of the functionality of the Message Element Setter – except that you cannot promote part of a BO Map. It also has the handy added bonus that it shares the BO Map format with that used by the BO Map component in WebSphere Process Server – so you can reuse maps if they are appropriate. BO Maps are turned into Java code for execution directly on the SMO.
• The XSLT Primitive is similar to the BO Mapper in look and feel – in version 6.1 of WebSphere Integration Developer, the tool used to define the maps for both is almost identical. The underlying implementation of the primitive is quite different, however – it instead converts the map you define into XSLT code. When an XSLT primitive is executed at runtime, your SMO is flattened into XML, it is passed through the XSLT, and then the XML is ‘deserialized’ back into a new SMO. In theory, therefore, the XSLT primitive and the BO primitive are very similar in their capabilities – although there are some subtle differences that I won’t cover here. You also have the scope to modify or use your XSLT map if you need to do something advanced – although you should strongly consider your options before doing this, as this isn’t for the faint of heart. Additionally, there are some performance differences between the XSLT and BO Mapper primitives. The exact details are subject to change over time, but as with all performance questions, the details depend on the exact scenario you have, so it is best to test them out yourself in your environment.