Planning user-defined message processing nodes

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

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 following diagram shows the first generation of syntax elements of a typical WebSphere® MQ message received by an integration node. (Not all messages have an MQRFH2 header.)

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 header. 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 previous figure 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.

  <Business>
    <Product type='messaging'></Product>
    <Company>
      <Title>IBM</Title>
      <Location>Hursley</Location>
      <Department>WebSphere MQ</Department>
    </Company>
  </Business>

Use supplied node utility functions and methods (or the similar parser utility functions) to navigate through a message. Using the XML message shown, 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 of the first generation of the syntax elements of a typical message that is received by the integration node, 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.