DOMDocument.hpp
上传用户:zhuqijet
上传日期:2013-06-25
资源大小:10074k
文件大小:40k
源码类别:

词法分析

开发平台:

Visual C++

  1. #ifndef DOMDocument_HEADER_GUARD_
  2. #define DOMDocument_HEADER_GUARD_
  3. /*
  4.  * The Apache Software License, Version 1.1
  5.  *
  6.  * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
  7.  * reserved.
  8.  *
  9.  * Redistribution and use in source and binary forms, with or without
  10.  * modification, are permitted provided that the following conditions
  11.  * are met:
  12.  *
  13.  * 1. Redistributions of source code must retain the above copyright
  14.  *    notice, this list of conditions and the following disclaimer.
  15.  *
  16.  * 2. Redistributions in binary form must reproduce the above copyright
  17.  *    notice, this list of conditions and the following disclaimer in
  18.  *    the documentation and/or other materials provided with the
  19.  *    distribution.
  20.  *
  21.  * 3. The end-user documentation included with the redistribution,
  22.  *    if any, must include the following acknowledgment:
  23.  *       "This product includes software developed by the
  24.  *        Apache Software Foundation (http://www.apache.org/)."
  25.  *    Alternately, this acknowledgment may appear in the software itself,
  26.  *    if and wherever such third-party acknowledgments normally appear.
  27.  *
  28.  * 4. The names "Xerces" and "Apache Software Foundation" must
  29.  *    not be used to endorse or promote products derived from this
  30.  *    software without prior written permission. For written
  31.  *    permission, please contact apache@apache.org.
  32.  *
  33.  * 5. Products derived from this software may not be called "Apache",
  34.  *    nor may "Apache" appear in their name, without prior written
  35.  *    permission of the Apache Software Foundation.
  36.  *
  37.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  38.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  39.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  40.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  41.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  42.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  43.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  44.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  45.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  46.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  47.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48.  * SUCH DAMAGE.
  49.  * ====================================================================
  50.  *
  51.  * This software consists of voluntary contributions made by many
  52.  * individuals on behalf of the Apache Software Foundation, and was
  53.  * originally based on software copyright (c) 2001, International
  54.  * Business Machines, Inc., http://www.ibm.com .  For more information
  55.  * on the Apache Software Foundation, please see
  56.  * <http://www.apache.org/>.
  57.  */
  58. /*
  59.  * $Id: DOMDocument.hpp,v 1.14 2003/05/14 19:23:20 gareth Exp $
  60. */
  61. #include <xercesc/util/XercesDefs.hpp>
  62. #include "DOMNode.hpp"
  63. #include "DOMDocumentRange.hpp"
  64. #include "DOMDocumentTraversal.hpp"
  65. XERCES_CPP_NAMESPACE_BEGIN
  66. class DOMConfiguration;
  67. class DOMDocumentType;
  68. class DOMElement;
  69. class DOMDocumentFragment;
  70. class DOMComment;
  71. class DOMCDATASection;
  72. class DOMProcessingInstruction;
  73. class DOMAttr;
  74. class DOMEntity;
  75. class DOMEntityReference;
  76. class DOMImplementation;
  77. class DOMNodeFilter;
  78. class DOMNodeList;
  79. class DOMNotation;
  80. class DOMText;
  81. class DOMNode;
  82. /**
  83.  * The <code>DOMDocument</code> interface represents the entire XML
  84.  * document. Conceptually, it is the root of the document tree, and provides
  85.  * the primary access to the document's data.
  86.  * <p>Since elements, text nodes, comments, processing instructions, etc.
  87.  * cannot exist outside the context of a <code>DOMDocument</code>, the
  88.  * <code>DOMDocument</code> interface also contains the factory methods needed
  89.  * to create these objects. The <code>DOMNode</code> objects created have a
  90.  * <code>ownerDocument</code> attribute which associates them with the
  91.  * <code>DOMDocument</code> within whose context they were created.
  92.  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
  93.  */
  94. class CDOM_EXPORT DOMDocument: public DOMDocumentRange,
  95.  public DOMDocumentTraversal,
  96.  public DOMNode {
  97. protected:
  98.     // -----------------------------------------------------------------------
  99.     //  Hidden constructors
  100.     // -----------------------------------------------------------------------
  101.     /** @name Hidden constructors */
  102.     //@{    
  103.     DOMDocument() {};
  104.     //@}
  105. private:
  106.     // -----------------------------------------------------------------------
  107.     // Unimplemented constructors and operators
  108.     // -----------------------------------------------------------------------
  109.     /** @name Unimplemented constructors and operators */
  110.     //@{
  111.     DOMDocument(const DOMDocument &);
  112.     DOMDocument & operator = (const DOMDocument &);
  113.     //@}
  114. public:
  115.     // -----------------------------------------------------------------------
  116.     //  All constructors are hidden, just the destructor is available
  117.     // -----------------------------------------------------------------------
  118.     /** @name Destructor */
  119.     //@{
  120.     /**
  121.      * Destructor
  122.      *
  123.      */
  124.     virtual ~DOMDocument() {};
  125.     //@}
  126.     // -----------------------------------------------------------------------
  127.     // Virtual DOMDocument interface
  128.     // -----------------------------------------------------------------------
  129.     /** @name Functions introduced in DOM Level 1 */
  130.     //@{
  131.     /**
  132.      * Creates an element of the type specified. Note that the instance
  133.      * returned implements the <code>DOMElement</code> interface, so attributes
  134.      * can be specified directly on the returned object.
  135.      * <br>In addition, if there are known attributes with default values,
  136.      * <code>DOMAttr</code> nodes representing them are automatically created
  137.      * and attached to the element.
  138.      * <br>To create an element with a qualified name and namespace URI, use
  139.      * the <code>createElementNS</code> method.
  140.      * @param tagName The name of the element type to instantiate. For XML,
  141.      *   this is case-sensitive.
  142.      * @return A new <code>DOMElement</code> object with the
  143.      *   <code>nodeName</code> attribute set to <code>tagName</code>, and
  144.      *   <code>localName</code>, <code>prefix</code>, and
  145.      *   <code>namespaceURI</code> set to <code>null</code>.
  146.      * @exception DOMException
  147.      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
  148.      *   illegal character.
  149.      * @since DOM Level 1
  150.      */
  151.     virtual DOMElement     *createElement(const XMLCh *tagName) = 0;
  152.     /**
  153.      * Creates an empty <code>DOMDocumentFragment</code> object.
  154.      * @return A new <code>DOMDocumentFragment</code>.
  155.      * @since DOM Level 1
  156.      */
  157.     virtual DOMDocumentFragment   *createDocumentFragment() = 0;
  158.     /**
  159.      * Creates a <code>DOMText</code> node given the specified string.
  160.      * @param data The data for the node.
  161.      * @return The new <code>DOMText</code> object.
  162.      * @since DOM Level 1
  163.      */
  164.     virtual DOMText         *createTextNode(const XMLCh *data) = 0;
  165.     /**
  166.      * Creates a <code>DOMComment</code> node given the specified string.
  167.      * @param data The data for the node.
  168.      * @return The new <code>DOMComment</code> object.
  169.      * @since DOM Level 1
  170.      */
  171.     virtual DOMComment      *createComment(const XMLCh *data) = 0;
  172.     /**
  173.      * Creates a <code>DOMCDATASection</code> node whose value is the specified
  174.      * string.
  175.      * @param data The data for the <code>DOMCDATASection</code> contents.
  176.      * @return The new <code>DOMCDATASection</code> object.
  177.      * @since DOM Level 1
  178.      */
  179.     virtual DOMCDATASection   *createCDATASection(const XMLCh *data) = 0;
  180.     /**
  181.      * Creates a <code>DOMProcessingInstruction</code> node given the specified
  182.      * name and data strings.
  183.      * @param target The target part of the processing instruction.
  184.      * @param data The data for the node.
  185.      * @return The new <code>DOMProcessingInstruction</code> object.
  186.      * @exception DOMException
  187.      *   INVALID_CHARACTER_ERR: Raised if the specified target contains an
  188.      *   illegal character.
  189.      * @since DOM Level 1
  190.      */
  191.     virtual DOMProcessingInstruction *createProcessingInstruction(const XMLCh *target,
  192.         const XMLCh *data) = 0;
  193.     /**
  194.      * Creates an <code>DOMAttr</code> of the given name. Note that the
  195.      * <code>DOMAttr</code> instance can then be set on an <code>DOMElement</code>
  196.      * using the <code>setAttributeNode</code> method.
  197.      * <br>To create an attribute with a qualified name and namespace URI, use
  198.      * the <code>createAttributeNS</code> method.
  199.      * @param name The name of the attribute.
  200.      * @return A new <code>DOMAttr</code> object with the <code>nodeName</code>
  201.      *   attribute set to <code>name</code>, and <code>localName</code>,
  202.      *   <code>prefix</code>, and <code>namespaceURI</code> set to
  203.      *   <code>null</code>. The value of the attribute is the empty string.
  204.      * @exception DOMException
  205.      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
  206.      *   illegal character.
  207.      * @since DOM Level 1
  208.      */
  209.     virtual DOMAttr     *createAttribute(const XMLCh *name) = 0;
  210.     /**
  211.      * Creates an <code>DOMEntityReference</code> object. In addition, if the
  212.      * referenced entity is known, the child list of the
  213.      * <code>DOMEntityReference</code> node is made the same as that of the
  214.      * corresponding <code>DOMEntity</code> node.If any descendant of the
  215.      * <code>DOMEntity</code> node has an unbound namespace prefix, the
  216.      * corresponding descendant of the created <code>DOMEntityReference</code>
  217.      * node is also unbound; (its <code>namespaceURI</code> is
  218.      * <code>null</code>). The DOM Level 2 does not support any mechanism to
  219.      * resolve namespace prefixes.
  220.      * @param name The name of the entity to reference.
  221.      * @return The new <code>DOMEntityReference</code> object.
  222.      * @exception DOMException
  223.      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
  224.      *   illegal character.
  225.      * @since DOM Level 1
  226.      */
  227.     virtual DOMEntityReference    *createEntityReference(const XMLCh *name) = 0;
  228.     /**
  229.      * The Document Type Declaration (see <code>DOMDocumentType</code>)
  230.      * associated with this document. For XML
  231.      * documents without a document type declaration this returns
  232.      * <code>null</code>. The DOM Level 2 does not support editing the
  233.      * Document Type Declaration. <code>docType</code> cannot be altered in
  234.      * any way, including through the use of methods inherited from the
  235.      * <code>DOMNode</code> interface, such as <code>insertNode</code> or
  236.      * <code>removeNode</code>.
  237.      * @since DOM Level 1
  238.      */
  239.     virtual DOMDocumentType       *getDoctype() const = 0;
  240.     /**
  241.      * The <code>DOMImplementation</code> object that handles this document. A
  242.      * DOM application may use objects from multiple implementations.
  243.      * @since DOM Level 1
  244.      */
  245.     virtual DOMImplementation  *getImplementation() const = 0;
  246.     /**
  247.      * This is a convenience attribute that allows direct access to the child
  248.      * node that is the root element of the document.
  249.      * @since DOM Level 1
  250.      */
  251.     virtual DOMElement     *getDocumentElement() const = 0;
  252.     /**
  253.      * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
  254.      * given tag name in the order in which they are encountered in a
  255.      * preorder traversal of the <code>DOMDocument</code> tree.
  256.      *
  257.      * The returned node list is "live", in that changes
  258.      * to the document tree made after a nodelist was initially
  259.      * returned will be immediately reflected in the node list.
  260.      * @param tagname The name of the tag to match on. The special value "*"
  261.      *   matches all tags.
  262.      * @return A new <code>DOMNodeList</code> object containing all the matched
  263.      *   <code>DOMElement(s)</code>.
  264.      * @since DOM Level 1
  265.      */
  266.     virtual DOMNodeList      *getElementsByTagName(const XMLCh *tagname) const = 0;
  267.     //@}
  268.     /** @name Functions introduced in DOM Level 2. */
  269.     //@{
  270.     /**
  271.      * Imports a node from another document to this document. The returned
  272.      * node has no parent; (<code>parentNode</code> is <code>null</code>).
  273.      * The source node is not altered or removed from the original document;
  274.      * this method creates a new copy of the source node.
  275.      * <br>For all nodes, importing a node creates a node object owned by the
  276.      * importing document, with attribute values identical to the source
  277.      * node's <code>nodeName</code> and <code>nodeType</code>, plus the
  278.      * attributes related to namespaces (<code>prefix</code>,
  279.      * <code>localName</code>, and <code>namespaceURI</code>). As in the
  280.      * <code>cloneNode</code> operation on a <code>DOMNode</code>, the source
  281.      * node is not altered.
  282.      * <br>Additional information is copied as appropriate to the
  283.      * <code>nodeType</code>, attempting to mirror the behavior expected if
  284.      * a fragment of XML source was copied from one document to
  285.      * another, recognizing that the two documents may have different DTDs
  286.      * in the XML case. The following list describes the specifics for each
  287.      * type of node.
  288.      * <dl>
  289.      * <dt>ATTRIBUTE_NODE</dt>
  290.      * <dd>The <code>ownerElement</code> attribute
  291.      * is set to <code>null</code> and the <code>specified</code> flag is
  292.      * set to <code>true</code> on the generated <code>DOMAttr</code>. The
  293.      * descendants of the source <code>DOMAttr</code> are recursively imported
  294.      * and the resulting nodes reassembled to form the corresponding subtree.
  295.      * Note that the <code>deep</code> parameter has no effect on
  296.      * <code>DOMAttr</code> nodes; they always carry their children with them
  297.      * when imported.</dd>
  298.      * <dt>DOCUMENT_FRAGMENT_NODE</dt>
  299.      * <dd>If the <code>deep</code> option
  300.      * was set to <code>true</code>, the descendants of the source element
  301.      * are recursively imported and the resulting nodes reassembled to form
  302.      * the corresponding subtree. Otherwise, this simply generates an empty
  303.      * <code>DOMDocumentFragment</code>.</dd>
  304.      * <dt>DOCUMENT_NODE</dt>
  305.      * <dd><code>DOMDocument</code>
  306.      * nodes cannot be imported.</dd>
  307.      * <dt>DOCUMENT_TYPE_NODE</dt>
  308.      * <dd><code>DOMDocumentType</code>
  309.      * nodes cannot be imported.</dd>
  310.      * <dt>ELEMENT_NODE</dt>
  311.      * <dd>Specified attribute nodes of the
  312.      * source element are imported, and the generated <code>DOMAttr</code>
  313.      * nodes are attached to the generated <code>DOMElement</code>. Default
  314.      * attributes are not copied, though if the document being imported into
  315.      * defines default attributes for this element name, those are assigned.
  316.      * If the <code>importNode</code> <code>deep</code> parameter was set to
  317.      * <code>true</code>, the descendants of the source element are
  318.      * recursively imported and the resulting nodes reassembled to form the
  319.      * corresponding subtree.</dd>
  320.      * <dt>ENTITY_NODE</dt>
  321.      * <dd><code>DOMEntity</code> nodes can be
  322.      * imported, however in the current release of the DOM the
  323.      * <code>DOMDocumentType</code> is readonly. Ability to add these imported
  324.      * nodes to a <code>DOMDocumentType</code> will be considered for addition
  325.      * to a future release of the DOM.On import, the <code>publicId</code>,
  326.      * <code>systemId</code>, and <code>notationName</code> attributes are
  327.      * copied. If a <code>deep</code> import is requested, the descendants
  328.      * of the the source <code>DOMEntity</code> are recursively imported and
  329.      * the resulting nodes reassembled to form the corresponding subtree.</dd>
  330.      * <dt>
  331.      * ENTITY_REFERENCE_NODE</dt>
  332.      * <dd>Only the <code>DOMEntityReference</code> itself is
  333.      * copied, even if a <code>deep</code> import is requested, since the
  334.      * source and destination documents might have defined the entity
  335.      * differently. If the document being imported into provides a
  336.      * definition for this entity name, its value is assigned.</dd>
  337.      * <dt>NOTATION_NODE</dt>
  338.      * <dd>
  339.      * <code>DOMNotation</code> nodes can be imported, however in the current
  340.      * release of the DOM the <code>DOMDocumentType</code> is readonly. Ability
  341.      * to add these imported nodes to a <code>DOMDocumentType</code> will be
  342.      * considered for addition to a future release of the DOM.On import, the
  343.      * <code>publicId</code> and <code>systemId</code> attributes are copied.
  344.      * Note that the <code>deep</code> parameter has no effect on
  345.      * <code>DOMNotation</code> nodes since they never have any children.</dd>
  346.      * <dt>
  347.      * PROCESSING_INSTRUCTION_NODE</dt>
  348.      * <dd>The imported node copies its
  349.      * <code>target</code> and <code>data</code> values from those of the
  350.      * source node.</dd>
  351.      * <dt>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</dt>
  352.      * <dd>These three
  353.      * types of nodes inheriting from <code>DOMCharacterData</code> copy their
  354.      * <code>data</code> and <code>length</code> attributes from those of
  355.      * the source node.</dd>
  356.      * </dl>
  357.      * @param importedNode The node to import.
  358.      * @param deep If <code>true</code>, recursively import the subtree under
  359.      *   the specified node; if <code>false</code>, import only the node
  360.      *   itself, as explained above. This has no effect on <code>DOMAttr</code>
  361.      *   , <code>DOMEntityReference</code>, and <code>DOMNotation</code> nodes.
  362.      * @return The imported node that belongs to this <code>DOMDocument</code>.
  363.      * @exception DOMException
  364.      *   NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
  365.      *   supported.
  366.      * @since DOM Level 2
  367.      */
  368.     virtual DOMNode        *importNode(DOMNode *importedNode, bool deep) = 0;
  369.     /**
  370.      * Creates an element of the given qualified name and namespace URI.
  371.      * @param namespaceURI The namespace URI of the element to create.
  372.      * @param qualifiedName The qualified name of the element type to
  373.      *   instantiate.
  374.      * @return A new <code>DOMElement</code> object with the following
  375.      *   attributes:
  376.      * <table border='1'>
  377.      * <tr>
  378.      * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
  379.      * <td valign='top' rowspan='1' colspan='1'>
  380.      *   <code>Value</code></td>
  381.      * </tr>
  382.      * <tr>
  383.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
  384.      * <td valign='top' rowspan='1' colspan='1'>
  385.      *   <code>qualifiedName</code></td>
  386.      * </tr>
  387.      * <tr>
  388.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.namespaceURI</code></td>
  389.      * <td valign='top' rowspan='1' colspan='1'>
  390.      *   <code>namespaceURI</code></td>
  391.      * </tr>
  392.      * <tr>
  393.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.prefix</code></td>
  394.      * <td valign='top' rowspan='1' colspan='1'>prefix, extracted
  395.      *   from <code>qualifiedName</code>, or <code>null</code> if there is
  396.      *   no prefix</td>
  397.      * </tr>
  398.      * <tr>
  399.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
  400.      * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
  401.      *   <code>qualifiedName</code></td>
  402.      * </tr>
  403.      * <tr>
  404.      * <td valign='top' rowspan='1' colspan='1'><code>DOMElement.tagName</code></td>
  405.      * <td valign='top' rowspan='1' colspan='1'>
  406.      *   <code>qualifiedName</code></td>
  407.      * </tr>
  408.      * </table>
  409.      * @exception DOMException
  410.      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name
  411.      *   contains an illegal character, per the XML 1.0 specification .
  412.      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
  413.      *   malformed per the Namespaces in XML specification, if the
  414.      *   <code>qualifiedName</code> has a prefix and the
  415.      *   <code>namespaceURI</code> is <code>null</code>, or if the
  416.      *   <code>qualifiedName</code> has a prefix that is "xml" and the
  417.      *   <code>namespaceURI</code> is different from "
  418.      *   http://www.w3.org/XML/1998/namespace" .
  419.      *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
  420.      *   support the <code>"XML"</code> feature, since namespaces were
  421.      *   defined by XML.
  422.      * @since DOM Level 2
  423.      */
  424.     virtual DOMElement         *createElementNS(const XMLCh *namespaceURI,
  425.                                               const XMLCh *qualifiedName) = 0;
  426.     /**
  427.      * Creates an attribute of the given qualified name and namespace URI.
  428.      * @param namespaceURI The namespace URI of the attribute to create.
  429.      * @param qualifiedName The qualified name of the attribute to
  430.      *   instantiate.
  431.      * @return A new <code>DOMAttr</code> object with the following attributes:
  432.      * <table border='1'>
  433.      * <tr>
  434.      * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
  435.      * <td valign='top' rowspan='1' colspan='1'>
  436.      *   <code>Value</code></td>
  437.      * </tr>
  438.      * <tr>
  439.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
  440.      * <td valign='top' rowspan='1' colspan='1'>qualifiedName</td>
  441.      * </tr>
  442.      * <tr>
  443.      * <td valign='top' rowspan='1' colspan='1'>
  444.      *   <code>DOMNode.namespaceURI</code></td>
  445.      * <td valign='top' rowspan='1' colspan='1'><code>namespaceURI</code></td>
  446.      * </tr>
  447.      * <tr>
  448.      * <td valign='top' rowspan='1' colspan='1'>
  449.      *   <code>DOMNode.prefix</code></td>
  450.      * <td valign='top' rowspan='1' colspan='1'>prefix, extracted from
  451.      *   <code>qualifiedName</code>, or <code>null</code> if there is no
  452.      *   prefix</td>
  453.      * </tr>
  454.      * <tr>
  455.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
  456.      * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
  457.      *   <code>qualifiedName</code></td>
  458.      * </tr>
  459.      * <tr>
  460.      * <td valign='top' rowspan='1' colspan='1'><code>DOMAttr.name</code></td>
  461.      * <td valign='top' rowspan='1' colspan='1'>
  462.      *   <code>qualifiedName</code></td>
  463.      * </tr>
  464.      * <tr>
  465.      * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeValue</code></td>
  466.      * <td valign='top' rowspan='1' colspan='1'>the empty
  467.      *   string</td>
  468.      * </tr>
  469.      * </table>
  470.      * @exception DOMException
  471.      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name
  472.      *   contains an illegal character, per the XML 1.0 specification .
  473.      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
  474.      *   malformed per the Namespaces in XML specification, if the
  475.      *   <code>qualifiedName</code> has a prefix and the
  476.      *   <code>namespaceURI</code> is <code>null</code>, if the
  477.      *   <code>qualifiedName</code> has a prefix that is "xml" and the
  478.      *   <code>namespaceURI</code> is different from "
  479.      *   http://www.w3.org/XML/1998/namespace", or if the
  480.      *   <code>qualifiedName</code>, or its prefix, is "xmlns" and the
  481.      *   <code>namespaceURI</code> is different from "
  482.      *   http://www.w3.org/2000/xmlns/".
  483.      *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
  484.      *   support the <code>"XML"</code> feature, since namespaces were
  485.      *   defined by XML.
  486.      * @since DOM Level 2
  487.      */
  488.     virtual DOMAttr        *createAttributeNS(const XMLCh *namespaceURI,
  489.                                             const XMLCh *qualifiedName) = 0;
  490.     /**
  491.      * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
  492.      * given local name and namespace URI in the order in which they are
  493.      * encountered in a preorder traversal of the <code>DOMDocument</code> tree.
  494.      * @param namespaceURI The namespace URI of the elements to match on. The
  495.      *   special value "*" matches all namespaces.
  496.      * @param localName The local name of the elements to match on. The
  497.      *   special value "*" matches all local names.
  498.      * @return A new <code>DOMNodeList</code> object containing all the matched
  499.      *   <code>DOMElement(s)</code>.
  500.      * @since DOM Level 2
  501.      */
  502.     virtual DOMNodeList        *getElementsByTagNameNS(const XMLCh *namespaceURI,
  503.                                                      const XMLCh *localName) const = 0;
  504.     /**
  505.      * Returns the <code>DOMElement</code> whose <code>ID</code> is given by
  506.      * <code>elementId</code>. If no such element exists, returns
  507.      * <code>null</code>. Behavior is not defined if more than one element
  508.      * has this <code>ID</code>. The DOM implementation must have
  509.      * information that says which attributes are of type ID. Attributes
  510.      * with the name "ID" are not of type ID unless so defined.
  511.      * Implementations that do not know whether attributes are of type ID or
  512.      * not are expected to return <code>null</code>.
  513.      * @param elementId The unique <code>id</code> value for an element.
  514.      * @return The matching element.
  515.      * @since DOM Level 2
  516.      */
  517.     virtual  DOMElement        * getElementById(const XMLCh *elementId) const = 0;
  518.     //@}
  519.     /** @name Functions introduced in DOM Level 3. */
  520.     //@{
  521.     /**
  522.      * An attribute specifying the actual encoding of this document. This is
  523.      * <code>null</code> otherwise.
  524.      * <br> This attribute represents the property [character encoding scheme]
  525.      * defined in.
  526.      *
  527.      * <p><b>"Experimental - subject to change"</b></p>
  528.      *
  529.      * @since DOM Level 3
  530.      */
  531.     virtual const XMLCh*           getActualEncoding() const = 0;
  532.     /**
  533.      * An attribute specifying the actual encoding of this document. This is
  534.      * <code>null</code> otherwise.
  535.      * <br> This attribute represents the property [character encoding scheme]
  536.      * defined in .
  537.      *
  538.      * <p><b>"Experimental - subject to change"</b></p>
  539.      *
  540.      * @since DOM Level 3
  541.      */
  542.     virtual void                   setActualEncoding(const XMLCh* actualEncoding) = 0;
  543.     /**
  544.      * An attribute specifying, as part of the XML declaration, the encoding
  545.      * of this document. This is <code>null</code> when unspecified.
  546.      *
  547.      * <p><b>"Experimental - subject to change"</b></p>
  548.      *
  549.      * @since DOM Level 3
  550.      */
  551.     virtual const XMLCh*           getEncoding() const = 0;
  552.     /**
  553.      * An attribute specifying, as part of the XML declaration, the encoding
  554.      * of this document. This is <code>null</code> when unspecified.
  555.      *
  556.      * <p><b>"Experimental - subject to change"</b></p>
  557.      *
  558.      * @since DOM Level 3
  559.      */
  560.     virtual void                   setEncoding(const XMLCh* encoding) = 0;
  561.     /**
  562.      * An attribute specifying, as part of the XML declaration, whether this
  563.      * document is standalone.
  564.      * <br> This attribute represents the property [standalone] defined in .
  565.      *
  566.      * <p><b>"Experimental - subject to change"</b></p>
  567.      *
  568.      * @since DOM Level 3
  569.      */
  570.     virtual bool                   getStandalone() const = 0;
  571.     /**
  572.      * An attribute specifying, as part of the XML declaration, whether this
  573.      * document is standalone.
  574.      * <br> This attribute represents the property [standalone] defined in .
  575.      *
  576.      * <p><b>"Experimental - subject to change"</b></p>
  577.      *
  578.      * @since DOM Level 3
  579.      */
  580.     virtual void                   setStandalone(bool standalone) = 0;
  581.     /**
  582.      * An attribute specifying, as part of the XML declaration, the version
  583.      * number of this document. This is <code>null</code> when unspecified.
  584.      * <br> This attribute represents the property [version] defined in .
  585.      *
  586.      * <p><b>"Experimental - subject to change"</b></p>
  587.      *
  588.      * @since DOM Level 3
  589.      */
  590.     virtual const XMLCh*           getVersion() const = 0;
  591.     /**
  592.      * An attribute specifying, as part of the XML declaration, the version
  593.      * number of this document. This is <code>null</code> when unspecified.
  594.      * <br> This attribute represents the property [version] defined in .
  595.      *
  596.      * <p><b>"Experimental - subject to change"</b></p>
  597.      *
  598.      * @since DOM Level 3
  599.      */
  600.     virtual void                   setVersion(const XMLCh* version) = 0;
  601.     /**
  602.      * The location of the document or <code>null</code> if undefined.
  603.      * <br>Beware that when the <code>DOMDocument</code> supports the feature
  604.      * "HTML" , the href attribute of the HTML BASE element takes precedence
  605.      * over this attribute.
  606.      *
  607.      * <p><b>"Experimental - subject to change"</b></p>
  608.      *
  609.      * @since DOM Level 3
  610.      */
  611.     virtual const XMLCh*           getDocumentURI() const = 0;
  612.     /**
  613.      * The location of the document or <code>null</code> if undefined.
  614.      * <br>Beware that when the <code>DOMDocument</code> supports the feature
  615.      * "HTML" , the href attribute of the HTML BASE element takes precedence
  616.      * over this attribute.
  617.      *
  618.      * <p><b>"Experimental - subject to change"</b></p>
  619.      *
  620.      * @since DOM Level 3
  621.      */
  622.     virtual void                   setDocumentURI(const XMLCh* documentURI) = 0;
  623.     /**
  624.      * An attribute specifying whether errors checking is enforced or not.
  625.      * When set to <code>false</code>, the implementation is free to not
  626.      * test every possible error case normally defined on DOM operations,
  627.      * and not raise any <code>DOMException</code>. In case of error, the
  628.      * behavior is undefined. This attribute is <code>true</code> by
  629.      * defaults.
  630.      *
  631.      * <p><b>"Experimental - subject to change"</b></p>
  632.      *
  633.      * @since DOM Level 3
  634.      */
  635.     virtual bool                   getStrictErrorChecking() const = 0;
  636.     /**
  637.      * An attribute specifying whether errors checking is enforced or not.
  638.      * When set to <code>false</code>, the implementation is free to not
  639.      * test every possible error case normally defined on DOM operations,
  640.      * and not raise any <code>DOMException</code>. In case of error, the
  641.      * behavior is undefined. This attribute is <code>true</code> by
  642.      * defaults.
  643.      *
  644.      * <p><b>"Experimental - subject to change"</b></p>
  645.      *
  646.      * @since DOM Level 3
  647.      */
  648.     virtual void                   setStrictErrorChecking(bool strictErrorChecking) = 0;
  649.     /**
  650.      * Rename an existing node. When possible this simply changes the name of
  651.      * the given node, otherwise this creates a new node with the specified
  652.      * name and replaces the existing node with the new node as described
  653.      * below. This only applies to nodes of type <code>ELEMENT_NODE</code>
  654.      * and <code>ATTRIBUTE_NODE</code>.
  655.      * <br>When a new node is created, the following operations are performed:
  656.      * the new node is created, any registered event listener is registered
  657.      * on the new node, any user data attached to the old node is removed
  658.      * from that node, the old node is removed from its parent if it has
  659.      * one, the children are moved to the new node, if the renamed node is
  660.      * an <code>DOMElement</code> its attributes are moved to the new node, the
  661.      * new node is inserted at the position the old node used to have in its
  662.      * parent's child nodes list if it has one, the user data that was
  663.      * attached to the old node is attach to the new node, the user data
  664.      * event <code>NODE_RENAMED</code> is fired.
  665.      * <br>When the node being renamed is an <code>DOMAttr</code> that is
  666.      * attached to an <code>DOMElement</code>, the node is first removed from
  667.      * the <code>DOMElement</code> attributes map. Then, once renamed, either
  668.      * by modifying the existing node or creating a new one as described
  669.      * above, it is put back.
  670.      *
  671.      * <p><b>"Experimental - subject to change"</b></p>
  672.      *
  673.      * @param n The node to rename.
  674.      * @param namespaceURI The new namespaceURI.
  675.      * @param name The new qualified name.
  676.      * @return The renamed node. This is either the specified node or the new
  677.      *   node that was created to replace the specified node.
  678.      * @exception DOMException
  679.      *   NOT_SUPPORTED_ERR: Raised when the type of the specified node is
  680.      *   neither <code>ELEMENT_NODE</code> nor <code>ATTRIBUTE_NODE</code>.
  681.      *   <br>WRONG_DOCUMENT_ERR: Raised when the specified node was created
  682.      *   from a different document than this document.
  683.      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
  684.      *   malformed per the Namespaces in XML specification, if the
  685.      *   <code>qualifiedName</code> has a prefix and the
  686.      *   <code>namespaceURI</code> is <code>null</code>, or if the
  687.      *   <code>qualifiedName</code> has a prefix that is "xml" and the
  688.      *   <code>namespaceURI</code> is different from "
  689.      *   http://www.w3.org/XML/1998/namespace" . Also raised, when the node
  690.      *   being renamed is an attribute, if the <code>qualifiedName</code>,
  691.      *   or its prefix, is "xmlns" and the <code>namespaceURI</code> is
  692.      *   different from "http://www.w3.org/2000/xmlns/".
  693.      * @since DOM Level 3
  694.      */
  695.     virtual DOMNode* renameNode(DOMNode* n, const XMLCh* namespaceURI, const XMLCh* name) = 0;
  696.     /**
  697.      * Changes the <code>ownerDocument</code> of a node, its children, as well
  698.      * as the attached attribute nodes if there are any. If the node has a
  699.      * parent it is first removed from its parent child list. This
  700.      * effectively allows moving a subtree from one document to another. The
  701.      * following list describes the specifics for each type of node.
  702.      *
  703.      * <p><b>"Experimental - subject to change"</b></p>
  704.      *
  705.      * <dl>
  706.      * <dt>
  707.      * ATTRIBUTE_NODE</dt>
  708.      * <dd>The <code>ownerElement</code> attribute is set to
  709.      * <code>null</code> and the <code>specified</code> flag is set to
  710.      * <code>true</code> on the adopted <code>DOMAttr</code>. The descendants
  711.      * of the source <code>DOMAttr</code> are recursively adopted.</dd>
  712.      * <dt>
  713.      * DOCUMENT_FRAGMENT_NODE</dt>
  714.      * <dd>The descendants of the source node are
  715.      * recursively adopted.</dd>
  716.      * <dt>DOCUMENT_NODE</dt>
  717.      * <dd><code>DOMDocument</code> nodes cannot
  718.      * be adopted.</dd>
  719.      * <dt>DOCUMENT_TYPE_NODE</dt>
  720.      * <dd><code>DOMDocumentType</code> nodes cannot
  721.      * be adopted.</dd>
  722.      * <dt>ELEMENT_NODE</dt>
  723.      * <dd>Specified attribute nodes of the source
  724.      * element are adopted, and the generated <code>DOMAttr</code> nodes.
  725.      * Default attributes are discarded, though if the document being
  726.      * adopted into defines default attributes for this element name, those
  727.      * are assigned. The descendants of the source element are recursively
  728.      * adopted.</dd>
  729.      * <dt>ENTITY_NODE</dt>
  730.      * <dd><code>DOMEntity</code> nodes cannot be adopted.</dd>
  731.      * <dt>
  732.      * ENTITY_REFERENCE_NODE</dt>
  733.      * <dd>Only the <code>DOMEntityReference</code> node
  734.      * itself is adopted, the descendants are discarded, since the source
  735.      * and destination documents might have defined the entity differently.
  736.      * If the document being imported into provides a definition for this
  737.      * entity name, its value is assigned.</dd>
  738.      * <dt>NOTATION_NODE</dt>
  739.      * <dd><code>DOMNotation</code>
  740.      * nodes cannot be adopted.</dd>
  741.      * <dt>PROCESSING_INSTRUCTION_NODE, TEXT_NODE,
  742.      * CDATA_SECTION_NODE, COMMENT_NODE</dt>
  743.      * <dd>These nodes can all be adopted. No
  744.      * specifics.</dd>
  745.      * </dl>
  746.      * @param source The node to move into this document.
  747.      * @return The adopted node, or <code>null</code> if this operation
  748.      *   fails, such as when the source node comes from a different
  749.      *   implementation.
  750.      * @exception DOMException
  751.      *   NOT_SUPPORTED_ERR: Raised if the source node is of type
  752.      *   <code>DOCUMENT</code>, <code>DOCUMENT_TYPE</code>.
  753.      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is
  754.      *   readonly.
  755.      * @since DOM Level 3
  756.      */
  757.     virtual DOMNode*               adoptNode(DOMNode* source) = 0;
  758.     /**
  759.      * This method acts as if the document was going through a save and load
  760.      * cycle, putting the document in a "normal" form. The actual result
  761.      * depends on the features being set. See <code>DOMConfiguration</code> for 
  762.      * details.
  763.      *
  764.      * <p><b>"Experimental - subject to change"</b></p>
  765.      *
  766.      * <br>Noticeably this method normalizes <code>DOMText</code> nodes, makes
  767.      * the document "namespace wellformed", according to the algorithm
  768.      * described below in pseudo code, by adding missing namespace
  769.      * declaration attributes and adding or changing namespace prefixes,
  770.      * updates the replacement tree of <code>DOMEntityReference</code> nodes,
  771.      * normalizes attribute values, etc.
  772.      * <br>Mutation events, when supported, are generated to reflect the
  773.      * changes occuring on the document.
  774.      * Note that this is a partial implementation. Not all the required features are implemented.
  775.      * Currently <code>DOMAttr</code> and <code>DOMText</code> nodes are normalized. 
  776.      * Features to remove <code>DOMComment</code> and <code>DOMCDATASection</code> work.
  777.      * The feature to normalize namespaces is implemented. This feature is called 
  778.      * "namespaces" and is incorectly documented in the current WD.
  779.      * @since DOM Level 3 
  780.      *
  781.      */
  782.     virtual void                   normalizeDocument() = 0;
  783.     /**
  784.      * The configuration used when Document.normalizeDocument is invoked.
  785.      * 
  786.      * @return The <code>DOMConfiguration</code> from this <code>DOMDocument</code>
  787.      *
  788.      * Note that this is a partial implementation. Not all the required features are 
  789.      * implemented and this is only used by normalizeDocument.
  790.      * Currently <code>DOMAttr</code> and <code>DOMText</code> nodes are normalized. 
  791.      * Features to remove <code>DOMComment</code> and <code>DOMCDATASection</code> work.
  792.      * The feature to normalize namespaces is implemented. This feature is called 
  793.      * "namespaces" and is incorectly documented in the current WD.
  794.      *
  795.      * <p><b>"Experimental - subject to change"</b></p>
  796.      * @since DOM Level 3
  797.      */
  798.     virtual DOMConfiguration*      getDOMConfiguration() const = 0;
  799.     // -----------------------------------------------------------------------
  800.     // Non-standard extension
  801.     // -----------------------------------------------------------------------
  802.     /** @name Non-standard extension */
  803.     //@{
  804.     /**
  805.      * Non-standard extension
  806.      *
  807.      * Create a new entity.
  808.      * @param name The name of the entity to instantiate
  809.      *
  810.      */
  811.     virtual DOMEntity     *createEntity(const XMLCh *name) = 0;
  812.     /**
  813.      * Non-standard extension
  814.      *
  815.      * Create a DOMDocumentType node.
  816.      * @return A <code>DOMDocumentType</code> that references the newly
  817.      *  created DOMDocumentType node.
  818.      *
  819.      */
  820.     virtual DOMDocumentType *createDocumentType(const XMLCh *name) = 0;
  821.     /**
  822.      * Non-standard extension.
  823.      *
  824.      * Create a Notation.
  825.      * @param name The name of the notation to instantiate
  826.      * @return A <code>DOMNotation</code> that references the newly
  827.      *  created DOMNotation node.
  828.      */
  829.     virtual DOMNotation *createNotation(const XMLCh *name) = 0;
  830.     /**
  831.      * Non-standard extension.
  832.      *
  833.      * Creates an element of the given qualified name and
  834.      * namespace URI, and also stores line/column number info.
  835.      * Used by internally XSDXercesDOMParser during schema traversal.
  836.      *
  837.      * @see createElementNS(const XMLCh *namespaceURI, const XMLCh *qualifiedName)
  838.      */
  839.     virtual DOMElement         *createElementNS(const XMLCh *namespaceURI,
  840.                                                   const XMLCh *qualifiedName,
  841.                                                   const XMLSSize_t lineNum,
  842.                                                   const XMLSSize_t columnNum) = 0;
  843.     //@}
  844. };
  845. XERCES_CPP_NAMESPACE_END
  846. #endif