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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

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

    16 the following: </p> <ul>

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

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

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

    20 tree </p> </li>

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

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

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

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

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

    26 XPath expressions </p> </li>

    27 </ul> </section>

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

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

    30 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>

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

    32 related to generic XML understanding: </p><p><b>XPath Extension Functions</b></p><p>XML

    33 Path Language (or XPath) is a W3C standard designed to address parts of an

    34 XML document. A subset of XPath is also used for matching: that is, checking

    35 that a node matches a pattern. Extension Functions are not part of the W3C

    36 standard: you can implement them to add functionalities to XPath. </p><p><b>Serialise</b></p><p>Serialising

    37 means converting binary data to a persistent format that can be stored (to

    38 a buffer or a file) or transmitted over a data link. The reverse operation

    39 is called deserialising. </p><p>The <b>RChunk</b> and <b>RHeap</b> classes

    40 are standard Symbian platform classes. For more information,

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

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

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

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

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

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

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

    48 for deserialisation. </p> <p>The following package diagram summarises the

    49 dependencies of the XML DOM Engine and shows the three functionality groups

    50 that are described in the following section. </p> <fig id="GUID-EEFA9390-CA66-56DD-96B4-9DF7C35AB36D">

    51 <title>              Package diagram for the XML DOM Engine component    

    52        </title>

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

    54 </fig> </section>

    55 <section><title>Description</title> <p>The XML DOM Engine is an object-oriented

    56 provider of the DOM services included in the standard libxml2 library: tree-based

    57 parsing with validation and random access to the XML elements. If you need

    58 event-based parsing, use the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML

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

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

    61 Node objects and an <xref href="GUID-87294A6B-4607-3D4A-9D1E-B87B16A06209.dita"><apiname>RXmlEngDocument</apiname></xref> object which contains

    62 type-specific nodes. Use these type-specific nodes to avoid type-checking

    63 and casting the Nodes as well as to improve performance. Some of these node

    64 types are shown in the following diagram. </p> <fig id="GUID-32F52AA5-2670-5C4C-B9EE-508BDB3B9E78">

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

    66 parser               </title>

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

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

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

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

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

    72 Packaging) </p> </li>

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

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

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

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

    77 Extension Function</b> </p> <p>XPath can be extended at run-time by registering

    78 a new extension function. To call the new function, include it in an XPath

    79 expression evaluated by the XML DOM Engine. </p> <p>The XPath Extension Function

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

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

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

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

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

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

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

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

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

    89 <thead>

    90 <row>

    91 <entry>DOM Parser API</entry>

    92 <entry>Description</entry>

    93 </row>

    94 </thead>

    95 <tbody>

    96 <row>

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

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

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

   100 </row>

   101 <row>

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

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

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

   105 </row>

   106 <row>

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

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

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

   110 </row>

   111 <row>

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

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

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

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

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

   117 </row>

   118 </tbody>

   119 </tgroup>

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

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

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

   123 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

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

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

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

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

   128 <thead>

   129 <row>

   130 <entry>Serialisation API</entry>

   131 <entry>Description</entry>

   132 </row>

   133 </thead>

   134 <tbody>

   135 <row>

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

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

   138 </row>

   139 <row>

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

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

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

   143 </row>

   144 </tbody>

   145 </tgroup>

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

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

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

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

   150 <thead>

   151 <row>

   152 <entry>XPath API</entry>

   153 <entry>Description</entry>

   154 </row>

   155 </thead>

   156 <tbody>

   157 <row>

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

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

   160 </row>

   161 <row>

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

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

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

   165 </row>

   166 <row>

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

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

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

   170 </row>

   171 </tbody>

   172 </tgroup>

   173 </table> <p>The most relevant classes of the Extension Function API for XPath

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

   175 documentation. </p> <table id="GUID-6200B207-23F8-522A-885E-8DFA82CECE0F">

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

   177 <thead>

   178 <row>

   179 <entry> XPath Extension Function API</entry>

   180 <entry>Description</entry>

   181 </row>

   182 </thead>

   183 <tbody>

   184 <row>

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

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

   187 </row>

   188 <row>

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

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

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

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

   193 </row>

   194 </tbody>

   195 </tgroup>

   196 </table> </section>

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

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

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

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

   201 or files. </p> </li>

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

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

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

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

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

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

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

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

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

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

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

   213 <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

   214 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>

   215 <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

   216 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

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

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

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

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

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

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

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

   224 </ul> </li>

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

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

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

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

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

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

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

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

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

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

   235 </ul> </section>

   236 </conbody><related-links>

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

   238 </link>

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

   240 </link>

   241 </related-links></concept>