Planning user-defined message processing nodes

This topic provides guidance for writing your message processing node to ensure that it functions correctly. It explains how you can use your message processing node to navigate a message.

Design considerations

Before developing and implementing your message processing node, you should decide on the following:
  • The message parser that will parse the message
  • Whether to override the default message parser attribute values for this message processing node.
  • The appropriate threading model for the message processing node
  • End of message processing and transaction support that the node will support
  • The configuration attributes required by the message processing node that should be externalised for alteration by the message flow designer.
  • Optional node APIs the user-defined node will provide
  • General development issues:

Syntax element navigation

The broker infrastructure provides functions that enable a message processing node implementation to traverse the tree representation of the message, with functions and methods to allow navigation from the current element to its:
  • Parent
  • First child
  • Last child
  • Previous (or left) sibling
  • Next (or right) sibling
As shown in the figure below. 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 for more information.

A syntax element with connections to other elements


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.
The next figure describes a simple syntax element tree that shows a full range of interconnections between the elements.

Syntax element tree


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 WebSphere Message Broker. (Note that not all messages will have an MQRFH2 header.)

First generation of syntax elements in a typical message


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. Finally, there is the folder that represents the message content, which (in this example) is an XML message.

The figure above includes an MQMD and an MQRFH2 header. All messages received by an MQmessage processing node include an MQMD header, there are a number of other headers than can also be included.

Navigating an XML message

Suppose we have 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'

You can use node utility functions and methods (or the similar parser utility functions) to navigate through a message. Taking the XML message shown above, you need to call cniRootElement first, with the message received by the node as input to this function. In Java you need to call getRootElement on the incoming MbMessage. This returns an MbElement that represents the root of the element. The root element should not be modified by a user-defined node.

The figure above shows that the last child of the root element is the folder containing the XML parse tree. You can 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.

There is one element only (<Business>) at the top level of the message, so calling cniFirstChild (in C) or getFirstChild (in Java) moves to this point in the tree. You can use cniElementType or getElementType to get its type (which is name), followed by cniElementName or getName to return the name itself (Business).

<Business> has two children, <Product> and <Company>, so you can use cniFirstChild or getFirstChild followed by cniNextSibling or getNextSiblingto navigate to them in turn.

<Product> has an attribute (type='messaging'), which is a child element. Use cniFirstChild or getFirstChildagain to navigate to this element, and cniElementType or getType to return its type (which is name-value). Use cniElementName or getName as before 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 will be cniElementCharacterValue. In Java use the method getValue, which will return a Java object representing the element value.

<Company> has three children, each one having a child that is a value element (IBM, Hursley, and WebSphere MQ). You can 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.