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 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

Provide a name for the new java class. This project will then be created and initialized for JavaCompute node development. for modifying a message as it passes through the node. 4. This action initiates the Java Compute wizard. Choose a template for the node class: a. Right click on the node and select Open Java. b. 5. 3. Page 2 of 12 Peter Crocker . Provide a Java Project name. Creating message class. The logic required by this new node can now be coded. Modifying message class.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. c. Filtering message class. This involves the following steps: 1. for the creation of a new message which is propagated by the flow. for routing within a message flow based on the contents of a message. 2. 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.

Message Processing The JavaCompute node can provide message flows with both routing and transformation logic. 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. A summary of the capabilities and techniques available for routing and transformation follows. Associating existing code Once a JavaCompute node class has been developed the class can be reused by subsequent nodes. The content assist that is provided in Eclipse can then be used to developing the class.0 The following illustrates the code that is presented when the first filter template is chosen. via the node terminals or a route to label approach.Using Java in WebSphere Message Broker V6. 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. Using Out and Alternate terminals for routing Page 3 of 12 Peter Crocker .

Similarly. The following code then propagates the message received to the “Out” terminal. out. Select the Filtering Message Class template in the JavaCompute node creation wizard to create a filter type node. 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.Using Java in WebSphere Message Broker V6.propagate(assembly). 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 . public void evaluate(MbMessageAssembly assembly) throws MbException { MbOutputTerminal out = getOutputTerminal("out"). 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.0 The JavaCompute node includes a two directional routing capability. The RegexFilterNode and RoutingFileNode samples demonstrate this capability. to filter some messages down the alternate terminal the propagate method would be called on the alt object. The node provides this via two output terminals which are labeled in the toolkit as the “Out” and “Alternate” terminals. This flow illustrates an example where the JavaCompute node determines which label node the RouteToLabel node propagates the message to. Note the use of lower case for the initial letter when referencing the terminals within the Java code. MbOutputTerminal alt = getOutputTerminal("alternate"). The following code extract gets these terminals so that they can be propagated to within this method.

0 Navigating the Input Message Navigating the message received by any node is required for both message based routing and transformation.0 navigation An XPath syntax can also be used to retrieve the contents of a message. MbElement chapter = document. // the following returns a list of all chapters in the document using an XPath // expression. // returns the first chapter The JavaComputeTransformXPath sample demonstrates this capability. The following Java code accesses the first chapter element in the logical tree this time using the XPath syntax: MbMessage msg = assembly.0 syntax are also available but not illustrated in the diagram. Methods that use the XPath 1. MbElement title = chapter. // returns the first chapter The JavaComputeTransformNoXPath sample demonstrates this capability.getFirstChild(). List chapters= (List)msg. Creating the Output message Once again an API and a syntax modeled on XPath can be used for the creation of output messages.evaluateXPath("/document/chapter").createElementAsFirstChild(MbXML.getLastChild(). "title". Page 5 of 12 Peter Crocker .getFirstChild(). The following code creates the title element as the first child of the chapter. MbElement chapter = (MbElement)chapters.getRootElement(). MbElement navigation This Java code accesses the document and then the first chapter element in the logical tree: MbElement root = assembly. XPath 1. "Introduction"). </chapter> </document> The Key includes details of some of the Java methods available against the MbElement class for navigating the message tree. The message which follows is used in the subsequent code extracts to illustrate the techniques available for navigating a message.get(0).ATTRIBUTE.Using Java in WebSphere Message Broker V6.getMessage(). MbElement document = root.getMessage(). The JavaComputeTransformNoXPath sample best demonstrates this capability. 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 XML document is illustrated to the right in its parsed message tree form: <document> <chapter title='Introduction'> Some text.

that provides flow level configuration available to nodes within a message flow. The RegexFilterNode sample demonstrates this capability and has been used for the illustrations in this section. Page 6 of 12 Peter Crocker . 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. These settings could then be stored in static members of the class making the value available to subsequent messages. The following code given a message containing the document and chapter elements adds the title element and sets its value: message. The JavaComputeTransformXPath sample demonstrates this capability. User Defined Properties User defined properties are a mechanism.Using Java in WebSphere Message Broker V6. Messages Messages as they pass through a node can be used for dynamic configuration. 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. Configuring the node A number of mechanisms exist for configuring a JavaCompute node. Note that static variables will return to their defaults every time the execution group is started or the message flow is deployed. For the previous flow the properties can be accessed via the following Java calls: String regexValue = (String)getUserDefinedAttribute("filterRegex"). String fieldValue = (String)getUserDefinedAttribute("filterField").evaluateXPath("/document/chapter/?@title[set-value('Introduction')]"). new to version 6. Access to the Environment and LocalEnvironment along with the message body provides a number of means by which this configuration could be set.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 retrieves the names of each of these resources. other values not listed here are available. 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.getName().Using Java in WebSphere Message Broker classes these could also be used to configure the node. Invoking Java dependencies Java classes developed for the JavaCompute node can make calls to existing java classes. Execution Group and Message Flow within which the node is running. No additional steps particular to the JavaCompute node are required. or present in the broker’s class path. these resources are packaged in a broker archive (bar) file as part of the normal deployment process. Files Files on the run time system can be accessed by the Java Compute node using the standard java. The versioning and keywords support that was added to version 6.0 is also provided for Jar files.getName(). This uses settings made in a file (METAINF/keywords. copied to <Work Path>/shared-classes. as shown to the right. = getExecutionGroup(). = getMessageFlow(). 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. 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. • 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. Updates/deletions/insertions are coordinated with the rest of the message flow. So again these broker attributes could be used to provide environment dependant configuration. 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.0 Broker attributes The Java API provides a number of broker attributes for retrieving details of the Broker. String messageBrokerName String messageExecutionGroupName String messageFlowName = getBroker(). Page 7 of 12 Peter Crocker . In addition files deployed in the jar along with the java class files will be accessible to the java code. For deploying message flows and associated JavaCompute classes. The GoogleAPINode and NewsGroupGetNode sample demonstrate this capability. The Routing File Node sample demonstrates this capability. This is the only method of accessing a database with transactional integrity.txt) embedded within the Jar file. 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.getName(). This Java archive is then included in the broker archive file which can then be deployed to the broker.

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.demonstrates how a JavaCompute node can be used to process simple invoices. JavaComputeTransform sample . with the filtering rules being loaded from an external source. in this case a properties file. Then when setting up the message broker debug session within the Toolkit the Java debug port should be entered.Using Java in WebSphere Message Broker V6. and the • • • • use of user-defined attributes. GoogleAPINode sample .demonstrates how a JavaCompute node can call out to an external API and augment an incoming message with the results of this call. NewsGroupGetNode sample .java for adding a minimal MQMD or RFH2 header. RoutingFileNode sample . 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.demonstrates how a JavaCompute node can call out to an external service and propagate a new message based on the results of this call. The following command syntax requiring the broker name.demonstrates how a JavaCompute node can be used as a filter node. 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. Sample utility methods are also included in SampleUtils.demonstrates how a JavaCompute node can be used as a filter node. Page 8 of 12 Peter Crocker . 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 .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. by reading input messages and producing new output messages. Performance of the JavaCompute node The Java support is based on an efficient implementation that compares favorably with ESQL. 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.

however. new to version 6. be installed on the runtime. The classes of a user defined extensions must. Page 9 of 12 Peter Crocker . including these examples.0 performance reports which will be available here. For further comparisons with the other transformation options including Mapping and XSLT. Any work done within the JavaCompute node classes will be eligible for off loading to a zAAP processor if available. 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. Further details of the performance improvements and the test cases used for these figures are provided in the WebSphere Message Broker V6. This processing is performed by the same underlying XML parser regardless of the language in which the logic is coded. see the article “Transformation options for WebSphere Message Broker Version 6” by Andy Piper. Processing costs associated with the WebSphere Message Broker message parsers and serialization is not eligible to be run on the zAAP however.Using Java in WebSphere Message Broker V6. 3. This is due to the fact that as in many message brokering scenarios. Par files. 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. 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. They do not benefit from the class deployment mechanism used by JavaCompute nodes. most of the processing is in the parsing and accessing of elements within a message. z/OS users can benefit through the potential to reduce costs with the use of the JavaCompute node and the zAAP technology.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.0 Task Computation on an Input Message Manipulation of an Input Message ESQL Msgs / Sec 886 866 JavaCompute Msgs / Sec 793 720 JavaCompute as percentage of ESQL 90% 80% Filter on the First Element 2443 2221 90% These figures were recorded on IBM XSeries 360 4 x 2GHz Intel Xeon processors.

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

These are available at http://www. The java API shipped with the product is located in: Message Broker run-time installation path /docs/JavaAPI/index. The article included information on some of the additional and enhanced Java support that is provided with this major release of the . 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 • • • • o • IBM WebSphere MQ SupportPacs provide you with a wide range of downloadable code and documentation that complements the WebSphere MQ family of products.0 Conclusion This article has presented the extended Java support available in WebSphere Message Broker V6.w3. To help you understand more about the Java support in WebSphere Message Broker V6 and related technologies. Get the latest WebSphere Message Broker technical resources at the WebSphere Business Integration zone which is available at*. 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 Situations for which Java business logic already exists benefit from the ability to reuse this logic within one of these See the announcement letters for the o IBM WebSphere Message Broker Join WebSphere MQ public newsgroups for discussion of WebSphere MQ at news:// Find out more about IBM Tivoli Monitor for Business Integration at http://www. links to additional resources are provided XPath IBM WebSphere Message Broker V6.0 specification including links to further resources at • • • • Page 11 of 12 Peter Crocker .ibm.Using Java in WebSphere Message Broker V6.websphere. Developer Works article What's new in WebSphere Message Broker V6 at http://www.0 at http://www. Particular focus has been given to the new JavaCompute node function in this release. 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.0 for z/OS at Find out more about the IBM zSeries Application Assist Processor(zAAP) at http://www. Performance reports are also He specialises in WebSphere Message Broker and works with leading customers to provide consultancy on architecture. You can contact Peter at peter_crocker@uk. 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.Using Java in WebSphere Message Broker V6. Peter moved to this role from the Message Broker development team bringing a deep technical knowledge of the internals of this product. design and implementation. Page 12 of 12 Peter Crocker .0 About the author Peter Crocker works for the Software Services team based out of the IBM Hursley Software Lab in the UK.