Skip to main content

skip to main content

developerWorks  >  WebSphere  >

Using Java in WebSphere Message Broker V6

developerWorks
Document options

Document options requiring JavaScript are not displayed


Rate this page

Help us improve this content


Level: Intermediate

Peter Crocker (peter_crocker@uk.ibm.com), Senior IT Specialist, IBM

31 May 2006

This article introduces the enhanced Java support in WebSphere Message Broker V6, focusing on the new JavaCompute node, which simplifies the use of Java when developing message flow applications. The article also lists resources that can help you learn about and use Java in WebSphere Message Broker.

The JavaCompute node


Figure 1. JavaCompute node
Figure 1. JavaCompute node

The new JavaCompute node significantly improves the ease of use of Java™ in IBM® WebSphere® Message Broker V6, allowing direct coding of Java source for use by message flow applications. The alternative has been to code logic in ESQL and call Java procedures from the ESQL, or write custom processing nodes. These both remain valid options, but the JavaCompute node is the recommended way to use Java in WebSphere Message Broker V6. Its big advantage is that code developed for the JavaCompute node can be deployed to a broker run time using the same mechanism that is used to deploy message flows, message sets, and ESQL logic. This capability gives you you a similar experience to developing message flows using ESQL.

The JavaCompute node also extends the existing Java API with message processing based on the XPath 1.0 syntax. Developing Java code for these nodes within the Toolkit makes full use of the Java development environment, which it is built on Rational Application Developer and provides content assist, refactoring tools, and other useful features. Also included is a JavaCompute node wizard, which initializes 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.

Those with Java skills can use the JavaCompute node to code the logic of a flow wholly in Java, using the Toolkit in an environment and deployment model that fully supports the development process.

Capabilities of the JavaCompute Node

You can use a JavaCompute node to:

  • Route messages based on message content
  • Enrich a message as it passes through the node
  • Create a new output message
  • Use other capabilities provided by the Java language

The following sections focus on the technical side of these capabilities: the creation, development, and deployment of JavaCompute nodes.

Creating the code for a JavaCompute node

A 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, which provides the logic that will be used to process messages that this node receives. The Java project must also include references to the jar files that implement Message Broker’s Java Compute node APIs (javacompute.jar and jplugin2.jar). In addition to initializing a Java project with a template class and references to its required dependencies, the JavaCompute node wizard performs most of the setup, prompting you for names and choice of template. Once you add a JavaCompute node to the message flow, you must invoke and execute the configuration, using the following steps:

  1. Right-click on the node and select Open Java. The JavaCompute note wizard opens.
  2. Provide a Java Project name. The project is created and initialized for JavaCompute node development.
  3. Provide a name for the new Java class.
  4. Choose a template for the node class:
    • Filtering message class -- for routing within a message flow based on the contents of a message.
    • Modifying message class -- for modifying a message as it passes through the node.
    • 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.

Figure 2. JavaCompute node configuration wizard
Figure 2. JavaCompute node configuration wizard

Here is the code presented when the first filter template is chosen:


Figure 3. JavaCompute node template
Figure 3. JavaCompute node template

You can then use the content assist in Eclipse to develop the class.

Associating existing code

Once a JavaCompute node class has been developed, it can be reused by subsequent nodes. To do this, simply drop a new JavaCompute node onto a message flow and then from the node’s properties, select 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 is below.

Routing within a Flow

The ability to route a message within a message flow gives a flow decision points whereby alternative processing and destinations can be selected for any given message. Two approaches are available for routing messages within a flow -- via node terminals or a route-to-label approach.

Using Out and Alternate terminals for routing


Figure 4. Using Out and Alternate terminals for routing
Figure 4. Using Out and Alternate terminals for routing

The JavaCompute node includes two-directional routing capability via two output terminals, 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. Use 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 is called on the alt object. To immediately free the memory used by any MbMessage objects created in a node, always call the clearMessage method on them before returning from evaluate.

To create a filter type node, select the Filtering Message Class template in the JavaCompute node creation wizard.

The RegexFilterNode and RoutingFileNode samples demonstrate this capability. All samples referenced in this article are included with WebSphere Message Broker V6.

RouteToLabel

If routing down just two terminals is not sufficient, then as in the rest of the product, you can use a RouteToLabel approach. This flow illustrates an example where the JavaCompute node determines which label node the RouteToLabel node propagates the message to:


Figure 5. Using Route To Label for routing
Figure 5. Using Route To Label for routing

Transforming the message

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

Navigating the input message

Navigating the message received by any node is required for both message-based routing and transformation. The following message is used in the subsequent code extracts to illustrate the techniques available for navigating a message. The XML document is illustrated below in its parsed message tree form:

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


Figure 6. Message tree resulting from parse of sample document
Figure 6. Message tree resulting from parse of sample 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 are 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

You can also use an XPath syntax to retrieve the contents of a message. The following Java code accesses the first chapter element in the logical tree 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 shipped with WebSphere Message Broker V6 demonstrates this capability.

Creating the Output message

Once again, you can use an API and syntax modeled on XPath to create output messages.

MbElement creation

In a similar fashion to how message tree elements can be accessed, you can also access create methods and use them 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 shipped with WebSphere Message Broker V6 best demonstrates this capability.

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 shipped with WebSphere Message Broker V6 demonstrates this capability.

Configuring the Node

A number of mechanisms exist for configuring a JavaCompute node:

  • User-defined properties (New in V6)
  • Messages received by the node
  • Broker attributes
  • Files

The following sections detail each of these techniques.

User-defined properties

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


Figure 7. User-defined attributes
Figure 7. User-defined attributes

For the previous flow, you can access the properties via the following Java calls:

	
String regexValue = (String)getUserDefinedAttribute("filterRegex");
String fieldValue = (String)getUserDefinedAttribute("filterField");

The RegexFilterNode sample shipped with WebSphere Message Broker V6 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 ways to set this configuration. You can then store these settings in static members of the class, making the value available to subsequent messages. Static variables will return to their defaults every time the execution group is started or the message flow is deployed.

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 also available.

	
	String messageBrokerName 		= getBroker().getName();
	String messageExecutionGroupName 	= getExecutionGroup().getName();
	String messageFlowName 		= getMessageFlow().getName();

So again you can use these broker attributes 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 that can 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. For the Message Broker run time to reference the jar file, it must be placed in one of the following locations: deployed within the broker archive file; copied to <Work Path>/shared-classes;, or present in the Message Broker classpath. The GoogleAPINode and NewsGroupGetNode sample demonstrate this capability.

Database support

Two methods provide database access:

  • MbSQLStatement – A class within the Java API that provides access to ODBC datasources managed by Message Broker. This is the data access method that provides transactional integrity -- updates, deletions, and 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 do updates 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 specific to the JavaCompute node are required. Adding a flow that contains a JavaCompute node into a bar file also triggers the packaging of the Java classes into a Java Archive (jar) file, which is then included in the bar 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 keyword support in V6 is also provided for jar files, and uses settings made in a file (META-INF/keywords.txt) embedded in the jar file.


Figure 8. Deployed JavaCompute node
Figure 8. Deployed JavaCompute node

Debugging

To debug a node in the Message Broker Toolkit, first set a debug port for the JVM that Message Broker is running. Use the following command syntax, which requires the broker name, execution group, and port number:

	
mqsichangeproperties <Broker Name> -e <Execution Group Name> 
	-o ComIbmJVMManager -n jvmDebugPort -v <Port Number>

Restart the execution group for this setting to take effect. When setting up the Message Broker debug session within the Toolkit, enter the Java debug port. To restart just the execution group, use the following command:

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

JavaCompute node samples

WebSphere Message Broker V6 comes with a sample that consists of five message flows and corresponding JavaCompute node classes that demonstrate the capabilities of this node:

  • 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 an external service and propagate a new message based on the results of this call.
  • NewsGroupGetNode sample -- Demonstrates how a JavaCompute node can call 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.

JavaCompute node performance

The Java support is based on an efficient implementation that compares favorably with ESQL. The following table details message throughput 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 therefore the benefits of running Java will lead to a more favorable comparison.


Table 1. Message throughput comparison for ESQL and Java implementations when performing identical message processing
TaskESQL Msgs/SecJavaCompute Msgs/SecJavaCompute as a percentage of ESQL
Computation on an input message88679390%
Manipulation of an input message86672080%
Filter on the first element2443222190%

These figures were recorded on an IBM xSeries 360 server with 4 x 2GHz Intel Xeon processors, 3.5 GB of RAM, and Microsoft Windows 2000 (SP4), using non-persistent 1K bytes XML messages.

As you can see, the Java implementation compares favorably to the ESQL implementation because, as in many message broker scenarios, 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. For further details on the performance improvement and test cases used for these figures, see the performance reports for WebSphere Message Broker V6.

z/OS users can reduce costs by using the JavaCompute node with the IBM System z Application Assist Processor (zAAP). Any work done within JavaCompute node classes can be offloaded to a zAAP processor. However, processing associated with WebSphere Message Broker message parsers and serialization is not eligible to be run on the zAAP.

Additional support for Java in WebSphere Message Broker

User-defined extensions

User-defined extensions are another way in which you can write code to run as a node within Message Broker. Nodes developed using 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 extension must, however, be installed on the run time. They do not benefit from the class deployment mechanism used by JavaCompute nodes.

Par files, new to V6, enable a user-defined extension’s classes and dependencies to be packaged together and installed on Message Broker as one unit.

Configuration manager API

The configuration manager API is the Java interface to the configuration manager, and it lets you control broker domains programmatically. It is the interface used by the Message Broker Toolkit, so creating and deploying to an execution group, or stopping and starting message flows, all become possible from within a Java application. To provide this support, the API makes a WebSphere MQ 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. The screenshot of this application below shows the resources of this domain, from the configuration manager all the way through to the message flow, displayed on the left. The right-hand window provides detailed information that is reported for the selected message flow.


Figure 9. Configuration manager proxy API exerciser
Figure 9. Configuration manager proxy API exerciser

Conclusion

This article described the extended Java support in WebSphere Message Broker V6, focusing on the new JavaCompute node function. The article showed how to create Java code for one of these nodes and how easily this code can be deployed to Message Broker. With routing and transformation capabilities combined with good performance, message flows with logic coded entirely in Java become a viable alternative for those with Java skills. If Java business logic already exists, you can reuse it within one of these nodes. The article also described some of the additional enhanced Java support in this major new release of WebSphere Message Broker. For more information on Java support in WebSphere Message Broker V6 and on related technologies, see the "Resources" section below.



Resources



About the author

Photo of Peter Crocker

Peter Crocker works on the Software Services team at the IBM Hursley Software Lab in the UK. He specialises in WebSphere Message Broker and works as a consultant with leading customers on architecture, design, and implementation. Peter moved to this role from the Message Broker Development team, bringing a deep technical knowledge of Message Broker internals. Prior to the announcement of V6, he helped deliver the Beta program and also helped develop and deliver education to the Services teams on new V6 function. You can contact Peter at peter_crocker@uk.ibm.com.




Rate this page


Please take a moment to complete this form to help us better serve you.



 


 


Not
useful		Extremely
useful
 


Share this....

digg Digg this story del.icio.us del.icio.us Slashdot Slashdot it!



Back to top