1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 /*

    18  * Licensed to the Apache Software Foundation (ASF) under one or more

    19  * contributor license agreements.  See the NOTICE file distributed with

    20  * this work for additional information regarding copyright ownership.

    21  * The ASF licenses this file to You under the Apache License, Version 2.0

    22  * (the "License"); you may not use this file except in compliance with

    23  * the License.  You may obtain a copy of the License at

    24  * 

    25  *      http://www.apache.org/licenses/LICENSE-2.0

    26  * 

    27  * Unless required by applicable law or agreed to in writing, software

    28  * distributed under the License is distributed on an "AS IS" BASIS,

    29  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    30  * See the License for the specific language governing permissions and

    31  * limitations under the License.

    32  */

    33 

    34 /*

    35  * $Id: DOM_Document.hpp 568078 2007-08-21 11:43:25Z amassari $

    36 */

    37 

    38 #ifndef DOM_Document_HEADER_GUARD_

    39 #define DOM_Document_HEADER_GUARD_

    40 

    41 #include <xercesc/util/XercesDefs.hpp>

    42 #include "DOM_DocumentType.hpp"

    43 #include "DOM_DOMImplementation.hpp"

    44 #include "DOM_Element.hpp"

    45 #include "DOM_DocumentFragment.hpp"

    46 #include "DOM_Comment.hpp"

    47 #include "DOM_CDATASection.hpp"

    48 #include "DOM_ProcessingInstruction.hpp"

    49 #include "DOM_Attr.hpp"

    50 #include "DOM_Entity.hpp"

    51 #include "DOM_EntityReference.hpp"

    52 #include "DOM_NodeList.hpp"

    53 #include "DOM_Notation.hpp"

    54 #include "DOM_Text.hpp"

    55 #include "DOM_Node.hpp"

    56 #include "DOM_NodeIterator.hpp"

    57 #include "DOM_TreeWalker.hpp"

    58 #include "DOM_XMLDecl.hpp"

    59 #include "DOM_Range.hpp"

    60 

    61 XERCES_CPP_NAMESPACE_BEGIN

    62 

    63 

    64 class DocumentImpl;

    65 class NodeIteratorImpl;

    66 

    67 

    68 /**

    69 * Class to refer to XML Document nodes in the DOM.

    70 *

    71 * Conceptually, a DOM document node is the root of the document tree, and provides

    72 * the  primary access to the document's data.

    73 * <p>Since elements, text nodes, comments, processing instructions, etc.

    74 * cannot exist outside the context of a <code>Document</code>, the

    75 * <code>Document</code> interface also contains the factory methods needed

    76 * to create these objects.  The <code>Node</code> objects created have a

    77 * <code>ownerDocument</code> attribute which associates them with the

    78 * <code>Document</code> within whose  context they were created.

    79 */

    80 class DEPRECATED_DOM_EXPORT DOM_Document: public DOM_Node {

    81 

    82 public:

    83     /** @name Constructors and assignment operators */

    84     //@{

    85     /**

    86      * The default constructor for DOM_Document creates a null

    87      * DOM_Document object that refers to no document.  It may subsequently be

    88      * assigned to refer to an actual Document node.

    89      *

    90      * To create a new document, use the static method

    91      *   <code> DOM_Document::createDocument(). </code>

    92      *

    93      */

    94     DOM_Document();

    95 

    96     /**

    97       * Copy constructor.  Creates a new <code>DOM_Document</code> that refers to the

    98       * same underlying actual document as the original.

    99       *

   100       * @param other The object to be copied

   101       */

   102     DOM_Document(const DOM_Document &other);

   103     /**

   104       * Assignment operator

   105       *

   106       * @param other The object to be copied

   107       */

   108     DOM_Document & operator = (const DOM_Document &other);

   109 

   110     /**

   111       * Assignment operator.  This overloaded variant is provided for

   112       *   the sole purpose of setting a DOM_Node reference variable to

   113       *   zero.  Nulling out a reference variable in this way will decrement

   114       *   the reference count on the underlying Node object that the variable

   115       *   formerly referenced.  This effect is normally obtained when reference

   116       *   variable goes out of scope, but zeroing them can be useful for

   117       *   global instances, or for local instances that will remain in scope

   118       *   for an extended time,  when the storage belonging to the underlying

   119       *   node needs to be reclaimed.

   120       *

   121       * @param val   Only a value of 0, or null, is allowed.

   122       */

   123     DOM_Document & operator = (const DOM_NullPtr *val);

   124 

   125 

   126 

   127 	//@}

   128   /** @name Destructor */

   129   //@{

   130 	

   131   /**

   132     * Destructor.  The object being destroyed is the reference

   133     * object, not the underlying Document itself.

   134     *

   135     * <p>The reference counting memory management will

   136     *  delete the underlying document itself if this

   137     * DOM_Document is the last remaining to refer to the Document,

   138     * and if there are no remaining references to any of the nodes

   139     * within the document tree.  If other live references do remain,

   140     * the underlying document itself remains also.

   141     *

   142     */

   143     ~DOM_Document();

   144 

   145   //@}

   146   /** @name Factory methods to create new nodes for the Document */

   147   //@{

   148 

   149     /**

   150     *   Create a new empty document.

   151     *

   152     *   This differs from the <code> DOM_Document </code> default

   153     *   constructor, which creates

   154     *   a null reference only, not an actual document.

   155     *

   156     *   <p>This function is an extension to the DOM API, which

   157     *   lacks any mechanism for the creation of new documents.

   158     *   @return A new <code>DOM_Document</code>, which may then

   159     *   be populated using the DOM API calls.

   160     */

   161     static DOM_Document   createDocument(MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   162 

   163     /**

   164     *  Create a new entity.

   165     *

   166     *  Non-standard extension.

   167     * @param name The name of the entity to instantiate

   168     *

   169     */

   170     DOM_Entity     createEntity(const DOMString &name);

   171 

   172     /**

   173     * Creates an element of the type specified.

   174     *

   175     * Note that the instance returned

   176     * implements the Element interface, so attributes can be specified

   177     * directly  on the returned object.

   178     * @param tagName The name of the element type to instantiate.

   179     * @return A <code>DOM_Element</code> that reference the new element.

   180     * @exception DOMException

   181     *   INVALID_CHARACTER_ERR: Raised if the specified name contains an

   182     *   illegal character.

   183     */

   184     DOM_Element     createElement(const DOMString &tagName);

   185 

   186     /**

   187     * Creates an element of the type specified.

   188     * This non-standard overload of createElement, with the name specified as

   189     * raw Unicode string, is intended for use from XML parsers,

   190     * and is the best performing way to create elements.  The name

   191     * string is not checked for conformance to the XML rules for valid

   192     * element names.

   193     *

   194     *

   195     * @param tagName The name of the element type to instantiate, as

   196     *    a null-terminated unicode string.

   197     * @return A new <CODE>DOM_Element</CODE>

   198     *        object with the <CODE>nodeName</CODE> attribute set to

   199     *        <CODE>tagName</CODE>, and <CODE>localName</CODE>,

   200     *        <CODE>prefix</CODE>, and <CODE>namespaceURI</CODE> set to

   201     *        <CODE>null</CODE>.

   202     */

   203     DOM_Element     createElement(const XMLCh *tagName);

   204 

   205 

   206     /**

   207     * Creates an empty DocumentFragment object.

   208     *

   209     * @return A <code>DOM_DocumentFragment</code> that references the newly

   210     * created document fragment.

   211     */

   212     DOM_DocumentFragment   createDocumentFragment();

   213 

   214     /**

   215     * Creates a Text node given the specified string.

   216     *

   217     * @param data The data for the node.

   218     * @return A <code>DOM_Text</code> object that references the newly

   219     *  created text node.

   220     */

   221     DOM_Text         createTextNode(const DOMString &data);

   222 

   223     /**

   224     * Creates a Comment node given the specified string.

   225     *

   226     * @param data The data for the comment.

   227     * @return A <code>DOM_Comment</code> that references the newly

   228     *  created comment node.

   229     */

   230     DOM_Comment      createComment(const DOMString &data);

   231 

   232     /**

   233     * Creates a CDATASection node whose value  is the specified

   234     * string.

   235     *

   236     * @param data The data for the <code>DOM_CDATASection</code> contents.

   237     * @return A <code>DOM_CDATASection</code> object.

   238     * @exception DOMException

   239     *   NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

   240     */

   241     DOM_CDATASection   createCDATASection(const DOMString &data);

   242 

   243     /**

   244     *  Create a DocumentType node.  Non-standard extension.

   245     *

   246     * @return A <code>DOM_DocumentType</code> that references the newly

   247     *  created DocumentType node.

   248     *

   249     */

   250     DOM_DocumentType createDocumentType(const DOMString &name);

   251 

   252 

   253     /**

   254     *  Create a Notation.

   255     *

   256     *  Non-standard extension.

   257     *

   258     *  @param name The name of the notation to instantiate

   259     * @return A <code>DOM_Notation</code> that references the newly

   260     *  created Notation node.

   261     */

   262     DOM_Notation createNotation(const DOMString &name);

   263 

   264 

   265     /**

   266     * Creates a ProcessingInstruction node given the specified

   267     * name and data strings.

   268     *

   269     * @param target The target part of the processing instruction.

   270     * @param data The data for the node.

   271     * @return A <code>DOM_ProcessingInstruction</code> that references the newly

   272     *  created PI node.

   273     * @exception DOMException

   274     *   INVALID_CHARACTER_ERR: Raised if an illegal character is specified.

   275     */

   276     DOM_ProcessingInstruction createProcessingInstruction(const DOMString &target,

   277         const DOMString &data);

   278 

   279 

   280     /**

   281      * Creates an Attr of the given name.

   282      *

   283      * Note that the

   284      * <code>Attr</code> instance can then be attached to an Element

   285      * using the <code>DOMElement::setAttribute()</code> method.

   286      * @param name The name of the attribute.

   287      * @return A new <CODE>DOM_Attr</CODE>

   288      *       object with the <CODE>nodeName</CODE> attribute set to

   289      *       <CODE>name</CODE>, and <CODE>localName</CODE>, <CODE>prefix</CODE>,

   290      *       and <CODE>namespaceURI</CODE> set to

   291      *       <CODE>null</CODE>.

   292      * @exception DOMException

   293      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an

   294      *   illegal character.

   295      */

   296     DOM_Attr     createAttribute(const DOMString &name);

   297 

   298 

   299     /**

   300      * Creates an EntityReference object.

   301      *

   302      * @param name The name of the entity to reference.

   303      * @return A <code>DOM_EntityReference</code> that references the newly

   304      *  created EntityReference node.

   305      * @exception DOMException

   306      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an

   307      *   illegal character.

   308      */

   309     DOM_EntityReference    createEntityReference(const DOMString &name);

   310 

   311 

   312     /**

   313      * Creates a NodeIterator object.   (DOM2)

   314      *

   315      * NodeIterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the

   316      * document subtree governed by a particular node, the results of a query, or any other set of nodes.

   317      * The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM Level 2

   318      * specifies a single NodeIterator implementation for document-order traversal of a document subtree.

   319      * Instances of these iterators are created by calling <code>DocumentTraversal.createNodeIterator()</code>.

   320      *

   321      * To produce a view of the document that has entity references expanded and does not

   322      * expose the entity reference node itself, use the <code>whatToShow</code> flags to hide the entity

   323      * reference node and set expandEntityReferences to true when creating the iterator. To

   324      * produce a view of the document that has entity reference nodes but no entity expansion,

   325      * use the <code>whatToShow</code> flags to show the entity reference node and set

   326      * expandEntityReferences to false.

   327      *

   328      * @param root The root node of the DOM tree

   329      * @param whatToShow This attribute determines which node types are presented via the iterator.

   330      * @param filter The filter used to screen nodes

   331      * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are

   332      *                   visible to the iterator. If false, they will be skipped over.

   333      */

   334 

   335     DOM_NodeIterator createNodeIterator(DOM_Node root,

   336                                         unsigned long whatToShow,

   337                                         DOM_NodeFilter*  filter,

   338                                         bool entityReferenceExpansion);

   339      /**

   340      * Creates a TreeWalker object.   (DOM2)

   341      *

   342      * TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined

   343      * by its whatToShow flags and any filters that are defined for the TreeWalker. Any function which performs

   344      * navigation using a TreeWalker will automatically support any view defined by a TreeWalker.

   345      *

   346      * Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from

   347      * the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may

   348      * be children of different, widely separated nodes in the original view. For instance, consider a Filter that skips

   349      * all nodes except for Text nodes and the root node of a document. In the logical view that results, all text

   350      * nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the

   351      * structure of the original document.

   352      *

   353      * To produce a view of the document that has entity references expanded

   354      * and does not expose the entity reference node itself, use the whatToShow

   355      * flags to hide the entity reference node and set <code>expandEntityReferences</code> to

   356      * true when creating the TreeWalker. To produce a view of the document

   357      * that has entity reference nodes but no entity expansion, use the

   358      * <code>whatToShow</code> flags to show the entity reference node and set

   359      * <code>expandEntityReferences</code> to false

   360      *

   361      * @param root The root node of the DOM tree

   362      * @param whatToShow This attribute determines which node types are presented via the tree-walker.

   363      * @param filter The filter used to screen nodes

   364      * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are

   365      *                   visible to the tree-walker. If false, they will be skipped over.

   366      */

   367 

   368     DOM_TreeWalker  createTreeWalker(DOM_Node root,

   369                                      unsigned long whatToShow,

   370                                      DOM_NodeFilter*  filter,

   371                                      bool entityReferenceExpansion);

   372 

   373     /**

   374      * Creates a XMLDecl type Node .   Non-Standard (an extension to xerces)

   375      *

   376      * XMLDecl Nodes are created to get  version, encoding and standalone information in a document tree

   377      *

   378      * This node if created gets attached to a document object or an entity node. There can be no child

   379      * to this type of node.

   380      *

   381      * @param version The version data of the document. Currently possible value is 1.0

   382      * @param encoding The encoding type specified in the document

   383      * @param standalone The information whether the document is standalone or not

   384      */

   385 

   386     DOM_XMLDecl createXMLDecl(const DOMString& version,

   387                             const DOMString& encoding,

   388                             const DOMString& standalone);

   389 

   390     /**

   391 	  * To create the range  consisting of boundary-points and offset of the

   392       * selected contents

   393       *

   394       * @return The initial state of the Range such that both the boundary-points

   395       * are positioned at the beginning of the corresponding DOM_DOcument, before

   396       * any content. The range returned can only be used to select content

   397       * associated with this document, or with documentFragments and Attrs for

   398       * which this document is the ownerdocument

   399 	  */

   400     DOM_Range    createRange();

   401 

   402     //@}

   403     /** @name Getter functions */

   404     //@{

   405     /**

   406      * Get Document Type Declaration (see <code>DOM_DocumentType</code>) associated

   407      * with  this document.

   408      *

   409      * For documents without

   410      * a document type declaration this returns <code>null</code> reference object. The DOM Level

   411      *  1 does not support editing the Document Type Declaration, therefore

   412      * <code>docType</code> cannot be altered in any way.

   413      */

   414     DOM_DocumentType       getDoctype() const;

   415 

   416 

   417 

   418     /**

   419      * Return the <code>DOMImplementation</code> object that handles this document.

   420      */

   421     DOM_DOMImplementation  &getImplementation() const;

   422 

   423 

   424     /**

   425      * Return a reference to the root element of the document.

   426      */

   427     DOM_Element     getDocumentElement() const;

   428 

   429     /**

   430      * Returns a <code>DOM_NodeList</code> of all the elements with a

   431      * given tag name.  The returned node list is "live", in that changes

   432      * to the document tree made after a nodelist was initially

   433      * returned will be immediately reflected in the node list.

   434      *

   435      * The elements in the node list are ordered in the same order in which they

   436      * would be encountered in a

   437      * preorder traversal of the <code>Document</code> tree.

   438      * @param tagname The name of the tag to match on. The special value "*"

   439      *   matches all tags.

   440      * @return A reference to a NodeList containing all the matched

   441      *   <code>Element</code>s.

   442      */

   443     DOM_NodeList           getElementsByTagName(const DOMString &tagname) const;

   444 

   445     //@}

   446     /** @name Functions introduced in DOM Level 2. */

   447     //@{

   448 

   449     /**

   450      * Imports a node from another document to this document.

   451      * The returned node has no parent (<CODE>parentNode</CODE> is

   452      * <CODE>null</CODE>). The source node is not altered or removed from the

   453      * original document; this method creates a new copy of the source

   454      * node.<BR>For all nodes, importing a node creates a node object owned by

   455      * the importing document, with attribute values identical to the source

   456      * node's <CODE>nodeName</CODE> and <CODE>nodeType</CODE>, plus the

   457      * attributes related to namespaces (prefix and namespaces URI).

   458      *

   459      * @param importedNode The node to import.

   460      * @param deep If <CODE>true</CODE>, recursively import the subtree under the

   461      *      specified node; if <CODE>false</CODE>, import only the node itself,

   462      *      as explained above. This does not apply to <CODE>DOM_Attr</CODE>,

   463      *      <CODE>DOM_EntityReference</CODE>, and <CODE>DOM_Notation</CODE> nodes.

   464      * @return The imported node that belongs to this <CODE>DOM_Document</CODE>.

   465      * @exception DOMException

   466      *   NOT_SUPPORTED_ERR: Raised if the type of node being imported is

   467      *                      not supported.

   468      */

   469     DOM_Node            importNode(const DOM_Node &importedNode, bool deep);

   470 

   471     /**

   472      * Creates an element of the given qualified name and

   473      * namespace URI.

   474      *

   475      * @param namespaceURI The <em>namespace URI</em> of

   476      *   the element to create.

   477      * @param qualifiedName The <em>qualified name</em>

   478      *   of the element type to instantiate.

   479      * @return A new <code>DOM_Element</code> object.

   480      * @exception DOMException

   481      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name contains

   482      *                          an illegal character.

   483      * <br>

   484      *   NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is

   485      *      malformed, if the <CODE>qualifiedName</CODE> has a prefix and the

   486      *      <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,

   487      *      or if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and

   488      *      the <CODE>namespaceURI</CODE> is different from

   489      *      "http://www.w3.org/XML/1998/namespace".

   490      */

   491     DOM_Element         createElementNS(const DOMString &namespaceURI,

   492 	const DOMString &qualifiedName);

   493 

   494     /**

   495      * Creates an attribute of the given qualified name and namespace

   496      * URI.

   497      *

   498      * @param namespaceURI The <em>namespace URI</em> of

   499      *   the attribute to create.

   500      * @param qualifiedName The <em>qualified name</em>

   501      *   of the attribute to instantiate.

   502      * @return A new <code>DOM_Attr</code> object.

   503      * @exception DOMException

   504      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name contains

   505      *                          an illegal character.

   506      * <br>

   507      *   NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is

   508      *      malformed, if the <CODE>qualifiedName</CODE> has a prefix and the

   509      *      <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,

   510      *      if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and the

   511      *      <CODE>namespaceURI</CODE> is different from

   512      *      "http://www.w3.org/XML/1998/namespace", if the

   513      *      <CODE>qualifiedName</CODE> has a prefix that is "xmlns" and the

   514      *      <CODE>namespaceURI</CODE> is different from

   515      *      "http://www.w3.org/2000/xmlns/", or if the

   516      *      <CODE>qualifiedName</CODE> is "xmlns" and the

   517      *      <CODE>namespaceURI</CODE> is different from

   518      *      "http://www.w3.org/2000/xmlns/".

   519      */

   520     DOM_Attr            createAttributeNS(const DOMString &namespaceURI,

   521 	const DOMString &qualifiedName);

   522 

   523     /**

   524      * Returns a <code>DOM_NodeList</code> of all the <code>DOM_Element</code>s

   525      * with a given <em>local name</em> and

   526      * namespace URI in the order in which they would be encountered in a

   527      * preorder traversal of the <code>DOM_Document</code> tree.

   528      *

   529      * @param namespaceURI The <em>namespace URI</em> of

   530      *   the elements to match on. The special value "*" matches all

   531      *   namespaces.

   532      * @param localName The <em>local name</em> of the

   533      *   elements to match on. The special value "*" matches all local names.

   534      * @return A new <code>DOM_NodeList</code> object containing all the matched

   535      *  <code>DOM_Element</code>s.

   536      */

   537     DOM_NodeList        getElementsByTagNameNS(const DOMString &namespaceURI,

   538 	const DOMString &localName) const;

   539 

   540     /**

   541      * Returns the <code>DOM_Element</code> whose ID is given by <code>elementId</code>.

   542      * If no such element exists, returns <code>null</code>.

   543      * Behavior is not defined if more than one element has this <code>ID</code>.

   544      * <P><B>Note:</B> The DOM implementation must have information that says

   545      * which attributes are of type ID. Attributes with the name "ID" are not of

   546      * type ID unless so defined. Implementations that do not know whether

   547      * attributes are of type ID or not are expected to return

   548      * <CODE>null</CODE>.</P>

   549      *

   550      * @param elementId The unique <code>id</code> value for an element.

   551      * @return The matching element.

   552      */

   553     DOM_Element         getElementById(const DOMString &elementId);

   554 

   555     /**

   556      * Sets whether the DOM implementation performs error checking

   557      * upon operations. Turning off error checking only affects

   558      * the following DOM checks:

   559      * <ul>

   560      * <li>Checking strings to make sure that all characters are

   561      *     legal XML characters

   562      * <li>Hierarchy checking such as allowed children, checks for

   563      *     cycles, etc.

   564      * </ul>

   565      * <p>

   566      * Turning off error checking does <em>not</em> turn off the

   567      * following checks:

   568      * <ul>

   569      * <li>Read only checks

   570      * <li>Checks related to DOM events

   571      * </ul>

   572      */

   573     void setErrorChecking(bool check);

   574 

   575     /**

   576      * Returns true if the DOM implementation performs error checking.

   577      */

   578     bool getErrorChecking();

   579 

   580     //@}

   581 

   582 protected:

   583     DOM_Document (DocumentImpl *impl);

   584 

   585     friend class DOM_Node;

   586     friend class DocumentImpl;

   587     friend class NodeIteratorImpl;

   588     friend class DOM_DOMImplementation;

   589 

   590 };

   591 

   592 

   593 XERCES_CPP_NAMESPACE_END

   594 

   595 #endif