The protocol layer is responsible for all tasks related to dataformats. It has two kind of modules:

• Messages to hold the data in various formats. A PDF file explains, which dataformats can be used with which senders / receivers.
• Transformers to transform data from one format into another format. A PDF file explains, which transformers are used by default.

A substantial part of communication - both between neighbor systems and the xBus and within the xBus itself - takes place on basis of XML.

XMLMessage

XMLMessage is the base class for all kind of messages in the XML format.

It holds the XML data internally as an org.w3c.dom.Document. Therefore it is able to work with nearly all sender/receiver modules, either with a human readable XML string or with an object of kind org.w3c.dom.Document. When working with the string representation, parsing and serializing is done internally.

XBUSXMLMessage

XBUSXMLMessage represents messages in the xBus specific XML-format. It consists of two parts: some header fields like id or function and the data itself. It is very useful when a message leaves the context of the xBus and reenters again, e.g. it is buffered in a message queue or send to another instance of the xBus via HTTP. An example describes its format.

SOAPMessage

SOAPMessage represents messages in the format for SOAP requests. It has some more functionality than a normal XMLMessage:

• When receiving a SOAP message, it extracts the function of the message by getting the name of the first node of the SOAP body.
• When an error occurs while processing the message, it sets a fault element into the SOAP body with an explanation of the error.

The HTTPSender has two special features when dealing with SOAP messages, to fulfil the SOAP specification:

• The HTTP Header contains an additional entry SOAPAction, referencing the function of the message.
• When the other side sends a returncode other than OK, the HTTPSender reads the error stream as the response.

When setting the request or the response of a XML message as a string, e.g. after receiving data from an external system, the data can be validated either against a DTD or a XML Schema. See the examples(example 1 for DTD validating, example 3 for XML Schema validating) and the configuration for more details.

Record type messages are often used when communicating with legacy systems. Their main attributes are:

• Every line of the message contains exactly one record.
• The fields of a record have a fixed length.
• The message may contain different types of records, e.g. order header and order lines. In this case there is one field indicating the type of the record.
• The value of a field does not contain any line breaks.

RecordTypeMessage

The RecordTypeMessage module is used to transport and convert messages structured by record types.

The interface file structure is described by a xml file - in particular the contained record types with the format of their fields, their order within the file and how to identify them during parsing. Such definition files are of document type InterfaceSpec declared in "InterfaceSpec.dtd".

When receiving a record type message, the xBus parses this message using the interface definition and stores the data internally in a XML representation. Transformers can convert this format into another format by using XSLT. When sending a record type message to another system, the internal XML representation will be serialized into the record type format using the same interface definition. "Transformation of Record Type Interface Files" explains this behavior in more detail.

More information about the several elements necessary to configure the definition and transformation of record types messages you will find in the chapter "Configuration -> XML/XSL for RecordTypeMessage".

CSV (comma separated values) is a commonly used format for structured data. One of its advantages is the import into / export from spreadsheet programs. Main attributes of CSV are:

• Every line contains one record.
• Fields are separated by commas, semicolons or another delimiter.
• Fields can be surrounded by double-quotes, single-quotes or another character.
• Fields must be surrounded by a quote character if its value contains
  • a delimiter or
  • a quote character (which must then be doubled) or
  • a line break
  or when the configuration parameter AlwaysQuote is set to true.

CSVMessage

The string containing the CSV data is internally stored as a XML document. When receiving CSV data, the string is parsed into a XML document, when sending CSV data the internal XML document is serialized back into a string. There are to ways of controlling this parsing and serialization:

• Some configuration entries control the character for delimiters, the existence of headers and the quotation of fields. There are global entries, which can be overwritten per system.
• Additionally it is possible to either use just the information that can be gathered out of the CSV data for parsing and serialization or to use an interface definition to have more control over this process.

More details about parsing, serialization and the internal XML format can be found here.

When transferring record type structured data with fixed field lengths, using strings like in the RecordTypeMessage may cause problems:

• If the string length for some fields may be different in source and destination system due to different string encoding, when dealing with non-western characters like for example a Korean charset.
• If field values may contain line breaks which are interpreted as record ends.

In these cases the use of the ByteArrayListMessage is more convenient. Here the interface content is read into a list of byte arrays - one byte array for each record.

The configuration and interface definition of ByteArrayListMessages is very similar to RecordTypeMessages (described here), with a few differences:

• The interface definition file is simpler, according to XBUS_HOME/etc/InterfaceDescriptions/InterfaceSpecSimple.dtd.
• The internal XML format is slightly different.

ByteArrayListMessage

This message module is used for transferring byte array lists without transformation of the interface content. The processing of records in byte array lists involves parsing to single filed values because this is the only way to correctly treat different string lengths because of the character encoding.

In some cases the xBus shall just send or receive data without interpreting it. To do this very efficently, the simple message modules can be used.

SimpleTextMessage

SimpleTextMessage is the most simple implementation to transport strings.

SimpleObjectMessage

This module serves for the most simple transfer of data which may be of arbitrary type.

EmptyMessage

This module serves as a dummy. The EmptyMessage may not transport any contents. But is compatible with all message types.

AS400ProgramMessage

AS400ProgramMessage represents a message in the specific XML-format for the calling an iSeries server program. Cf. the corresponding "technical" information.

CloneTransformer

The CloneTransformer creates clones of arbitrary messages. In fact the outgoing message is not a copy but a reference of the incoming message.

JavaTransformer

The JavaTransformer calls a method of a Java class, to transform the source into the destination format. Which class and which method to be used is read out of the configuration.

The signature of the called method must be:

    public Object methodName(Object inObject) throws XException

RecordTypeTransformer

The RecordTypeTransformer class transforms one RecordTypeMessage into another one - according to a xsl transformation description. The class is pretty like the XSLTTransformer. The only differences are the determination of the xsl file and a whitespace cleaning after the transformation.

XMLWrapperTransformer

The XMLWrapperTransformer wraps the given String into a XBUSXMLMessage. The XBUS_Data section of the outcoming XBUSXML document contains the given String as a CDATA element. This makes sure the XML parser will not try to evaluate the String.

XMLUnwrapperTransformer

The XMLUnwrapperTransformer does the inverse transformation of the XMLWrapperTransformer. It awaits a XBUSXML document containing a CDATA section. The content of this CDATA section is given back as a String.

XMLParserTransformer

The XMLParserTransformer parses the given String into an org.w3c.Document.

XMLSerializerTransformer

The XMLSerializerTransformer serializes the given org.w3c.Document into a String.

XSLTTransformer

Responsible for transformation between XMLMessages with XSLT stylesheets.The transformation is done in two steps:

1. An XSLT stylesheet which name is read from the configuration does the first part of the transformation.
2. The so-called XBUS_Stylets are processed to fill in extra data into the XML data. This allows transformation steps which cannot be expressed in XSL. Detail information on XBUS_Stylets is collected on a separate page.