Logical tree structure

When a message arrives at a broker, it is received by an input node that you have configured in a message flow. Before the message can be processed by the message flow, the message must be interpreted by one or more parsers that create a logical tree representation from the bit stream of the message data.

The tree format contains identical content to the bit stream from which it is created, but it is easier to manipulate in the message flow. Many of the built-in message flow nodes provide an interface for you to query and update message content in the tree, and perform other actions against messages and databases to help you to provide the required function in each node.

Several interfaces are provided:

• ESQL, a programming language that you can code in the Compute, Database, and Filter nodes.
• Java™, a programming language that you can code in the JavaCompute node.
• Mappings, a graphical method of achieving transformation from input to output structures, available in the Mapping node.
• XSL, a language for transforming XML that you can use in the XSLTransform node.
• PHP, a scripting language that you can code in the PHPCompute node.

The tree structure that is created by the parsers is largely independent of any message format (for example, XML). The exception to this is the subtree that is created as part of the message tree to represent the message body. This subtree is message dependent, and its content is not further described here.

The input node creates this message assembly, which consists of four trees:

• Message tree structure
• Environment tree structure
• Local environment tree structure
• Exception list tree structure

The first of these trees is populated with the contents of the input message bit stream, as described in How the message tree is populated; the remaining three trees are initially empty.

Each of the four trees created has a root element (with a name that is specific to each tree). Each tree is made up of a number of discrete pieces of information called elements. The root element has no parent and no siblings (siblings are elements that share a single parent). The root is parent to a number of child elements. Each child must have a parent, can have zero or more siblings, and can have zero or more children.

The four trees are created for both built-in and user-defined input nodes and parsers.

The input node passes the message assembly that it has created to subsequent message processing nodes in the message flow:

• All message processing nodes can read the four trees.
• You can code ESQL in the Database and Filter nodes, or use mappings in the nodes that support that interface to modify the Environment and LocalEnvironment trees only.
• The Compute node differs from other nodes in that it has both an input message assembly and at least one output message assembly. Configure the Compute node to determine which trees are included in the output message assembly; the Environment tree is an exception in that it is always retained from input message assembly to output message assembly.

  To determine which of the other trees are included, you must specify a value for the Compute mode property of the node (displayed on the Advanced tab). The default action is for only the message to be created. You can specify any combination of message, LocalEnvironment, and ExceptionList trees to be created in the output message assembly.

  If you want the output message assembly to contain a complete copy of the input message tree, you can code a single ESQL SET statement to make the copy. If you want the output message to contain a subset of the input message tree, code ESQL to copy those parts that you want. In both cases, your choice of Compute mode must include Message.

  If you want the output message assembly to contain all or part of the input LocalEnvironment or ExceptionList tree contents, code the appropriate ESQL to copy information you want to retain in that tree. Your choice of Compute mode must include LocalEnvironment, or Exception, or both.

  You can also code ESQL to populate the output message, Environment, LocalEnvironment, or ExceptionList tree with information that is not copied from the input tree. For example, you can retrieve data from a database, or calculate content from the input message data.

• You can produce similar results in the JavaCompute node. See Writing Java for more information.
• You can also achieve results like these in the PHPCompute node. See Using PHP for more information.