Messaging XML Support overview

Messaging XML support comprises the following elements:

• A generic set of classes that can represent the contents of an XML file in an object hierarchy for efficient processing. These classes are referred to as the "mini-DOM", because they use some but not all concepts from the DOM [DOM]. The classes can perform syntax checking and validation with regard to a specific DTD set at run time.

• An interface class that defines the signature for the necessary DTD validation functions. Any DTD-specific validation class is derived from this, and provides an implementation of these functions.

• A parser that can read an XML file and can generate mini-DOM objects.

• A composer that can take a mini-DOM object tree and output an XML file.

The XML Mini-DOM classes are based on a subset of the DOM classes [DOM]. The Mini-DOM is a subset, because it is not intended to support some of the more ambitious or obscure uses of XML. It also discards some of the theoretical layers (for example, attributes are not created as separate nodes, but are member data of element objects). The Mini-DOM is not intended as a porting API whereby applications written on other platforms using the DOM can be trivially ported to Symbian OS.

When an XML file is parsed, and a Mini-DOM tree is created, the Mini-DOM classes provide an API to navigate through the document objects and to query the element attributes. When an XML file is to be composed, the Mini-DOM provides an API to interrogate the elements allowing the XML Composer to produce a textual representation.

The document (CMDXMLDocument) is with a reference to an MXMLDtd object and provides an API to allow validation based on DTD specific rules.

The generic element class can represent each element type, with elements being differentiated by their names.

The Mini-DOM is generic and its basic API provides access to all elements and attribute values. Attribute access is by name: e.g. to get the value of the "width" attribute, call GetAttributeL("width") or a close approximation, and the value will be returned as another string.

No DTD element classes are necessary. All elements are constructed from the generic element class and will have the following functionality:

• The element class has member variables created for each element attribute defined. Each member variable has standard accessor and mutator functions defined.

• Validation of attribute values can be carried out by calling IsValidAttributeForElementL(). DTD specific validation will be done, based on the MXMLDtd object passed into the document on creation.

• The element class has a CheckChildren() function created to check that any child elements conform in type and order to the requirements of the DTD. This is achieved by calling CheckValidChildren() on the DTD object owned by the document.

To allow the a mini-DOM tree to be validated for a specific DTD, a DTD interface class MXMLDtd is defined from which specific DTD classes are derived. The mini-DOM is then able to call DTD-specific functions through implementations of the interface.

The XML Parser is a single-pass parser with a two-stage pipeline. The first stage is basic lexical analysis that reads in data from a source, performs some housekeeping and normalisation functions on it and passes on meaningful sections of text to the second stage for parsing.

The following operations are performed on the input by the lexical analysis stage:

• Comments are stripped out.

• Processing instructions are stripped out.

Meaningful sections of text are as follows:

• Complete tag definitions (could be start tag, end tag or combined tag)

• Sections of text of specific CDATA sections

The second stage is to parse elements by breaking out the element name and sequence of attribute values and create generic attributes.

Built-in, character entities are replaced by their values if they have previously been defined. Any entity references that are not recognised will be left untouched.

The second parser stage creates DOM objects in a tree structure by adding new elements onto the child element list of each element as appropriate. Encountering a start tag causes an element to be created under the then-current element, while encountering an end tag causes the then-current element to move up the object tree. At the same time, the end tag is compared with the relevant element to ensure that start and end tags match. If an empty element tag is encountered, then the element is created, but the position for insertion of the next tag will not descend the object tree.

The XML Parser is generic and has no functionality specific to any particular DTD. Instead, validation/syntax checking is done through the Mini-DOM API.

The parser carries out the act of parsing an XML file as an Active Object. In the current version, a single activation of the object parses the whole file.

The XML Composer is presented with an object tree based on the DOM (mini or DTD-specific). It performs a tree walk for each element and, using the generic element API, accesses element details and outputs the text of the elements or the character data.

During the tree-walk, elements that are not empty result in a start tag and an end tag being output. Empty elements result in a single tag being output. Instances of characters that should be replaced by built-in entity references are so replaced.

An XML file that is parsed, and then the resulting object tree fed into the composer, will not necessarily create an output file that is identical to the input file: comments may be lost, and whitespace elements affected as well.