Using convention-based XML mapping with JMS messages

Use this approach to parse or generate XML documents by using event definitions that follow specific conventions to implicitly encode the structure of the XML document. This approach allows mapping of sequences to elements of the same type. It avoids the need for XPath, but does impose some limitations on the XML naming and structure.

The topics below explain how to use convention-based XML mapping with JMS messages.

Convention-based mapping allows XML documents to be created or parsed based on a document structure encoded in the definition of the source or target Apama event type.

The first stage when using convention-based mapping is to examine the structure of the XML document, and create an event definition to represent its root element, with fields for each attribute, text node, sub-element or sequence (of attributes, text nodes or sub-elements). The actual names of the event types are not important, but the event field names and types must follow the following conventions:

XML attributes can be represented by any EPL simple type such as string or integer. The name used should be preceded by an underscore, for example boolean _flag;.

XML text nodes are represented by either:

A field inside an Apama event representing the parent of the element containing the text, named after the element that encloses the text such as string myelement;. This avoids the need to create an event type to represent the element in cases where the element only contains a text node, and no attributes or children. The field type may be any primitive EPL type (for example, string or integer).

A field inside an Apama event representing the element that directly contains the text, named xmlTextNode. This is necessary in cases where an Apama event type is needed to represent the element so that attributes and/or child elements can also be mapped. The field type may be any primitive EPL type (for example, string or integer).

XML elements containing attributes or sub-elements of interest are represented by a field of an event type which follows these same conventions. The event type can have any name, but the field must be named after the element, for example, MyElementEventType myelement.

XML attributes, text nodes or elements which may occur more than once in the document are represented by a sequence field of the appropriate primitive or event type, named after the element, for example, sequence<string> myelement or sequence<MyElement> myelement.

A field of the optional type is processed in the same way as the contained type. If the optional value is empty, then it is not processed when creating XML. Similarly when creating an Apama event from XML, if a node corresponding to an optional field is absent, then the field will have an empty value.

Some special cases to be aware of when naming fields to match element/attribute names are:

XML nodes which are inside an XML namespace are always referenced by their local name only (the namespace or namespace prefix is ignored).

When generating an XML document, each field in the event will be processed in order and used to build up the output document.

When parsing an XML document, each field in the event will be populated with whatever XML content matches the field name and type (based on the conventions above); any XML content that is not referenced in the event definition will be silently ignored.

XML node names that are Apama EPL keywords (such as <return>) must be escaped in the event definition using a hash character, for example, string #return;.

XML node names containing any character that is not a valid EPL identifier character (anything other than than a-z, A-Z, 0-9 and _) must be represented using a $hexcode escape sequence. Of the characters that are not valid EPL identifier characters, only the hyphen and dot are supported. Note that the hexcode based escape sequences are case sensitive. For representing the hyphen or dot use the following:

You can generate event type definitions automatically from an XML schema using Software AG Designer. See Creating new event definition files for EPL applications.

In this release it is not possible to generate documents that contain elements in different XML namespaces (although when parsing this is not a problem).

The following limitations apply to the Apama event definitions that can be used to generate XML:

Dictionary event field types are not supported.

If an event field is of type sequence, the sequence can contain simple types or events. The sequence cannot contain sequences of sequences or sequences of dictionaries.