Convention-based XML mapping

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, integer, etc. 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, integer, etc.).

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, integer, etc.).

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.

XML nodes which are inside an XML namespace are always referenced by their local name only (the namespace or namespace prefix is 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;. 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 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:

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).

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