Using Java in WebSphere Message Broker V6.

Using Java in WebSphere Message Broker V6.0

Introduction
This article introduces the enhanced Java support provided in Version 6.0 of WebSphere® Message Broker.
The focus will be on the new JavaCompute node that simplifies the use of Java when developing message
flow applications. References are also provided to other resources that can help you learn about and use
Java within WebSphere® Message Broker.

The JavaCompute node

The new JavaCompute node significantly improves the ease of use of Java within
Message Broker allowing direct coding of Java source for use by message flow
applications. The alternative to this has been to code logic in ESQL, call Java procedures
from ESQL or to write custom processing nodes. These are both valid options which still
remain but the JavaCompute node is the recommended way of using Java in WebSphere
Message Broker V6. A big advantage of using this approach is that code which is
developed for the JavaCompute node can be deployed to a broker runtime using the same mechanism that
is used for deploying message flows, message sets and ESQL logic. This capability provides a Java
developer with a similar experience to that which they get when developing message flows using the ESQL
language. The JavaCompute node also extends the existing Java API with message processing based on
the XPath 1.0 syntax. Development of the Java code for these nodes within the Toolkit makes full use of the
Java development environment provided by Rational Application Developer on which it is built. This brings
with it content assist and refactoring tools to name but a few. A JavaCompute node wizard is also included to
initialize a Java project with a template class and references to its required dependencies. The JavaCompute
node supports the use of external classes allowing potential reuse of existing business logic written in Java
within message flows.

For someone with existing Java skills the JavaCompute node can be used to code the logic of a flow wholly
using the Java language. All of this is possible from the Toolkit in an environment and deployment model that
fully supports the development process.

Capabilities of the JavaCompute node

A JavaCompute node can be used to: route messages based on message content; enrich a message as it
passes through the node; create a new output message; along with the other capabilities that are provided
by the Java language itself. The following sections will focus on the technical side of these capabilities: the
creation; development; and deployment of JavaCompute nodes.

Creating the code for a JavaCompute node

The JavaCompute node requires a Java class to be implemented within a Java project that extends the
com.ibm.broker.javacompute.MbJavaComputeNode class. Extensions to the MbJavaComputeNode
class must implement the evaluate method. This provides the logic which will then be used to process
messages that this node receives. The Java project must also include references to the jar files that
implement the message broker’s Java Compute node APIs (javacompute.jar and jplugin2.jar). A
JavaCompute node wizard is included to create the Java project, the Java class initialized with some
template code and initiate the project with the dependencies. This wizard performs most of the setup
involved prompting the user for some names and the choice of template to be used.

Page 1 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Once a JavaCompute node has been added to the message flow the configuration wizard must be invoked
and executed. This involves the following steps:
1. Right click on the node and select Open Java.
This action initiates the Java Compute wizard.
2. Provide a Java Project name.
This project will then be created and initialized for JavaCompute node development.
3. Provide a name for the new java class.
4. Choose a template for the node class:
a. Filtering message class, for routing within a message flow based on the contents of a
message.
b. Modifying message class, for modifying a message as it passes through the node.
c. Creating message class, for the creation of a new message which is propagated by the flow.
5. Once a template has been selected the perspective within the toolkit will be switched to the Java
perspective and code based on the selected template will be brought into focus. The logic required
by this new node can now be coded.

Page 2 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

The following illustrates the code that is presented when the first filter template is chosen.

The content assist that is provided in Eclipse can then be used to developing the class.

Associating existing code

Once a JavaCompute node class has been developed the class can be reused by subsequent nodes. This is
a matter of dropping a New JavaCompute node onto a message flow and then from the node’s properties
selecting from the existing class types.

Message Processing
The JavaCompute node can provide message flows with both routing and transformation logic. A summary
of the capabilities and techniques available for routing and transformation follows.

Routing within a Flow

The ability to route a message within a message flow provides a flow with decision points where by
alternative processing and destinations can be selected for any given message. Two approaches are
available for routing messages within a flow, via the node terminals or a route to label approach.

Using Out and Alternate terminals for routing

Page 3 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

The JavaCompute node includes a two directional routing capability. The node provides this via two output
terminals which are labeled in the toolkit as the “Out” and “Alternate” terminals.

The following code extract gets these terminals so that they can be propagated to within this method. Note
the use of lower case for the initial letter when referencing the terminals within the Java code.

public void evaluate(MbMessageAssembly assembly) throws MbException

{
MbOutputTerminal out = getOutputTerminal("out");
MbOutputTerminal alt = getOutputTerminal("alternate");

The following code then propagates the message received to the “Out” terminal.

out.propagate(assembly);

Similarly, to filter some messages down the alternate terminal the propagate method would be called on the
alt object. Note to immediately free the memory used by any MbMessage objects created in a node you
should always call the clearMessage method on them before returning from evaluate.

Select the Filtering Message Class template in the JavaCompute node creation wizard to create a filter type
node.

The RegexFilterNode and RoutingFileNode samples demonstrate this capability. All of the samples
referenced in this document are shipped as part of WebSphere Message Broker V6

Route to label
If routing down just two terminals is not sufficient then as within the rest of the product a Route to Label
approach can be adopted. This flow illustrates an example where the JavaCompute node determines which
label node the RouteToLabel node propagates the message to.

Transforming the Message

Transforming a message consists of navigating the input message and creating a modified or new output
message

Page 4 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Navigating the Input Message

Navigating the message received by any node is required for both message based routing and
transformation. The message which follows is used in the subsequent code extracts to illustrate the
techniques available for navigating a message.

The XML document is illustrated to the

right in its parsed message tree form:

<document>
<chapter title='Introduction'>
Some text.
</chapter>
</document>

The Key includes details of some of the

Java methods available against the
MbElement class for navigating the
message tree.

Methods that use the XPath 1.0 syntax

are also available but not illustrated in the
diagram.

MbElement navigation
This Java code accesses the document and then the first chapter element in the logical tree:
MbElement root = assembly.getMessage().getRootElement();
MbElement document = root.getLastChild().getFirstChild();
MbElement chapter = document.getFirstChild(); // returns the first chapter

The JavaComputeTransformNoXPath sample demonstrates this capability.

XPath 1.0 navigation

An XPath syntax can also be used to retrieve the contents of a message. The following Java code accesses
the first chapter element in the logical tree this time using the XPath syntax:
MbMessage msg = assembly.getMessage();
// the following returns a list of all chapters in the document using an XPath
// expression.
List chapters= (List)msg.evaluateXPath("/document/chapter");
MbElement chapter = (MbElement)chapters.get(0); // returns the first chapter

The JavaComputeTransformXPath sample demonstrates this capability.

Creating the Output message

Once again an API and a syntax modeled on XPath can be used for the creation of output messages.

MbElement creation
In a similar fashion to how message tree elements can be accessed create methods are also available.
These can be used to create child and sibling elements given a particular MbElement. The following code
creates the title element as the first child of the chapter.
MbElement title = chapter.createElementAsFirstChild(MbXML.ATTRIBUTE,
"title",
"Introduction");

The JavaComputeTransformNoXPath sample best demonstrates this capability.

Page 5 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

XPath creation
The XPath support includes XPath extensions to support creation of elements with an XPath like syntax. So
for example “/?title[set-value(‘Introduction’)]” will create a title element and set its value.
The following code given a message containing the document and chapter elements adds the title element
and sets its value:
message.evaluateXPath("/document/chapter/?@title[set-value('Introduction')]");

The JavaComputeTransformXPath sample demonstrates this capability.

Configuring the node

A number of mechanisms exist for configuring a JavaCompute node. These include:
• User Defined Properties (New to version 6)
• Messages received by the node
• Broker Attributes
• Files

The following sections detail each of these techniques.

User Defined Properties

User defined properties are a mechanism, new to version 6, that provides flow level configuration available to
nodes within a message flow. Within the JavaCompute node these are referred to as User Defined Attributes
and the method getUserDefinedAttributes when supplied the attribute name returns the value that
has been set on the flow. Note these settings are made at a flow level not on the individual nodes so the
same properties can be accessed by all JavaCompute nodes and Compute nodes in the flow.

For the previous flow the properties can be accessed via the following Java calls:
String regexValue = (String)getUserDefinedAttribute("filterRegex");
String fieldValue = (String)getUserDefinedAttribute("filterField");

The RegexFilterNode sample demonstrates this capability and has been used for the illustrations in this
section.

Messages
Messages as they pass through a node can be used for dynamic configuration. Access to the Environment
and LocalEnvironment along with the message body provides a number of means by which this
configuration could be set. These settings could then be stored in static members of the class making the
value available to subsequent messages. Note that static variables will return to their defaults every time the
execution group is started or the message flow is deployed.

Page 6 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Broker attributes
The Java API provides a number of broker attributes for retrieving details of the Broker, Execution Group and
Message Flow within which the node is running. The following code retrieves the names of each of these
resources; other values not listed here are available.
String messageBrokerName = getBroker().getName();
String messageExecutionGroupName = getExecutionGroup().getName();
String messageFlowName = getMessageFlow().getName();
So again these broker attributes could be used to provide environment dependant configuration.

Files
Files on the run time system can be accessed by the Java Compute node using the standard java.io
classes these could also be used to configure the node. In addition files deployed in the jar along with the
java class files will be accessible to the java code.

The Routing File Node sample demonstrates this capability.

Invoking Java dependencies

Java classes developed for the JavaCompute node can make calls to existing java classes. So that the
broker runtime is able to reference the Jar file it must be place in one of the following locations: Deployed
within the broker archive file; copied to <Work Path>/shared-classes; or present in the broker’s class path.

The GoogleAPINode and NewsGroupGetNode sample demonstrate this capability.

Database support
Database access is available by two methods:
• MbSQLStatement – a class within the Java API which gives access to the ODBC datasources that
are managed by the broker. This is the only method of accessing a database with transactional
integrity. Updates/deletions/insertions are coordinated with the rest of the message flow.
• Type 4 JDBC drivers – Updates performed using this interface are not transactionally coordinated
with other resources which may also be update in a message flow.

Deploying a flow containing a JavaCompute node

Deployment is the process of transferring data to an execution group on a broker so that it can take effect in
the broker domain. For deploying message flows and associated JavaCompute classes, these resources are
packaged in a broker archive (bar) file as part of the normal deployment process. No additional steps
particular to the JavaCompute node are required. The addition of a flow that contains a JavaCompute node
into a broker archive file also triggers the packaging of the Java classes into a Java Archive (Jar) file. This
Java archive is then included in the broker archive file which can then be deployed to the broker.

When a Jar file has been deployed to the broker it

appears along with the message flows in the
domains view from within the toolkit, as shown to the
right.

The versioning and keywords support that was

added to version 6.0 is also provided for Jar files.
This uses settings made in a file (META-
INF/keywords.txt) embedded within the Jar file.

Page 7 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Debug
Debugging the node in the Message Broker Toolkit is possible by first setting a debug port for the JVM that
the message broker is running. The following command syntax requiring the broker name, execution group
and port number is used to do this:

mqsichangeproperties <Broker Name> -e <Execution Group Name> -o ComIbmJVMManager -n

jvmDebugPort -v <Port Number>

The execution group must be restarted for this setting to take effect. Then when setting up the message
broker debug session within the Toolkit the Java debug port should be entered.

To restart just the execution group the following command can be employed:

mqsireload <Broker Name> -e <Execution Group Name>

JavaCompute node samples

The product comes with a sample that consists of five message flows and corresponding JavaCompute node
classes which demonstrate the capabilities of this node. These are:
• RegexFilterNode sample - demonstrates how a JavaCompute node can be used as a filter node, and the
use of user-defined attributes.
• RoutingFileNode sample - demonstrates how a JavaCompute node can be used as a filter node, with
the filtering rules being loaded from an external source, in this case a properties file.
• JavaComputeTransform sample - demonstrates how a JavaCompute node can be used to process
simple invoices, by reading input messages and producing new output messages.
• GoogleAPINode sample - demonstrates how a JavaCompute node can call out to an external service
and propagate a new message based on the results of this call.
• NewsGroupGetNode sample - demonstrates how a JavaCompute node can call out to an external API
and augment an incoming message with the results of this call.

Sample utility methods are also included in SampleUtils.java for adding a minimal MQMD or RFH2 header.

Performance of the JavaCompute node

The Java support is based on an efficient implementation that compares favorably with ESQL. The following
table details message through put for equivalent function implemented in the JavaCompute node and in
ESQL in a Compute node using the XPath syntax methods. The example is simple and illustrates the least
favorable comparison from a Java point of view as there is little business logic coded in the message flow. In
practice there is likely to be a higher proportion of business logic and so the benefits of running Java will lead
to a more favorable comparison.

Page 8 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Task ESQL JavaCompute JavaCompute as

Msgs / Sec Msgs / Sec percentage of ESQL

Computation on an Input Message 886 793 90%

Manipulation of an Input Message 866 720 80%

Filter on the First Element 2443 2221 90%

These figures were recorded on IBM XSeries 360 4 x 2GHz Intel Xeon processors, 3.5GB RAM running
Microsoft Windows 2000 (SP4) machine using non-persistent 1k bytes XML messages.

As you can see the Java implementation compares favorably to the ESQL implementation. This is due to the
fact that as in many message brokering scenarios, including these examples, most of the processing is in the
parsing and accessing of elements within a message. This processing is performed by the same underlying
XML parser regardless of the language in which the logic is coded. Further details of the performance
improvements and the test cases used for these figures are provided in the WebSphere Message Broker
V6.0 performance reports which will be available here.

For further comparisons with the other transformation options including Mapping and XSLT, see the article
“Transformation options for WebSphere Message Broker Version 6” by Andy Piper.

z/OS users can benefit through the potential to reduce costs with the use of the JavaCompute node and the
zAAP technology. Any work done within the JavaCompute node classes will be eligible for off loading to a
zAAP processor if available. Processing costs associated with the WebSphere Message Broker message
parsers and serialization is not eligible to be run on the zAAP however.

Additional support for Java within the product

User defined extensions
User defined extensions are another way in which code can be written to run as a node within the broker.
Nodes developed via this method can specify the number and names of terminals and properties for the
node along with whether the node acts as an input node for a flow. The classes of a user defined extensions
must, however, be installed on the runtime. They do not benefit from the class deployment mechanism used
by JavaCompute nodes.

Par files, new to version 6, provide a mechanism where by a user defined extension’s classes and
dependencies can be packaged together and installed on the broker as one unit.

Page 9 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Configuration Manager API

The configuration manager API is the Java interface to the configuration manager and allows control of
broker domains programmatically. It is in fact the very interface used by the Message Broker Toolkit. So for
example creating and deploying to an Execution group, stopping and starting message flows all become
possible from within a Java application. To provide this support the API makes a WMQ client connection to
the queue manager on which the configuration manager is running. The “Configuration Manager Proxy API
Exerciser” sample included in the installation demonstrates the full capabilities of this API. A screen shot of
this application follows. In this example you can see the resources of this domain, the configuration manager
all the way through to the message flow, displayed on the left hand side. The right hand window then
provides detailed information that is reported for the selected message flow.

Page 10 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

Conclusion
This article has presented the extended Java support available in WebSphere Message Broker V6. Particular
focus has been given to the new JavaCompute node function in this release. It has covered the development
of the Java code for one of these nodes and the ease with which this code can now be deployed to the
broker. With both routing and transformation capabilities combined with its good performance mean that
message flows with logic coded entirely in Java become a viable alternative for those with Java skills.
Situations for which Java business logic already exists benefit from the ability to reuse this logic within one of
these nodes. The article included information on some of the additional and enhanced Java support that is
provided with this major release of the product.

To help you understand more about the Java support in WebSphere Message Broker V6 and related
technologies, links to additional resources are provided below.

Resources
• The tasks and concepts detailing the development of a JavaCompute node can be found in the
Information Center that accompanies the product and can be located by navigating to the following
headings in the table of contents:
Developing Applications Æ Developing Message Flow applications Æ Developing Java.

• The java API shipped with the product is located in:

Message Broker run-time installation path /docs/JavaAPI/index.html

• XPath 1.0 specification including links to further resources at http://www.w3.org/TR/xpath.

• Developer Works article What's new in WebSphere Message Broker V6 at

http://www.ibm.com/developerworks/websphere/library/techarticles/0510_dunn/0510_dunn.html.

• See the announcement letters for the

o IBM WebSphere Message Broker V6.0 at http://www.ibm.com/common/ssi/fcgi-

bin/ssialias?infotype=an&subtype=ca&appname=GPA&htmlfid=897/ENUS205-206

o IBM WebSphere Message Broker V6.0 for z/OS at http://www.ibm.com/common/ssi/fcgi-

bin/ssialias?infotype=an&subtype=ca&appname=GPA&htmlfid=897/ENUS205-208

• IBM WebSphere MQ SupportPacs provide you with a wide range of downloadable code and
documentation that complements the WebSphere MQ family of products. Performance reports are
also available. These are available at http://www.ibm.com/software/integration/support/supportpacs/.

• Join WebSphere MQ public newsgroups for discussion of WebSphere MQ at

news://news.software.ibm.com/ibm.software.websphere.mq.*.

• Get the latest WebSphere Message Broker technical resources at the WebSphere Business
Integration zone which is available at
http://www.ibm.com/developerworks/websphere/zones/businessintegration/.

• Find out more about the IBM zSeries Application Assist Processor(zAAP) at
http://www.ibm.com/servers/eserver/zseries/zaap/ .

• Find out more about IBM Tivoli Monitor for Business Integration at
http://www.ibm.com/software/tivoli/products/monitor-integration/.

Page 11 of 12 Peter Crocker

 Using Java in WebSphere Message Broker V6.0

About the author

Peter Crocker works for the Software Services team based out of the IBM Hursley Software Lab in the UK.
He specialises in WebSphere Message Broker and works with leading customers to provide consultancy on
architecture, design and implementation. Peter moved to this role from the Message Broker development
team bringing a deep technical knowledge of the internals of this product. In the time prior to the
announcement of version 6 he was part of the team that delivered the Beta program and has also developed
and delivered education to the services teams on the new function in version 6. You can contact Peter at
peter_crocker@uk.ibm.com.

Page 12 of 12 Peter Crocker