XML DOM Engine Overview

Purpose

The XML DOM Engine provides APIs to achieve the following:

• Parse XML content: create a DOM tree from XML streams or files

• Create an empty DOM tree

• Modify a DOM tree by adding or removing nodes and changing their properties (attributes?)

• Save a DOM tree to a buffer or a file (in regular XML, XOP or compressed format)

• Explore a DOM tree with XPath expressions

Required background

The XML DOM engine is based on the libxml2 component. It provides a Level-3-like implementation of the DOM standard from W3C, along with XPath and serialisation extensions.

Key concepts and terms

The following concepts are related to generic XML understanding:

XPath Extension Functions

XML Path Language (or XPath) is a W3C standard designed to address parts of an XML document. A subset of XPath is also used for matching: that is, checking that a node matches a pattern. Extension Functions are not part of the W3C standard: you can implement them to add functionalities to XPath.

Serialise

Serialising means converting binary data to a persistent format that can be stored (to a buffer or a file) or transmitted over a data link. The reverse operation is called deserialising.

The RChunk and RHeap classes are standard Symbian platform classes. For more information, see Memory allocation concepts .

Architecture

The XML DOM Engine component relies on the libxml2 component for most of its operations. For more information, see libxml2 Overview .

It also relies on the libxml2 SAX parser plugin of the XML Framework and on the multi-part parser of the BAFL component for deserialisation.

The following package diagram summarises the dependencies of the XML DOM Engine and shows the three functionality groups that are described in the following section.

Description

The XML DOM Engine is an object-oriented provider of the DOM services included in the standard libxml2 library: tree-based parsing with validation and random access to the XML elements. If you need event-based parsing, use the XML Framework instead.

DOM Parsing

Parsing an XML document creates two parallel trees: the regular DOM tree containing generic Node objects and an RXmlEngDocument object which contains type-specific nodes. Use these type-specific nodes to avoid type-checking and casting the Nodes as well as to improve performance. Some of these node types are shown in the following diagram.

Serialisation

Serialisation transforms the DOM tree (including binary data) into one of the following formats:

• Default (standard XML)

• XOP (XML-binary Optimized Packaging)

• XOP Infoset (original Infoset with any optimized content replaced by xop:Include items)

• gzip (compressed XML)

The result can be returned as a file, a buffer or both.

XPath Extension Function

XPath can be extended at run-time by registering a new extension function. To call the new function, include it in an XPath expression evaluated by the XML DOM Engine.

The XPath Extension Function API provides two interfaces: MXPathExtensionFunction for the XPath function and MXmlEngXpathEvaluationContext for its configuration. The static TXmlEngXPathConfiguration class performs the registration of the extension function within the XML DOM Engine.

APIs

DOM Parser API

The most relevant classes for parsing and editing a DOM tree are listed in the following table. See Implementation of W3C Types for correspondance between this API and the W3C standard.

The DOM API relies on Descriptor objects for string manipulation, and on RFile handles for filesystem input and output. To store RFile in a DOM tree, use the TXmlEngFileContainer class. To store RChunk in a DOM tree, use the TXmlEngChunkContainer class.

Serialisation API

The most relevant classes for DOM serialisation and deserialisation are listed in the following table. Other classes can be found in the reference documentation.

XPath APIs

The DOM Parsing classes related to XPath are listed in the following table. Other classes can be found in the reference documentation.

The most relevant classes of the Extension Function API for XPath are listed in the following table. Other classes can be found in the reference documentation.

Typical uses

The XML DOM Engine is used by client applications to process XML documents:

• The most common clients are web browsers and associated software, which parse and validate XML streams or files.

• Applications can also use the XML DOM Engine to organize and store their data, or to transfer their XML objects over a network connection.

• Middleware providers can extend XPath with new functions with the XPath Extension Function API.

To port an existing application that uses the standard libxml2 library, use the libxml2 component and call the C++ wrappers of the standard library.

Here are some of the common tasks that applications perform through the XML DOM Engine:

• Read an XML file by one of the following means:

  • Use the RXMLEngDOMParser class to parse a regular XML file and get a DOM tree, as explained in the XML DOM Parsing Tutorial .

  • Use the CXMLEngineSaxPlugin class to parse a regular XML file and get SAX events, as explained in the XML SAX Parsing Tutorial .

  • Use the DeserializeL()</codeph> method of the TXmlEngDeserializer class to deserialise a compressed XML file and get SAX events.

  • Use the UseDOMImplementation() and DeserializeL() methods of the TXmlEngDeserializer class to deserialise a compressed XML file and get a DOM tree.

• Save an XML object to a file by using the TXmlEngSerializer class, as explained in the XML Serialisation Tutorial .

• Search through an XML document with XPath, as explained in the XPath Tutorial .

• Add extension functions to XPath, as explained in the XPath Extension Tutorial .