WebSphere Message Brokers
File: as01395_
Writer: Lorraine Waitt

Concept topic

This build: July 31, 2007 21:36:53

Planning user-defined message processing nodes

Plan how to write your message processing node or output node, and how to navigate the message within the node.

Design considerations

Before developing and implementing your message processing node, consider the following points:
  • Which parser will parse messages.
  • Whether to override the default message parser attribute values for this message processing node.
  • What is the appropriate threading model for the message processing node.
  • How to implement the end of message processing and transaction support that the node must support.
  • What configuration properties required by the message processing node should be externalized for alteration by the message flow designer.
  • What optional node APIs will the user-defined node provide.
  • General development issues:

Syntax element navigation

The broker provides functions that your node can call to traverse the tree representation of the message, as well as functions and methods to allow navigation from the current element to other elements:
  • Parent
  • First child
  • Last child
  • Previous (or left) sibling
  • Next (or right) sibling
These relationships are shown in the figure below.
The figure shows a syntax element. It is connected to other elements. The other elements are: previous sibling and next sibling to the left and right of the element, first child and last child below the element, and parent, which is above the element.

Other functions and methods support the manipulation of the elements themselves, with functions and methods to create elements, to set or query their values, to insert new elements into the tree, and to remove elements from the tree. See C node utility functions and C parser utility functions, or the Javadoc information for more details.

The next figure describes a simple syntax element tree that shows a full range of interconnections between the elements.
The figure shows a syntax element tree. Element A is at the top of the diagram, above element B, which is in turn above elements C, D, and E, which are at the same level.

The element A is the root element of the tree. It has no parent because it is the root. It has a first child of element B. Because A has no other children, element B is also the last child of A.

Element B has three children: elements C, D, and E. Element C is the first child of B; element E is the last child of B.

Element C has two siblings: elements D and E. The next sibling of element C is element D. The next sibling of element D is element E. The previous sibling of element E is element D. The previous sibling of element D is element C.

The figure below shows the first generation of syntax elements of a typical message received by a broker. (Not all messages have an MQRFH2 header.)
At the top of the figure is a box labelled Root. A line connects the box to one marked Properties below and to the left, and another line to a box marked XML below and to the right. Between these two, are two further boxes, marked MQMD and MQRFH2.

These elements at the first generation are often referred to as folders, in which syntax elements that represent message headers and message content data are stored. In this example, the first child of root is the Properties folder. The next sibling of Properties is the folder for the MQMD of the incoming WebSphere MQ messages. The next sibling is the folder for the MQRFH2 header. The last folder represents the message content, which (in this example) is an XML message.

The figure above includes an MQMD and an MQRFH2 header. All messages that are received by a processing node that handles WebSphere MQ include an MQMD header; a number of other headers can also be included.

Navigating an XML message

Consider the following XML message:
  <Business>
    <Product type='messaging'></Product>
    <Company>
      <Title>IBM</Title>
      <Location>Hursley</Location>
      <Department>WebSphere MQ</Department>
    </Company>
  </Business>
In this example, the elements are of the following types:
Name element
Business, Product, Company, Title, Location, Department
Value element
IBM, Hursley, WebSphere MQ
Name-value element
type='messaging'

Use supplied node utility functions and methods (or the similar parser utility functions) to navigate through a message. Using the XML message shown above, you must call cniRootElement first, with the message received by the node as input to this function. In Java, you must call getRootElement on the incoming MbMessage object. This call returns an MbElement that represents the root of the element. Do not modify this root element in the user-defined node.

The figure above, of the first generation of the syntax elements of a typical message that is received by the broker, shows that the last child of the root element is the folder containing the XML parse tree. Navigate to this folder by calling cniLastChild (with the output of the previous call as input to this function) in a C node, or by calling the method getLastChild on the root element, in a Java node.

Only one element (<Business>) is at the top level of the message, therefore call cniFirstChild (in C) or getFirstChild (in Java) to move to this point in the tree. Use cniElementType or getType to get its type (which is name), followed by cniElementName or getName to return the name itself (Business).

The element <Business> has two children, <Product> and <Company>. Use cniFirstChild or getFirstChild followed by cniNextSibling or getNextSibling to navigate to each child in turn.

The element <Product> has an attribute (type='messaging'), which is a child element. Use cniFirstChild or getFirstChild to navigate to this element, and cniElementType or getType to return its type (which is name-value). Use cniElementName or getName to get the name. To get the value, call cniElementValueType to return the type, followed by the appropriate function in the cniElementValue group: in this example it is cniElementCharacterValue. In Java use the method getValue, which returns a Java object representing the element value.

The element <Company> has three children, each one having a child that is a value element (IBM, Hursley, and WebSphere MQ). Use the functions already described to navigate to them and access their values.

Other functions are available to copy the element tree (or part of it). The copy can then be modified by adding or removing elements, and changing their names and values, to create an output message. See C node utility functions and C parser utility functions, or the Java user-defined node API, for more information.

Related reference
C node utility functions
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:36:53

as01395_ This topic's URL is: