Understanding the Encoder Framework

An Encoder is a bidirectional software component that transforms an XML message into a non-XML message, and vice versa. The term encoding has a very specific meaning within this context, representing act of transforming an XML message into a non-XML message. The act of transforming a non-XML message into an XML message is termed decoding. Despite its name, the Encoder performs both functions.

XML is used as a common data format for processing within GlassFish ESB. In general, most data used in external applications is in some non-XML, serialized format; hence, the need for an Encoder.

A very highly simplified illustration of the data flow to and from GlassFish ESB is shown in the following diagram. The area to the right of the JBI boundary represents GlassFish ESB, while the area to the left of the boundary represents whatever external applications are communicating with GlassFish ESB.

Three sets of information define the runtime behavior of an Encoder:

• Encoder Type, also known as encoding style, defines the high-level encoding rules for a specific type of encoding and applies globally to all encoders of that type. The specific type of encoding relates to the data format used by the external application or communications protocol that is sending data to, or receiving data from, GlassFish ESB. Examples include SAP, Oracle DBMS, HL7, SWIFT, and X12. Encoding rules include:

  • A grammar to scan an input message in its external representation, and rules on mapping the result to the internal representation (an operation known as decoding or parsing).

  • Rules on generating the external representation of an output message from the internal representation (an operation called encoding or serialization).

• Detailed Encoding Rules are specific to a single instance of an Encoder Type. These rules include:

  • Delimiters

  • Field Lengths

  • Data offsets

• The Abstract Message Structure specifies the logical structure of the messages being processed. This metadata is represented as XML schema (XSD), and may be viewed and edited by an XSD viewer/editor.

Abstract Message Structure

The runtime message structure is composed of a hierarchical system of nodes. These nodes are characterized by terms indicating their relationships with each other:

Parent, Child, and Sibling Nodes

Any subnode of a given node is called a child node, and the given node, in turn, is the child’s parent. Sibling nodes are nodes on the same hierarchical level under the same parent node. Nodes higher than a given node in the same lineage are ancestors and those below it are descendants.

Figure 1 Encoder Node Relationships

Root Nodes

The root node is the highest node in the tree structure, and has no parent. This node is a global element and represents the entire message. It may have one or more child nodes, but can never have sibling nodes or be repeating. The name of the root node can be edited.

Non-leaf Nodes

Non-leaf nodes, which can have children, provide the framework through which this data is accessed and organized. They are of complex types.

There are two major types of non-leaf nodes (aside from a root node, which is a special case):

• Sequence group nodes, which provide organizational grouping for purposes such as repetition. In XSD, they are of complexType of a sequence of elements.

• Choice group nodes, which represent sets of alternatives— only one of which is valid at any given time for an instance of that node. For example, a choice node named order might have two children, respectively named domestic and overseas. For each order instance, only one of these children will be present. In XSD, they are of complexType of a choice group of elements.

Leaf Nodes

Leaf nodes have no children, and normally carry the actual data from the message. They are of simple types such as string.

The basic node types are fixedLength and delimited. See Encoding Properties for information about other node types.

• With fixedLength data, the length of the unit of data is always the same. The position of the data within the message string is described by byte offset and length.

• With delimited data, the length of the unit of data is variable. Information is separated by a pre-determined system of delimiters defined within the properties of the Encoder (see Specifying Delimiters).

Creating the Abstract Message Definition

This document assumes that you are working with an existing XML Schema Definition (XSD) or that you are creating an XSD. There are a number of tools available that help you create an XML schema, including NetBeans. Once you create an XSD you can apply the Custom Encoder as described in this document.

Recursive Structure

A recursive structure is allowed in an XML schema document used to define a custom structure. The recursive elements can be introduced inside a local XML schema definition by import statements, or by include statements, in the XSD.

The Custom Encoder supports both linear recursion and mutual recursion by import statements. It also supports mutual recursion from include statements.

Binary Data Types

The Custom Encoder supports elements of binary data type, as well as String data type. Far an element field of binary data type, the data type of “hexBinary” or “base64Binary” can be specified in the XML schema using the XSD editor.

Note that, base64 encoded data expands by a factor of 1.33 times the original size, and hexadecimal encoded data expands by a factor of 2 times original size, assuming an underlying UTF-8 text encoding in both cases. If the underlying text encoding is UTF-16, then these numbers double.