/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * $Id: DOM_Document.hpp 568078 2007-08-21 11:43:25Z amassari $ */ #ifndef DOM_Document_HEADER_GUARD_ #define DOM_Document_HEADER_GUARD_ #include #include "DOM_DocumentType.hpp" #include "DOM_DOMImplementation.hpp" #include "DOM_Element.hpp" #include "DOM_DocumentFragment.hpp" #include "DOM_Comment.hpp" #include "DOM_CDATASection.hpp" #include "DOM_ProcessingInstruction.hpp" #include "DOM_Attr.hpp" #include "DOM_Entity.hpp" #include "DOM_EntityReference.hpp" #include "DOM_NodeList.hpp" #include "DOM_Notation.hpp" #include "DOM_Text.hpp" #include "DOM_Node.hpp" #include "DOM_NodeIterator.hpp" #include "DOM_TreeWalker.hpp" #include "DOM_XMLDecl.hpp" #include "DOM_Range.hpp" XERCES_CPP_NAMESPACE_BEGIN class DocumentImpl; class NodeIteratorImpl; /** * Class to refer to XML Document nodes in the DOM. * * Conceptually, a DOM document node is the root of the document tree, and provides * the primary access to the document's data. *

Since elements, text nodes, comments, processing instructions, etc. * cannot exist outside the context of a Document, the * Document interface also contains the factory methods needed * to create these objects. The Node objects created have a * ownerDocument attribute which associates them with the * Document within whose context they were created. */ class DEPRECATED_DOM_EXPORT DOM_Document: public DOM_Node { public: /** @name Constructors and assignment operators */ //@{ /** * The default constructor for DOM_Document creates a null * DOM_Document object that refers to no document. It may subsequently be * assigned to refer to an actual Document node. * * To create a new document, use the static method * DOM_Document::createDocument(). * */ DOM_Document(); /** * Copy constructor. Creates a new DOM_Document that refers to the * same underlying actual document as the original. * * @param other The object to be copied */ DOM_Document(const DOM_Document &other); /** * Assignment operator * * @param other The object to be copied */ DOM_Document & operator = (const DOM_Document &other); /** * Assignment operator. This overloaded variant is provided for * the sole purpose of setting a DOM_Node reference variable to * zero. Nulling out a reference variable in this way will decrement * the reference count on the underlying Node object that the variable * formerly referenced. This effect is normally obtained when reference * variable goes out of scope, but zeroing them can be useful for * global instances, or for local instances that will remain in scope * for an extended time, when the storage belonging to the underlying * node needs to be reclaimed. * * @param val Only a value of 0, or null, is allowed. */ DOM_Document & operator = (const DOM_NullPtr *val); //@} /** @name Destructor */ //@{ /** * Destructor. The object being destroyed is the reference * object, not the underlying Document itself. * *

The reference counting memory management will * delete the underlying document itself if this * DOM_Document is the last remaining to refer to the Document, * and if there are no remaining references to any of the nodes * within the document tree. If other live references do remain, * the underlying document itself remains also. * */ ~DOM_Document(); //@} /** @name Factory methods to create new nodes for the Document */ //@{ /** * Create a new empty document. * * This differs from the DOM_Document default * constructor, which creates * a null reference only, not an actual document. * *

This function is an extension to the DOM API, which * lacks any mechanism for the creation of new documents. * @return A new DOM_Document, which may then * be populated using the DOM API calls. */ static DOM_Document createDocument(MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager); /** * Create a new entity. * * Non-standard extension. * @param name The name of the entity to instantiate * */ DOM_Entity createEntity(const DOMString &name); /** * Creates an element of the type specified. * * Note that the instance returned * implements the Element interface, so attributes can be specified * directly on the returned object. * @param tagName The name of the element type to instantiate. * @return A DOM_Element that reference the new element. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * illegal character. */ DOM_Element createElement(const DOMString &tagName); /** * Creates an element of the type specified. * This non-standard overload of createElement, with the name specified as * raw Unicode string, is intended for use from XML parsers, * and is the best performing way to create elements. The name * string is not checked for conformance to the XML rules for valid * element names. * * * @param tagName The name of the element type to instantiate, as * a null-terminated unicode string. * @return A new DOM_Element * object with the nodeName attribute set to * tagName, and localName, * prefix, and namespaceURI set to * null. */ DOM_Element createElement(const XMLCh *tagName); /** * Creates an empty DocumentFragment object. * * @return A DOM_DocumentFragment that references the newly * created document fragment. */ DOM_DocumentFragment createDocumentFragment(); /** * Creates a Text node given the specified string. * * @param data The data for the node. * @return A DOM_Text object that references the newly * created text node. */ DOM_Text createTextNode(const DOMString &data); /** * Creates a Comment node given the specified string. * * @param data The data for the comment. * @return A DOM_Comment that references the newly * created comment node. */ DOM_Comment createComment(const DOMString &data); /** * Creates a CDATASection node whose value is the specified * string. * * @param data The data for the DOM_CDATASection contents. * @return A DOM_CDATASection object. * @exception DOMException * NOT_SUPPORTED_ERR: Raised if this document is an HTML document. */ DOM_CDATASection createCDATASection(const DOMString &data); /** * Create a DocumentType node. Non-standard extension. * * @return A DOM_DocumentType that references the newly * created DocumentType node. * */ DOM_DocumentType createDocumentType(const DOMString &name); /** * Create a Notation. * * Non-standard extension. * * @param name The name of the notation to instantiate * @return A DOM_Notation that references the newly * created Notation node. */ DOM_Notation createNotation(const DOMString &name); /** * Creates a ProcessingInstruction node given the specified * name and data strings. * * @param target The target part of the processing instruction. * @param data The data for the node. * @return A DOM_ProcessingInstruction that references the newly * created PI node. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if an illegal character is specified. */ DOM_ProcessingInstruction createProcessingInstruction(const DOMString &target, const DOMString &data); /** * Creates an Attr of the given name. * * Note that the * Attr instance can then be attached to an Element * using the DOMElement::setAttribute() method. * @param name The name of the attribute. * @return A new DOM_Attr * object with the nodeName attribute set to * name, and localName, prefix, * and namespaceURI set to * null. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * illegal character. */ DOM_Attr createAttribute(const DOMString &name); /** * Creates an EntityReference object. * * @param name The name of the entity to reference. * @return A DOM_EntityReference that references the newly * created EntityReference node. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * illegal character. */ DOM_EntityReference createEntityReference(const DOMString &name); /** * Creates a NodeIterator object. (DOM2) * * NodeIterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the * document subtree governed by a particular node, the results of a query, or any other set of nodes. * The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM Level 2 * specifies a single NodeIterator implementation for document-order traversal of a document subtree. * Instances of these iterators are created by calling DocumentTraversal.createNodeIterator(). * * To produce a view of the document that has entity references expanded and does not * expose the entity reference node itself, use the whatToShow flags to hide the entity * reference node and set expandEntityReferences to true when creating the iterator. To * produce a view of the document that has entity reference nodes but no entity expansion, * use the whatToShow flags to show the entity reference node and set * expandEntityReferences to false. * * @param root The root node of the DOM tree * @param whatToShow This attribute determines which node types are presented via the iterator. * @param filter The filter used to screen nodes * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are * visible to the iterator. If false, they will be skipped over. */ DOM_NodeIterator createNodeIterator(DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion); /** * Creates a TreeWalker object. (DOM2) * * TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined * by its whatToShow flags and any filters that are defined for the TreeWalker. Any function which performs * navigation using a TreeWalker will automatically support any view defined by a TreeWalker. * * Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from * the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may * be children of different, widely separated nodes in the original view. For instance, consider a Filter that skips * all nodes except for Text nodes and the root node of a document. In the logical view that results, all text * nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the * structure of the original document. * * To produce a view of the document that has entity references expanded * and does not expose the entity reference node itself, use the whatToShow * flags to hide the entity reference node and set expandEntityReferences to * true when creating the TreeWalker. To produce a view of the document * that has entity reference nodes but no entity expansion, use the * whatToShow flags to show the entity reference node and set * expandEntityReferences to false * * @param root The root node of the DOM tree * @param whatToShow This attribute determines which node types are presented via the tree-walker. * @param filter The filter used to screen nodes * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are * visible to the tree-walker. If false, they will be skipped over. */ DOM_TreeWalker createTreeWalker(DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion); /** * Creates a XMLDecl type Node . Non-Standard (an extension to xerces) * * XMLDecl Nodes are created to get version, encoding and standalone information in a document tree * * This node if created gets attached to a document object or an entity node. There can be no child * to this type of node. * * @param version The version data of the document. Currently possible value is 1.0 * @param encoding The encoding type specified in the document * @param standalone The information whether the document is standalone or not */ DOM_XMLDecl createXMLDecl(const DOMString& version, const DOMString& encoding, const DOMString& standalone); /** * To create the range consisting of boundary-points and offset of the * selected contents * * @return The initial state of the Range such that both the boundary-points * are positioned at the beginning of the corresponding DOM_DOcument, before * any content. The range returned can only be used to select content * associated with this document, or with documentFragments and Attrs for * which this document is the ownerdocument */ DOM_Range createRange(); //@} /** @name Getter functions */ //@{ /** * Get Document Type Declaration (see DOM_DocumentType) associated * with this document. * * For documents without * a document type declaration this returns null reference object. The DOM Level * 1 does not support editing the Document Type Declaration, therefore * docType cannot be altered in any way. */ DOM_DocumentType getDoctype() const; /** * Return the DOMImplementation object that handles this document. */ DOM_DOMImplementation &getImplementation() const; /** * Return a reference to the root element of the document. */ DOM_Element getDocumentElement() const; /** * Returns a DOM_NodeList of all the elements with a * given tag name. The returned node list is "live", in that changes * to the document tree made after a nodelist was initially * returned will be immediately reflected in the node list. * * The elements in the node list are ordered in the same order in which they * would be encountered in a * preorder traversal of the Document tree. * @param tagname The name of the tag to match on. The special value "*" * matches all tags. * @return A reference to a NodeList containing all the matched * Elements. */ DOM_NodeList getElementsByTagName(const DOMString &tagname) const; //@} /** @name Functions introduced in DOM Level 2. */ //@{ /** * Imports a node from another document to this document. * The returned node has no parent (parentNode is * null). The source node is not altered or removed from the * original document; this method creates a new copy of the source * node.
For all nodes, importing a node creates a node object owned by * the importing document, with attribute values identical to the source * node's nodeName and nodeType, plus the * attributes related to namespaces (prefix and namespaces URI). * * @param importedNode The node to import. * @param deep If true, recursively import the subtree under the * specified node; if false, import only the node itself, * as explained above. This does not apply to DOM_Attr, * DOM_EntityReference, and DOM_Notation nodes. * @return The imported node that belongs to this DOM_Document. * @exception DOMException * NOT_SUPPORTED_ERR: Raised if the type of node being imported is * not supported. */ DOM_Node importNode(const DOM_Node &importedNode, bool deep); /** * Creates an element of the given qualified name and * namespace URI. * * @param namespaceURI The namespace URI of * the element to create. * @param qualifiedName The qualified name * of the element type to instantiate. * @return A new DOM_Element object. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains * an illegal character. *
* NAMESPACE_ERR: Raised if the qualifiedName is * malformed, if the qualifiedName has a prefix and the * namespaceURI is null or an empty string, * or if the qualifiedName has a prefix that is "xml" and * the namespaceURI is different from * "http://www.w3.org/XML/1998/namespace". */ DOM_Element createElementNS(const DOMString &namespaceURI, const DOMString &qualifiedName); /** * Creates an attribute of the given qualified name and namespace * URI. * * @param namespaceURI The namespace URI of * the attribute to create. * @param qualifiedName The qualified name * of the attribute to instantiate. * @return A new DOM_Attr object. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains * an illegal character. *
* NAMESPACE_ERR: Raised if the qualifiedName is * malformed, if the qualifiedName has a prefix and the * namespaceURI is null or an empty string, * if the qualifiedName has a prefix that is "xml" and the * namespaceURI is different from * "http://www.w3.org/XML/1998/namespace", if the * qualifiedName has a prefix that is "xmlns" and the * namespaceURI is different from * "http://www.w3.org/2000/xmlns/", or if the * qualifiedName is "xmlns" and the * namespaceURI is different from * "http://www.w3.org/2000/xmlns/". */ DOM_Attr createAttributeNS(const DOMString &namespaceURI, const DOMString &qualifiedName); /** * Returns a DOM_NodeList of all the DOM_Elements * with a given local name and * namespace URI in the order in which they would be encountered in a * preorder traversal of the DOM_Document tree. * * @param namespaceURI The namespace URI of * the elements to match on. The special value "*" matches all * namespaces. * @param localName The local name of the * elements to match on. The special value "*" matches all local names. * @return A new DOM_NodeList object containing all the matched * DOM_Elements. */ DOM_NodeList getElementsByTagNameNS(const DOMString &namespaceURI, const DOMString &localName) const; /** * Returns the DOM_Element whose ID is given by elementId. * If no such element exists, returns null. * Behavior is not defined if more than one element has this ID. *

Note: The DOM implementation must have information that says * which attributes are of type ID. Attributes with the name "ID" are not of * type ID unless so defined. Implementations that do not know whether * attributes are of type ID or not are expected to return * null.

* * @param elementId The unique id value for an element. * @return The matching element. */ DOM_Element getElementById(const DOMString &elementId); /** * Sets whether the DOM implementation performs error checking * upon operations. Turning off error checking only affects * the following DOM checks: * *

* Turning off error checking does not turn off the * following checks: *

*/ void setErrorChecking(bool check); /** * Returns true if the DOM implementation performs error checking. */ bool getErrorChecking(); //@} protected: DOM_Document (DocumentImpl *impl); friend class DOM_Node; friend class DocumentImpl; friend class NodeIteratorImpl; friend class DOM_DOMImplementation; }; XERCES_CPP_NAMESPACE_END #endif