<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403" xml:lang="en"><title>XML

DOM Engine Overview</title><shortdesc>The XML DOM Engine implements the standard DOM API (tree-based

XML parsing and editing), including XPath and serialization extensions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p>The XML DOM Engine provides APIs to achieve

the following: </p> <ul>

<li id="GUID-D9B629FA-A426-5B43-ABAD-B49404822464"><p>Parse XML content: create

a DOM tree from XML streams or files </p> </li>

<li id="GUID-EBEBE1E6-1AEF-5181-A7C4-D4E3E3152FE4"><p>Create an empty DOM

tree </p> </li>

<li id="GUID-C8B88AF6-A2F0-5AE1-B207-8D56988DC5F9"><p>Modify a DOM tree by

adding or removing nodes and changing their properties (attributes?) </p> </li>

<li id="GUID-70322A4D-BDD9-5A93-8D38-107E46F4C952"><p>Save a DOM tree to a

buffer or a file (in regular XML, XOP or compressed format) </p> </li>

<li id="GUID-1A8514F7-534B-5C2A-9EF5-6F444B2FEE9F"><p>Explore a DOM tree with

XPath expressions </p> </li>

</ul> </section>

<section><title>Required background</title> <p>The XML DOM engine is based

on the <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2</xref> component.

It provides a Level-3-like implementation of the <xref href="http://www.w3.org/DOM/" scope="external">DOM</xref> standard from W3C, along with <xref href="http://www.w3.org/TR/xpath" scope="external">XPath</xref> and serialisation extensions. </p> </section>

<section><title>Key concepts and terms</title> <p>The following concepts are

related to generic XML understanding: </p><p><b>XPath Extension Functions</b></p><p>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. </p><p><b>Serialise</b></p><p>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. </p><p>The <b>RChunk</b> and <b>RHeap</b> classes

are standard Symbian platform classes. For more information,

see <xref href="GUID-6D8460DF-8B0F-5249-B236-92ABE0E67A14.dita">Memory allocation

concepts</xref>. </p> </section>

<section><title>Architecture</title> <p>The XML DOM Engine component relies

on the libxml2 component for most of its operations. For more information,

see <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2 Overview</xref>. </p> <p>It

also relies on the libxml2 SAX parser plugin of the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML

Framework</xref> and on the multi-part parser of the <xref href="GUID-C8BD333E-8384-534B-822B-F61B2F7C8B9F.dita">BAFL</xref> component

for deserialisation. </p> <p>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. </p> <fig id="GUID-EEFA9390-CA66-56DD-96B4-9DF7C35AB36D">

<title>              Package diagram for the XML DOM Engine component    

       </title>

<image href="GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e688779_href.png" placement="inline"/>

</fig> </section>

<section><title>Description</title> <p>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 <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML

Framework</xref> instead. </p> <p><b>DOM Parsing</b> </p> <p>Parsing an XML

document creates two parallel trees: the regular DOM tree containing generic

Node objects and an <xref href="GUID-87294A6B-4607-3D4A-9D1E-B87B16A06209.dita"><apiname>RXmlEngDocument</apiname></xref> 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. </p> <fig id="GUID-32F52AA5-2670-5C4C-B9EE-508BDB3B9E78">

<title>                 Extract of the class diagram for the XML DOM Engine

parser               </title>

<image href="GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e688810_href.png" placement="inline"/>

</fig> <p><b>Serialisation</b> </p> <p>Serialisation transforms the DOM tree

(including binary data) into one of the following formats: </p> <ul>

<li id="GUID-C7E6E69A-9373-5A8E-A0A4-FABA95738ACC"><p>Default (standard XML) </p> </li>

<li id="GUID-46B3A636-54BE-556A-B5D5-277378BD4BAB"><p>XOP (XML-binary Optimized

Packaging) </p> </li>

<li id="GUID-6DA98291-237E-5CD0-87ED-D6DBE56A9846"><p>XOP Infoset (original

Infoset with any optimized content replaced by <codeph>xop:Include</codeph> items) </p> </li>

<li id="GUID-235F5E65-C2A3-55FE-8537-B2F986367FFD"><p>gzip (compressed XML) </p> </li>

</ul> <p>The result can be returned as a file, a buffer or both. </p> <p><b>XPath

Extension Function</b> </p> <p>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. </p> <p>The XPath Extension Function

API provides two interfaces: <xref href="GUID-BCEBA44D-3C1A-38D2-BFDB-6CA14DF40CE9.dita"><apiname>MXPathExtensionFunction</apiname></xref> for

the XPath function and <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref> for

its configuration. The static <xref href="GUID-79B8C611-4646-330F-98EA-C387BDB430E2.dita"><apiname>TXmlEngXPathConfiguration</apiname></xref> class

performs the registration of the extension function within the XML DOM Engine. </p> </section>

<section><title>APIs</title> <p><b>DOM Parser API</b> </p> <p>The most relevant

classes for parsing and editing a DOM tree are listed in the following table.

See <xref href="GUID-326D4D50-5AD9-5CA2-8422-AA45AE0712D6.dita">Implementation

of W3C Types</xref> for correspondance between this API and the W3C standard. </p> <table id="GUID-B401C7C0-E8C1-5576-BF6A-DF722024F896">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>DOM Parser API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-A59972BD-707E-32B6-AF28-D2B8C6EA17F8.dita"><apiname>RXMLEngDOMImplementation</apiname></xref>  </p> </entry>

<entry><p>This class is the entry-point for the DOM Engine. It provides methods

for creating a new document or an instance of the DOM parser. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-701146BE-35E9-380F-AA58-25E4660C50EB.dita"><apiname>RXMLEngDomParser</apiname></xref>  </p> </entry>

<entry><p>This class provides methods for parsing an XML document and building

a DOM tree. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-BCF2D3E3-3A31-3D79-B355-04984EFF0551.dita"><apiname>RXMLEngDocument</apiname></xref>  </p> </entry>

<entry><p>This class represents a DOM tree. It stores the document properties

and provides methods for modifying the tree, such as adding or deleting nodes. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-56A1BCDD-A471-310B-8F9D-85AF2FAB2B37.dita"><apiname>TXMLEngNode</apiname></xref>  </p> </entry>

<entry><p>This class represents a DOM node. It stores the node type and properties,

and provides the DOM methods related to it. </p> <p>Specialisations of this

class are detailed in <xref href="GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita">XML

DOM Engine Node Reference</xref>. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The DOM API relies on Descriptor objects for string manipulation,

and on <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> handles for filesystem input and output. To

store <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> in a DOM tree, use the <xref href="GUID-FC3D2792-A98A-37FF-A59C-28DF0555FDCD.dita"><apiname>TXmlEngFileContainer</apiname></xref> class.

To store <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> in a DOM tree, use the <xref href="GUID-5D101B85-E1D0-3C78-8C97-3FB8CE459EC6.dita"><apiname>TXmlEngChunkContainer</apiname></xref> class. </p> <p><b>Serialisation

API</b> </p> <p>The most relevant classes for DOM serialisation and deserialisation

are listed in the following table. Other classes can be found in the reference

documentation. </p> <table id="GUID-0FBACCD6-BC4D-5CAF-88E7-61DE329EADB4">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Serialisation API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-ADFEF636-484D-35BF-B6C5-B9F47317ACD9.dita"><apiname>CXmlEngSerializer</apiname></xref>  </p> </entry>

<entry><p>This class provides methods to save a DOM tree to a file or a buffer. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-791D9C19-3942-3107-8C91-F56528CF2590.dita"><apiname>CXmlEngDeserializer</apiname></xref>  </p> </entry>

<entry><p>This class provides methods to read serialised XOP or GZIP and create

DOM or SAX representations of it. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>XPath APIs</b> </p> <p>The DOM Parsing classes related to XPath

are listed in the following table. Other classes can be found in the reference

documentation. </p> <table id="GUID-0E32710B-BEA3-5D01-B48F-BC753AA13625">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>XPath API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-036E87E6-F6FB-371B-8CAB-FBD8C2635FDA.dita"><apiname>RXmlEngXPathExpression</apiname></xref>  </p> </entry>

<entry><p>This class represents an XPath expression. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-D76EC81E-B92E-304A-8651-068459763BBA.dita"><apiname>TXmlEmgXPathEvaluator</apiname></xref>  </p> </entry>

<entry><p>This class evaluates an XPath expression and returns the result

in an <xref href="GUID-C84A1329-F403-370F-9740-6A8D38D72F22.dita"><apiname>RXmlEngXPathResult</apiname></xref> instance. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-1053AD9F-99BD-34D8-A77B-9B4F66FD7CCF.dita"><apiname>XmlEngXPathConfiguration</apiname></xref>  </p> </entry>

<entry><p>This class contains static methods for XPath configuration and registration

of extension functions. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>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. </p> <table id="GUID-6200B207-23F8-522A-885E-8DFA82CECE0F">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry> XPath Extension Function API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-6158C316-5D11-33D9-9599-4C3E98DF1748.dita"><apiname>MXmlEngXPathExtensionFunction</apiname></xref>  </p> </entry>

<entry><p>This interface must be implemented by your extension function. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref>  </p> </entry>

<entry><p>This interface must be implemented by your evaluation function,

which processes the arguments of the extension function and stores the result

of the evalutation. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Typical uses</title> <p>The XML DOM Engine is used by client

applications to process XML documents: </p> <ul>

<li id="GUID-4D5B1DAB-FEFD-5D66-8917-761042DC362A"><p>The most common clients

are web browsers and associated software, which parse and validate XML streams

or files. </p> </li>

<li id="GUID-4DFB1B4A-1F07-53E6-B043-D10D5C09679F"><p>Applications can also

use the XML DOM Engine to organize and store their data, or to transfer their

XML objects over a network connection. </p> </li>

<li id="GUID-98C0B034-7B47-5D00-8148-CEA28A53E9B0"><p>Middleware providers

can extend XPath with new functions with the XPath Extension Function API. </p> </li>

</ul> <p>To port an existing application that uses the standard libxml2 library,

use the <codeph>libxml2</codeph> component and call the C++ wrappers of the

standard library. </p> <p>Here are some of the common tasks that applications

perform through the XML DOM Engine: </p> <ul>

<li id="GUID-2F9859FD-1B09-58FB-849D-323B01D9F63D"><p>Read an XML file by

one of the following means: </p> <ul>

<li id="GUID-AC959FCA-A1F5-5691-8B4A-FFD8E385C25B"><p>Use the <xref href="GUID-B575F3B3-85B0-3709-932A-99C0388D8B6E.dita"><apiname>RXMLEngDOMParser</apiname></xref> class

to parse a regular XML file and get a DOM tree, as explained in the <xref href="GUID-C5C30218-311C-58D9-A990-3F95642F7517.dita">XML DOM Parsing Tutorial</xref>. </p> </li>

<li id="GUID-EC051C8A-47D1-5DE3-9093-C67FA6F75896"><p>Use the <xref href="GUID-72FD946E-36E1-3229-BF78-0E03D84BCB95.dita"><apiname>CXMLEngineSaxPlugin</apiname></xref> class

to parse a regular XML file and get SAX events, as explained in the <xref href="GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808.dita#GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808/GUID-948C5BEE-0E05-525A-B601-909A1818FDA0">XML

SAX Parsing Tutorial</xref>. </p> </li>

<li id="GUID-149E3236-EAB3-5990-8E5C-40B36BB89ACB"><p>Use the <codeph>DeserializeL()&lt;/codeph&gt;

method of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise

a compressed XML file and get SAX events. </codeph></p> </li>

<li id="GUID-3165531B-E5EC-5965-ACA9-4B660C40C6D8"><p>Use the <codeph>UseDOMImplementation()</codeph> and <codeph>DeserializeL()</codeph> methods

of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise a compressed

XML file and get a DOM tree. </p> </li>

</ul> </li>

<li id="GUID-A2269AAD-B0F9-50D2-8A96-5AEC601C84AA"><p>Save an XML object to

a file by using the <xref href="GUID-CD621FD4-8ADE-3211-96E9-FC6EFC9AEE2C.dita"><apiname>TXmlEngSerializer</apiname></xref> class, as explained

in the <xref href="GUID-E20C2C98-A294-551B-99CF-BE1DAA6F597E.dita">XML Serialisation

Tutorial</xref>. </p> </li>

<li id="GUID-2999261C-7049-50A6-A1DF-79CD57A039C4"><p>Search through an XML

document with XPath, as explained in the <xref href="GUID-92C2317A-57B8-558E-984B-B10FD0404981.dita">XPath

Tutorial</xref>. </p> </li>

<li id="GUID-D527989F-D3D8-50B5-9191-FBD59FCAC335"><p>Add extension functions

to XPath, as explained in the <xref href="GUID-49A7E8FD-72DA-5D56-86BE-74AA9AAF7C02.dita">XPath

Extension Tutorial</xref>. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita"><linktext>XML Framework</linktext>

</link>

<link href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita"><linktext>libxml2</linktext>

</link>