Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## 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 `DocumentType`Ref 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();