Table 15-11 summarizes the methods of available through DocumentRef interface.
Table 15-11 Summary of DocumentRef Methods; Dom Package
Function | Summary |
---|---|
DocumentRef
|
Constructor. |
createAttribute
|
Create an attribute node. |
createAttributeNS
|
Create an attribute node with namespace information. |
createCDATASection
|
Create a CDATA node. |
createComment
|
Create a comment node. |
createDocumentFragment
|
Create a document fragment. |
createElement
|
Create an element node. |
createElementNS
|
Create an element node with names pace information. |
createEntityReference
|
Create an entity reference node. |
createProcessingInstruction
|
Create a ProcessingInstruction node
|
createTextNode
|
Create a text node. |
getDoctype
|
Get DTD associated with the document. |
getDocumentElement
|
Get top-level element of this document. |
getElementById
|
Get an element given its ID. |
getElementsByTagName
|
Get elements in the document by tag name. |
getElementsByTagNameNS
|
Get elements in the document by tag name (namespace aware version). |
getImplementation
|
Get DOMImplementation object associated with the document.
|
importNode
|
Import a node from another DOM.s |
~DocumentRef
|
Public default destructor. |
This is a constructor.
Syntax | Description |
---|---|
DocumentRef( const NodeRef< Node>& nref, Node* nptr); |
Default constructor. |
DocumentRef( const DocumentRef< Node>& nref); |
Copy constructor. |
Parameter | Description |
---|---|
nref |
reference to provide the context |
nptr |
referenced node |
(DocumentRef)
Node
reference object
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);
Parameter | Description |
---|---|
name |
name |
(Node*)
New attribute node
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);
Parameter | Description |
---|---|
namespaceURI |
namespace URI |
qualifiedName |
qualified name |
(Node*)
New attribute node
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);
Parameter | Description |
---|---|
data |
data for new node |
(Node*)
New CDATA node
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);
Parameter | Description |
---|---|
data |
data for new node |
(Node*)
New comment node
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
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);
Parameter | Description |
---|---|
tagname |
tag name |
(Node*)
New element node
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);
Parameter | Description |
---|---|
namespaceURI |
namespace URI |
qualifiedName |
qualified name |
(Node*)
New element node
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);
Parameter | Description |
---|---|
name |
name |
(Node*)
New entity reference node
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);
Parameter | Description |
---|---|
target |
target |
data |
data for new node |
(Node*)
New PI node
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);
Parameter | Description |
---|---|
data |
data for new text node |
(Node*)
new text node
Returns the DTD node associated with this document. After this call, a DocumentType
Ref 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
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
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);
Parameter | Description |
---|---|
elementId |
element id |
(Node*)
Element
node
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;
Parameter | Description |
---|---|
tagname |
tag name |
(NodeList< Node>*)
List of nodes
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);
Parameter | Description |
---|---|
namespaceURI |
|
localName |
|
(NodeList< Node>*)
List of nodes
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
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);
Parameter | Description |
---|---|
importedNode |
|
deep |
|
(Node*)
New imported node
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();