
	API Docs for SAX and DOM

Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

DOM_Document Class Reference

Class to refer to XML Document nodes in the DOM. More...

#include <DOM_Document.hpp>

Inheritance diagram for DOM_Document

[legend]Collaboration diagram for DOM_Document:

[legend]List of all members.

Factory methods to create new nodes for the Document
DOM_Entity	createEntity (const DOMString &name)
	Create a new entity. More...
DOM_Element	createElement (const DOMString &tagName)
	Creates an element of the type specified. More...
DOM_Element	createElement (const XMLCh *tagName)
	Creates an element of the type specified. More...
DOM_DocumentFragment	createDocumentFragment ()
	Creates an empty DocumentFragment object. More...
DOM_Text	createTextNode (const DOMString &data)
	Creates a Text node given the specified string. More...
DOM_Comment	createComment (const DOMString &data)
	Creates a Comment node given the specified string. More...
DOM_CDATASection	createCDATASection (const DOMString &data)
	Creates a CDATASection node whose value is the specified string. More...
DOM_DocumentType	createDocumentType (const DOMString &name)
	Create a DocumentType node. More...
DOM_Notation	createNotation (const DOMString &name)
	Create a Notation. More...
DOM_ProcessingInstruction	createProcessingInstruction (const DOMString &target, const DOMString &data)
	Creates a ProcessingInstruction node given the specified name and data strings. More...
DOM_Attr	createAttribute (const DOMString &name)
	Creates an Attr of the given name. More...
DOM_EntityReference	createEntityReference (const DOMString &name)
	Creates an EntityReference object. More...
DOM_NodeIterator	createNodeIterator (DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion)
	Creates a NodeIterator object. More...
DOM_TreeWalker	createTreeWalker (DOM_Node root, unsigned long whatToShow, DOM_NodeFilter* filter, bool entityReferenceExpansion)
	Creates a TreeWalker object. More...
DOM_XMLDecl	createXMLDecl (const DOMString& version, const DOMString& encoding, const DOMString& standalone)
	Creates a XMLDecl type Node . More...
DOM_Range	createRange ()
	To create the range consisting of boundary-points and offset of the selected contents. More...
DOM_Document	createDocument ()
	Create a new empty document. More...
Public Methods
Constructors and assignment operators
	DOM_Document ()
	The default constructor for DOM_Document creates a null DOM_Document object that refers to no document. More...
	DOM_Document (const DOM_Document &other)
	Copy constructor. More...
DOM_Document&	operator= (const DOM_Document &other)
	Assignment operator. More...
DOM_Document&	operator= (const DOM_NullPtr *val)
	Assignment operator. More...
Destructor
	~DOM_Document ()
	Destructor. More...
Getter functions
DOM_DocumentType	getDoctype () const
	Get Document Type Declaration (see `DOM_DocumentType`) associated with this document. More...
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. More...
Functions introduced in DOM Level 2.
DOM_Node	importNode (const DOM_Node &importedNode, bool deep)
	Imports a node from another document to this document. More...
DOM_Element	createElementNS (const DOMString &namespaceURI, const DOMString &qualifiedName)
	Creates an element of the given qualified name and namespace URI. More...
DOM_Attr	createAttributeNS (const DOMString &namespaceURI, const DOMString &qualifiedName)
	Creates an attribute of the given qualified name and namespace URI. More...
DOM_NodeList	getElementsByTagNameNS (const DOMString &namespaceURI, const DOMString &localName) const
	Returns a `DOM_NodeList` of all the `DOM_Element`s 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.* More...
DOM_Element	getElementById (const DOMString &elementId)
	Returns the `DOM_Element` whose ID is given by `elementId`. More...
void	setErrorChecking (bool check)
	Sets whether the DOM implementation performs error checking upon operations. More...
bool	getErrorChecking ()
	Returns true if the DOM implementation performs error checking.
Protected Methods
	DOM_Document (DocumentImpl *impl)
Friends
class	DOM_Node
class	DocumentImpl
class	NodeIteratorImpl
class	DOM_DOMImplementation

Detailed Description

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.

Constructor & Destructor Documentation

DOM_Document::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::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::~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.

DOM_Document::DOM_Document ( DocumentImpl * impl ) [protected]

Member Function Documentation

DOM_Attr DOM_Document::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.
Parameters:

name The name of the attribute.

Returns:
A new DOM_Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null.
Exceptions:

DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

DOM_Attr DOM_Document::createAttributeNS ( const DOMString & namespaceURI,

const DOMString & qualifiedName )

Creates an attribute of the given qualified name and namespace URI.

"Experimental - subject to change"
Parameters:

namespaceURI The namespace URI of the attribute to create.

qualifiedName The qualified name of the attribute to instantiate.

Returns:
A new DOM_Attr object.
Exceptions:

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_CDATASection DOM_Document::createCDATASection ( const DOMString & data )

Creates a CDATASection node whose value is the specified string.

Parameters:

data The data for the DOM_CDATASection contents.

Returns:
A DOM_CDATASection object.
Exceptions:

DOMException NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

DOM_Comment DOM_Document::createComment ( const DOMString & data )

Creates a Comment node given the specified string.

Parameters:

data The data for the comment.

Returns:
A DOM_Comment that references the newly created comment node.

DOM_Document DOM_Document::createDocument ( ) [static]

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_DocumentFragment DOM_Document::createDocumentFragment ( )

Creates an empty DocumentFragment object.

Returns:
A DOM_DocumentFragment that references the newly created document fragment.

DOM_DocumentType DOM_Document::createDocumentType ( const DOMString & name )

Create a DocumentType node.
Non-standard extension.

Returns:
A DOM_DocumentType that references the newly created DocumentType node.

DOM_Element DOM_Document::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.
Parameters:

tagName The name of the element type to instantiate, as a null-terminated unicode string.

Returns:
A new DOM_Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.

DOM_Element DOM_Document::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.
Parameters:

tagName The name of the element type to instantiate.

Returns:
A DOM_Element that reference the new element.
Exceptions:

DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

DOM_Element DOM_Document::createElementNS ( const DOMString & namespaceURI,

const DOMString & qualifiedName )

Creates an element of the given qualified name and namespace URI.

"Experimental - subject to change"
Parameters:

namespaceURI The namespace URI of the element to create.

qualifiedName The qualified name of the element type to instantiate.

Returns:
A new DOM_Element object.
Exceptions:

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_Entity DOM_Document::createEntity ( const DOMString & name )

Create a new entity.
Non-standard extension.
Parameters:

name The name of the entity to instantiate

DOM_EntityReference DOM_Document::createEntityReference ( const DOMString & name )

Creates an EntityReference object.

Parameters:

name The name of the entity to reference.

Returns:
A DOM_EntityReference that references the newly created EntityReference node.
Exceptions:

DOMException INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

DOM_NodeIterator DOM_Document::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_Notation DOM_Document::createNotation ( const DOMString & name )

Create a Notation.
Non-standard extension.
Parameters:

name The name of the notation to instantiate

Returns:
A DOM_Notation that references the newly created Notation node.

DOM_ProcessingInstruction DOM_Document::createProcessingInstruction ( const DOMString & target,

const DOMString & data )

Creates a ProcessingInstruction node given the specified name and data strings.

Parameters:

target The target part of the processing instruction.

data The data for the node.

Returns:
A DOM_ProcessingInstruction that references the newly created PI node.
Exceptions:

DOMException INVALID_CHARACTER_ERR: Raised if an illegal character is specified.

DOM_Range DOM_Document::createRange ( )

To create the range consisting of boundary-points and offset of the selected contents.

Returns:
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_Text DOM_Document::createTextNode ( const DOMString & data )

Creates a Text node given the specified string.

Parameters:

data The data for the node.

Returns:
A DOM_Text object that references the newly created text node.

DOM_TreeWalker DOM_Document::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.

DOM_XMLDecl DOM_Document::createXMLDecl ( const DOMString & version,

const DOMString & encoding,

const DOMString & standalone )

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.

"Experimental - subject to change"
Parameters:

version The version data of the document. Currently possible value is 1.0

encoding The encoding type specified in the document

standalone The information whether the document is standalone or not

DOM_DocumentType DOM_Document::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_Element DOM_Document::getDocumentElement ( ) const

Return a reference to the root element of the document.

DOM_Element DOM_Document::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"
Parameters:

elementId The unique id value for an element.

Returns:
The matching element.

DOM_NodeList DOM_Document::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.
Parameters:

tagname The name of the tag to match on. The special value "*" matches all tags.

Returns:
A reference to a NodeList containing all the matched Elements.

DOM_NodeList DOM_Document::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"
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.

Returns:
A new DOM_NodeList object containing all the matched DOM_Elements.

bool DOM_Document::getErrorChecking ( )

Returns true if the DOM implementation performs error checking.

DOM_DOMImplementation & DOM_Document::getImplementation ( ) const

Return the DOMImplementation object that handles this document.

DOM_Node DOM_Document::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"
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.

Returns:
The imported node that belongs to this DOM_Document.
Exceptions:

DOMException NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

DOM_Document & 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.

Reimplemented from DOM_Node.

DOM_Document & DOM_Document::operator= ( const DOM_Document & other )

Assignment operator.

Parameters:

other The object to be copied

void DOM_Document::setErrorChecking ( bool check )

Sets whether the DOM implementation performs error checking upon operations.
Turning off error checking only affects the following DOM checks:

Checking strings to make sure that all characters are legal XML characters
Hierarchy checking such as allowed children, checks for cycles, etc.

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

Read only checks
Checks related to DOM events

Friends And Related Function Documentation

class DOM_DOMImplementation [friend]

class DOM_Node [friend]

class DocumentImpl [friend]

Reimplemented from DOM_Node.

class NodeIteratorImpl [friend]

Reimplemented from DOM_Node.

The documentation for this class was generated from the following file:

DOM_Document.hpp

DOM_Document Class Reference

Factory methods to create new nodes for the Document

Public Methods

Protected Methods

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation