DocumentRef Interface

Table 15-11 summarizes the methods of available through DocumentRef interface.

DocumentRef

This is a constructor.

DocumentRef(
   const NodeRef< Node>& nref,
   Node* nptr);

DocumentRef(
   const DocumentRef< Node>& nref);

nref

nptr

(DocumentRef) Node reference object

createAttribute

Creates an attribute node with the given name. This is the non-namespace aware function. The new attribute will have NULL namespace URI and prefix, and its local name will be the same as its name, even if the name specified is a qualified name. The new node is an orphan with no parent. The name is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Node* createAttribute( 
   oratext* name) 
throw (DOMException);

name

(Node*) New attribute node

createAttributeNS

Creates an attribute node with the given namespace URI and qualified name. The new node is an orphan with no parent. The URI and qualified name are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Node* createAttributeNS( 
   oratext* namespaceURI,
   oratext* qualifiedName)
   throw (DOMException);

namespaceURI

qualifiedName

(Node*) New attribute node

createCDATASection

Creates a CDATA section node with the given initial data (which should be in the data encoding). A CDATA section is considered verbatim and is never parsed; it will not be joined with adjacent text nodes by the normalize operation. The initial data may be NULL, if provided; it is not verified, converted, or checked. The name of a CDATA node is always "#cdata-section". The new node is an orphan with no parent. The CDATA is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Node* createCDATASection(
   oratext* data)
throw (DOMException);

data

(Node*) New CDATA node

createComment

Creates a comment node with the given initial data (which must be in the data encoding). The data may be NULL, if provided; it is not verified, converted, or checked. The name of the comment node is always "#comment". The new node is an orphan with no parent. The comment data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Node* createComment( 
   oratext* data)
throw (DOMException);

data

(Node*) New comment node

createDocumentFragment

Creates an empty Document Fragment node. A document fragment is treated specially when it is inserted into a DOM tree: the children of the fragment are inserted in order instead of the fragment node itself. After insertion, the fragment node will still exist, but have no children. The name of a fragment node is always "#document-fragment".

Node* createDocumentFragment()
throw (DOMException);

(Node*) new document fragment node

createElement

Creates an element node with the given tag name (which should be in the data encoding). The new node is an orphan with no parent. The tagname is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Note that the tag name of an element is case sensitive. This is the non-namespace aware function: the new node will have NULL namespace URI and prefix, and its local name will be the same as its tag name, even if the tag name specified is a qualified name.

Node* createElement(
   oratext* tagname)
throw (DOMException);

tagname

(Node*) New element node

createElementNS

Creates an element with the given namespace URI and qualified name. The new node is an orphan with no parent. The URI and qualified name are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Note that element names are case sensitive, and the qualified name is required though the URI may be NULL. The qualified name will be split into prefix and local parts. The tagName will be the full qualified name.

Node* createElementNS(
   oratext* namespaceURI,
   oratext* qualifiedName)
throw (DOMException);

namespaceURI

qualifiedName

(Node*) New element node

createEntityReference

Creates an entity reference node; the name (which should be in the data encoding) is the name of the entity to be referenced. The named entity does not have to exist. The name is not verified, converted, or checked. The new node is an orphan with no parent. The entity reference name is not copied; its pointer is just stored. The user is responsible for persistence and freeing of that data.

Note that entity reference nodes are never generated by the parser; instead, entity references are expanded as encountered. On output, an entity reference node will turn into a "&name;" style reference.

Node* createEntityReference(
   oratext* name)
throw (DOMException);

name

(Node*) New entity reference node

createProcessingInstruction

Creates a processing instruction node with the given target and data (which should be in the data encoding). The data may be NULL, but the target is required and cannot be changed. The target and data are not verified, converted, or checked. The name of the node is the same as the target. The new node is an orphan with no parent. The target and data are not copied; their pointers are just stored. The user is responsible for persistence and freeing of that data.

Node* createProcessingInstruction(
   oratext* target,
   oratext* data)
throw (DOMException);

target

data

(Node*) New PI node

createTextNode

Creates a text node with the given initial data (which must be non-NULL and in the data encoding). The data may be NULL; if provided, it is not verified, converted, checked, or parsed (entities will not be expanded). The name of the node is always "#text". The new node is an orphan with no parent. The text data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Node* createTextNode(
   oratext* data)
throw (DOMException);

data

(Node*) new text node

getDoctype

Returns the DTD node associated with this document. After this call, a DocumentTypeRef object needs to be created with an appropriate constructor in order to call its member functions. The DTD tree cannot be edited.

Node* getDoctype() const;

(Node*) DTD node

getDocumentElement

Returns the root element (node) of the DOM tree. Each document has only one uppermost Element node, called the root element. If there is no root element, NULL is returned. This can happen when the document tree is being constructed.

Node* getDocumentElement() const;

(Node*) Root element

getElementById

Returns the element node which has the given ID. Throws NOT_FOUND_ERR if no element is found. The given ID should be in the data encoding or it might not match.

Note that attributes named "ID" are not automatically of type ID; ID attributes (which can have any name) must be declared as type ID in the DTD or XML schema associated with the document.

Node* getElementById(
   oratext* elementId);

elementId

(Node*)Element node

getElementsByTagName

Returns a list of all elements in the document with a given tag name, in document order (the order in which they would be encountered in a preorder traversal of the tree). The list should be freed by the user when it is no longer needed. The list is not live, it is a snapshot. That is, if a new node which matched the tag name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive, and should be in the data encoding or a mismatch might occur.

This function is not namespace aware; the full tag names are compared. If two qualified names with two different prefixes both of which map to the same URI are compared, the comparison will fail.

NodeList< Node>* getElementsByTagName( 
   oratext* tagname) const;

tagname

(NodeList< Node>*) List of nodes

getElementsByTagNameNS

Returns a list of all elements in the document with a given namespace URI and local name, in document order (the order in which they would be encountered in a preorder traversal of the tree). The list should be freed by the user when it is no longer needed. The list is not live, it is a snapshot. That is, if a new node which matches the URI and local name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

The URI and local name should be in the data encoding. The special name "*" matches all local names; a NULL local name matches nothing. Namespace URIs must always match, however, no wildcard is allowed. Note that comparisons are case sensitive.

NodeList< Node>* getElementsByTagNameNS(
   oratext* namespaceURI,
   oratext* localName);

namespaceURI

localName

(NodeList< Node>*) List of nodes

getImplementation

Returns DOMImplementation object that was used to create this document. When the DOMImplementation object is destructed, all document trees associated with it are also destructed.

DOMImplementation< Node>* getImplementation() const;

(DOMImplementation) DOMImplementation reference object

importNode

Imports a node from one Document to another. The new node is an orphan and has no parent. The original node is not modified in any way or removed from its document; instead, a new node is created with copies of all the original node's qualified name, prefix, namespace URI, and local name.

The deep controls whether the children of the node are recursively imported. If FALSE, only the node itself is imported, and it will have no children. If TRUE, all descendents of the node will be imported as well, and an entire new subtree created. Elements will have only their specified attributes imported; non-specified (default) attributes are omitted. New default attributes (for the destination document) are then added. Document and DocumentType nodes cannot be imported.

Node* importNode( 
   NodeRef< Node>& importedNode,
   boolean deep) const
throw (DOMException);

importedNode

deep

(Node*) New imported node

~DocumentRef

This is the default destructor. It cleans the reference to the node. If the document node is marked for deletion, the destructor deletes the node and the tree under it. It is always deep deletion in the case of a document node. The destructor can be called by the environment or by the user directly.

~DocumentRef();