Skip Headers

Oracle® XML API Reference
10g Release 1 (10.1)
Part No. B10789-01
  Go To Table Of Contents
Contents

Previous Next  

DocumentRef Interface

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.


DocumentRef

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


Returns

(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.


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

Parameter Description
name
name


Returns

(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.


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

Parameter Description
namespaceURI
namespace URI
qualifiedName
qualified name


Returns

(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.


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

Parameter Description
data
data for new node


Returns

(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.


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

Parameter Description
data
data for new node


Returns

(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".


Syntax
Node* createDocumentFragment()
throw (DOMException);


Returns

(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.


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

Parameter Description
tagname
tag name


Returns

(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.


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

Parameter Description
namespaceURI
namespace URI
qualifiedName
qualified name


Returns

(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.


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

Parameter Description
name
name


Returns

(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.


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

Parameter Description
target
target
data
data for new node


Returns

(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.


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

Parameter Description
data
data for new text node


Returns

(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.


Syntax
Node* getDoctype() const;


Returns

(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.


Syntax
Node* getDocumentElement() const;


Returns

(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.


Syntax
Node* getElementById(
   oratext* elementId);

Parameter Description
elementId
element id


Returns

(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.


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

Parameter Description
tagname
tag name


Returns

(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.


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

Parameter Description
namespaceURI

localName



Returns

(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.


Syntax
DOMImplementation< Node>* getImplementation() const;


Returns

(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.


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

Parameter Description
importedNode

deep



Returns

(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.


Syntax
~DocumentRef();