class DOM_Document : public DOM_Node

Class to refer to XML Document nodes in the DOM

Inheritance:


Public

Constructors and assignment operators
DOM_Document ()
The default constructor for DOM_Document creates a null DOM_Document object that refers to no document
DOM_Document (const DOM_Document &other)
Copy constructor
DOM_Document& operator = (const DOM_Document &other)
Assignment operator
DOM_Document& operator = (const DOM_NullPtr *val)
Assignment operator
Destructor
~DOM_Document ()
Destructor
Factory methods to create new nodes for the Document
static DOM_Document createDocument ()
Create a new empty document
DOM_Entity createEntity (const DOMString &name)
Create a new entity
DOM_Element createElement (const DOMString &tagName)
Creates an element of the type specified
DOM_Element createElement (const XMLCh *tagName)
Creates an element of the type specified
DOM_DocumentFragment createDocumentFragment ()
Creates an empty DocumentFragment object
DOM_Text createTextNode (const DOMString &data)
Creates a Text node given the specified string
DOM_Comment createComment (const DOMString &data)
Creates a Comment node given the specified string
DOM_CDATASection createCDATASection (const DOMString &data)
Creates a CDATASection node whose value is the specified string
DOM_DocumentType createDocumentType (const DOMString &name)
Create a DocumentType node
DOM_Notation createNotation (const DOMString &name)
Create a Notation
DOM_ProcessingInstruction createProcessingInstruction (const DOMString &target, const DOMString &data)
Creates a ProcessingInstruction node given the specified name and data strings
DOM_Attr createAttribute (const DOMString &name)
Creates an Attr of the given name
DOM_EntityReference createEntityReference (const DOMString &name)
Creates an EntityReference object
DOM_NodeIterator createNodeIterator (DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion)
Creates a NodeIterator object
DOM_TreeWalker createTreeWalker (DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion)
Creates a TreeWalker object
Functions introduced in DOM Level 2.
DOM_Node importNode (const DOM_Node &importedNode, bool deep)
Imports a node from another document to this document
DOM_Element createElementNS (const DOMString &namespaceURI, const DOMString &qualifiedName)
Creates an element of the given qualified name and namespace URI
DOM_Attr createAttributeNS (const DOMString &namespaceURI, const DOMString &qualifiedName)
Creates an attribute of the given qualified name and namespace URI
DOM_NodeList getElementsByTagNameNS (const DOMString &namespaceURI, const DOMString &localName) const
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
DOM_Element getElementById (const DOMString &elementId)
Returns the DOM_Element whose ID is given by elementId
Getter functions
DOM_DocumentType getDoctype () const
Get Document Type Declaration (see DOM_DocumentType) associated with this document
DOM_DOMImplementation& getImplementation () const
Return the DOMImplementation object that handles this document
DOM_Element getDocumentElement () const
Return a reference to the root element of the document
DOM_NodeList getElementsByTagName (const DOMString &tagname) const
Returns a DOM_NodeList of all the elements with a given tag name

Inherited from DOM_Node:

Public

Cloning function.

DOM_Node cloneNode(bool deep) const
Returns a duplicate of this node

Destructor.

~DOM_Node()
Destructor for DOM_Node

Equality and Inequality operators.

bool operator == (const DOM_Node & other) const
The equality operator
bool operator == (const DOM_NullPtr *other) const
Compare with a pointer
bool operator != (const DOM_Node & other) const
The inequality operator
bool operator != (const DOM_NullPtr * other) const
Compare with a pointer

Functions to modify the DOM Node.

DOM_Node insertBefore(const DOM_Node &newChild, const DOM_Node &refChild)
Inserts the node newChild before the existing child node refChild
DOM_Node replaceChild(const DOM_Node &newChild, const DOM_Node &oldChild)
Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node
DOM_Node removeChild(const DOM_Node &oldChild)
Removes the child node indicated by oldChild from the list of children, and returns it
DOM_Node appendChild(const DOM_Node &newChild)
Adds the node newChild to the end of the list of children of this node

Get functions.

DOMString getNodeName() const
The name of this node, depending on its type; see the table above
DOMString getNodeValue() const
Gets the value of this node, depending on its type
short getNodeType() const
An enum value representing the type of the underlying object
DOM_Node getParentNode() const
Gets the parent of this node
DOM_NodeList getChildNodes() const
Gets a NodeList that contains all children of this node
DOM_Node getFirstChild() const
Gets the first child of this node
DOM_Node getLastChild() const
Gets the last child of this node
DOM_Node getPreviousSibling() const
Gets the node immediately preceding this node
DOM_Node getNextSibling() const
Gets the node immediately following this node
DOM_NamedNodeMap getAttributes() const
Gets a NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise
DOM_Document getOwnerDocument() const
Gets the DOM_Document object associated with this node
void* getUserData() const
Return the user data pointer

Query functions.

bool hasChildNodes() const
This is a convenience method to allow easy determination of whether a node has any children
bool isNull() const
Test whether this node is null

Set functions.

void setNodeValue(const DOMString &nodeValue)
Sets the value of the node
void setUserData(void *p)
Set the user data for a node

Documentation

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.

Constructors and assignment operators

DOM_Document()
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(const DOM_Document &other)
Copy constructor. Creates a new DOM_Document that refers to the same underlying actual document as the original.
Parameters:
other - The object to be copied

DOM_Document& operator = (const DOM_Document &other)
Assignment operator
Parameters:
other - The object to be copied

DOM_Document& operator = (const DOM_NullPtr *val)
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.
Parameters:
val. - Only a value of 0, or null, is allowed.

Destructor

~DOM_Document()
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.

Factory methods to create new nodes for the Document

static DOM_Document createDocument()
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.

Returns:
A new DOM_Document, which may then be populated using the DOM API calls.

DOM_Entity createEntity(const DOMString &name)
Create a new entity. Non-standard extension.
Parameters:
name - The name of the entity to instantiate

DOM_Element createElement(const DOMString &tagName)
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.
Throws:
DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
Returns:
A DOM_Element that reference the new element.
Parameters:
tagName - The name of the element type to instantiate.

DOM_Element createElement(const XMLCh *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.
Returns:
A new DOM_Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.
Parameters:
tagName - The name of the element type to instantiate, as a null-terminated unicode string.

DOM_DocumentFragment createDocumentFragment()
Creates an empty DocumentFragment object.
Returns:
A DOM_DocumentFragment that references the newly created document fragment.

DOM_Text createTextNode(const DOMString &data)
Creates a Text node given the specified string.
Returns:
A DOM_Text object that references the newly created text node.
Parameters:
data - The data for the node.

DOM_Comment createComment(const DOMString &data)
Creates a Comment node given the specified string.
Returns:
A DOM_Comment that references the newly created comment node.
Parameters:
data - The data for the comment.

DOM_CDATASection createCDATASection(const DOMString &data)
Creates a CDATASection node whose value is the specified string.
Throws:
DOMException NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
Returns:
A DOM_CDATASection object.
Parameters:
data - The data for the DOM_CDATASection contents.

DOM_DocumentType createDocumentType(const DOMString &name)
Create a DocumentType node. Non-standard extension.
Returns:
A DOM_DocumentType that references the newly created DocumentType node.

DOM_Notation createNotation(const DOMString &name)
Create a Notation. Non-standard extension.
Returns:
A DOM_Notation that references the newly created Notation node.
Parameters:
name - The name of the notation to instantiate

DOM_ProcessingInstruction createProcessingInstruction(const DOMString &target, const DOMString &data)
Creates a ProcessingInstruction node given the specified name and data strings.
Throws:
DOMException INVALID_CHARACTER_ERR: Raised if an illegal character is specified.
Returns:
A DOM_ProcessingInstruction that references the newly created PI node.
Parameters:
target - The target part of the processing instruction.
data - The data for the node.

DOM_Attr createAttribute(const DOMString &name)
Creates an Attr of the given name. Note that the Attr instance can then be attached to an Element using the DOMElement::setAttribute() method.
Throws:
DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
Returns:
A new DOM_Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null.
Parameters:
name - The name of the attribute.

DOM_EntityReference createEntityReference(const DOMString &name)
Creates an EntityReference object.
Throws:
DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
Returns:
A DOM_EntityReference that references the newly created EntityReference node.
Parameters:
name - The name of the entity to reference.

DOM_NodeIterator createNodeIterator(DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion)
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.

"Experimental - subject to change"

Parameters:
root - The root node of the DOM tree
whatToShow - This attribute determines which node types are presented via the iterator.
filter - The filter used to screen nodes
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_TreeWalker createTreeWalker(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

"Experimental - subject to change"

Parameters:
root - The root node of the DOM tree
whatToShow - This attribute determines which node types are presented via the tree-walker.
filter - The filter used to screen nodes
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.

Getter functions

DOM_DocumentType getDoctype() const
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_DOMImplementation& getImplementation() const
Return the DOMImplementation object that handles this document

DOM_Element getDocumentElement() const
Return a reference to the root element of the document

DOM_NodeList getElementsByTagName(const DOMString &tagname) 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.
Returns:
A reference to a NodeList containing all the matched Elements.
Parameters:
tagname - The name of the tag to match on. The special value "*" matches all tags.

Functions introduced in DOM Level 2.

DOM_Node importNode(const DOM_Node &importedNode, bool deep)
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).

"Experimental - subject to change"

Throws:
DOMException NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.
Returns:
The imported node that belongs to this DOM_Document.
Parameters:
importedNode - The node to import.
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.

DOM_Element createElementNS(const DOMString &namespaceURI, const DOMString &qualifiedName)
Creates an element of the given qualified name and namespace URI.

"Experimental - subject to change"

Throws:
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:
Returns:
A new DOM_Element object.
Parameters:
namespaceURI - The namespace URI of the element to create.
qualifiedName - The qualified name of the element type to instantiate.

DOM_Attr createAttributeNS(const DOMString &namespaceURI, const DOMString &qualifiedName)
Creates an attribute of the given qualified name and namespace URI.

"Experimental - subject to change"

Throws:
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: * qualifiedName has a prefix that is "xmlns" and the namespaceURI is different from "http: * qualifiedName is "xmlns" and the namespaceURI is different from "http:
Returns:
A new DOM_Attr object.
Parameters:
namespaceURI - The namespace URI of the attribute to create.
qualifiedName - The qualified name of the attribute to instantiate.

DOM_NodeList getElementsByTagNameNS(const DOMString &namespaceURI, const DOMString &localName) const
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.

"Experimental - subject to change"

Returns:
A new DOM_NodeList object containing all the matched DOM_Elements.
Parameters:
namespaceURI - The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName - The local name of the elements to match on. The special value "*" matches all local names.

DOM_Element getElementById(const DOMString &elementId)
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.

"Experimental - subject to change"

Returns:
The matching element.
Parameters:
elementId - The unique id value for an element.


This class has no child classes.

alphabetic index hierarchy of classes


Xerces-C XML Parser for C++ Version 1.1
Copyright © 2000 The Apache Software Foundation. All Rights Reserved.

generated by doc++