Skip Headers

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

## NodeRef Interface

Table 15-21 summarizes the methods of available through `NodeRef` interface.

Table 15-21 Summary of NodeRef Methods; Dom Package

Function | Summary
--- | ---
NodeRef | Constructor.
appendChild | Append new child to node's list of children.
cloneNode | Clone this node.
getAttributes | Get attributes of this node.
getChildNodes | Get children of this node.
getFirstChild | Get the first child node of this node.
getLastChild | Get the last child node of this node.
getLocalName | Get local name of this node.
getNamespaceURI | Get namespace URI of this node as a `NULL`-terminated string.
getNextSibling | Get the next sibling node of this node.
getNoMod | Tests if no modifications are allowed for this node.
getNodeName | Get node's name as `NULL`-terminated string.
getNodeType | Get DOMNodeType of the node.
getNodeValue | Get node's value as `NULL`-terminated string.
getOwnerDocument | Get the owner document of this node.
getParentNode | Get parent node of this node.
getPrefix | Get namespace prefix of this node.
getPreviousSibling | Get the previous sibling node of this node.
hasAttributes | Tests if this node has attributes.
hasChildNodes | Test if this node has children.
insertBefore | Insert new child into node's list of children.
isSupported | Tests if specified feature is supported by the implementation.
markToDelete | Sets the mark to delete the referenced node.
normalize | Merge adjacent text nodes.
removeChild | Remove an existing child node.
replaceChild | Replace an existing child of a node.
resetNode | Reset NodeRef to reference another node.
setNodeValue | Set node's value as `NULL`-terminated string.
setPrefix | Set namespace prefix of this node.
~NodeRef | Public default destructor.

### NodeRef

Class constructor.

Syntax | Description
--- | ---
    NodeRef(
       const NodeRef< Node>& nref,
       Node* nptr);
| Used to create references to a given node when at least one reference to this node or another node is already available. The node deletion flag is not copied and is set to `FALSE`.
    NodeRef(
       const NodeRef< Node>& nref);
| Copy constructor. Used to create additional references to the node when at least one reference is already available. The node deletion flag is not copied and is set to `FALSE`.

Parameter | Description
--- | ---
    node_ref
| reference to provide the context
    nptr
| referenced node

Returns

`(NodeRef)` `Node` reference object

### appendChild

Appends the node to the end of this node's list of children and returns the new node. If `newChild` is a `DocumentFragment`, all of its children are appended in original order; the `DocumentFragment` node itself is not. If `newChild` is already in the DOM tree, it is first removed from its current position.

Syntax

    Node* appendChild(
       NodeRef& newChild)
    throw (DOMException);

Parameter | Description
--- | ---
    newChild
| reference node

Returns

`(Node*)` the node appended

### cloneNode

Creates and returns a duplicate of this node. The duplicate node has no parent. Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but it does not copy any text it contains unless it is a deep clone, since the text is contained in a child `Text` node. Cloning any other type of node simply returns a copy of the node. If deep is `TRUE`, all children of the node are recursively cloned, and the cloned node will have cloned children; a non-deep clone will have no children. If the cloned node is not inserted into another tree or fragment, it probably should be marked, through its reference, for deletion (by the user).

Syntax

    Node* cloneNode(
       boolean deep);

Parameter | Description
--- | ---
    deep
| whether to clone the entire node hierarchy beneath the node (`TRUE`), or just the node itself (`FALSE`)

Returns

`(Node*)` duplicate (cloned) node

### getAttributes

Returns `NamedNodeMap` of attributes of this node, or `NULL` if it has no attributes. Only element nodes can have attribute nodes. For other node kinds, `NULL` is always returned. In the current implementation, the node map of child nodes is live; all changes in the original node are reflected immediately. Because of this, side effects can be present for some DOM tree manipulation styles, in particular, in multithreaded environments.

Syntax

    NamedNodeMap< Node>* getAttributes() const;

Returns

`(NamedNodeMap*)` `NamedNodeMap` of attributes

### getChildNodes

Returns the list of child nodes, or `NULL` if this node has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return `NULL`. In the current implementation, the list of child nodes is live; all changes in the original node are reflected immediately. Because of this, side effects can be present for some DOM tree manipulation styles, in particular, in multithreaded environments.

Syntax

    NodeList< Node>* getChildNodes() const;

Returns

`(NodeList*)` the list of child nodes

### getFirstChild

Returns the first child node, or `NULL`, if this node has no children

Syntax

    Node* getFirstChild() const;

Returns

`(Node*)` the first child node, or `NULL`

### getLastChild

Returns the last child node, or `NULL`, if this node has no children

Syntax

    Node* getLastChild() const;

Returns

`(Node*)` the last child node, or `NULL`

### getLocalName

Returns local name (local part of the qualified name) of this node (in the data encoding) as a `NULL`-terminated string. If this node's name is not fully qualified (has no prefix), then the local name is the same as the name.

Syntax

    oratext* getLocalName() const;

Returns

`(oratext*)` local name of this node

### getNamespaceURI

Returns the namespace URI of this node (in the data encoding) as a `NULL`-terminated string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be `NULL`).

Syntax

    oratext* getNamespaceURI() const;

Returns

`(oratext*)` namespace URI of this node

### getNextSibling

Returns the next sibling node, or `NULL`, if this node has no next sibling

Syntax

    Node* getNextSibling() const;

Returns

`(Node*)` the next sibling node, or `NULL`

### getNoMod

Tests if no modifications are allowed for this node and the DOM tree it belongs to. This member function is Oracle extension.

Syntax

    boolean getNoMod() const;

Returns

`(boolean)` `TRUE` if no modifications are allowed

### getNodeName

Returns the (fully-qualified) name of the node (in the data encoding) as a `NULL`-terminated string, for example "bar\0" or "foo:bar\0". Some node kinds have fixed names: "`#text`", "`#cdata-section`", "`#comment`", "`#document`", "`#document-fragment`". The name of a node cannot changed once it is created.

Syntax

    oratext* getNodeName() const;

Returns

`(oratext*)` name of node in data encoding

### getNodeType

Returns DOMNodeType of the node

Syntax

    DOMNodeType getNodeType() const;

Returns

`(DOMNodeType)` of the node

### getNodeValue

Returns the "value" (associated character data) for a node as a `NULL`-terminated string. Character and general entities will have been replaced. Only `Attr`, `CDATA`, `Comment`, `ProcessingInstruction` and `Text` nodes have values, all other node types have `NULL` value.

Syntax

    oratext* getNodeValue() const;

Returns

`(oratext *)` value of node

### getOwnerDocument

Returns the document node associated with this node. It is assumed that the document node type is derived from the node type. Each node may belong to only one document, or may not be associated with any document at all, such as immediately after it was created on user's request. The "owning" document [node] is returned, or the WRONG_DOCUMENT_ERR exception is thrown.

Syntax

    Node* getOwnerDocument() const throw (DOMException);

Returns

`(Node*)` the owning document node

### getParentNode

Returns the parent node, or `NULL`, if this node has no parent

Syntax

    Node* getParentNode() const;

Returns

`(Node*)` the parent node, or `NULL`

### getPrefix

Returns the namespace prefix of this node (in the data encoding) (as a `NULL`-terminated string). If this node's name is not fully qualified (has no prefix), `NULL` is returned.

Syntax

    oratext* getPrefix() const;

Returns

`(oratext*)` namespace prefix of this node

### getPreviousSibling

Returns the previous sibling node, or `NULL`, if this node has no previous siblings

Syntax

    Node* getPreviousSibling() const;

Returns

`(Node*)` the previous sibling node, or `NULL`

### hasAttributes

Returns `TRUE` if this node has attributes, if it is an element. Otherwise, it returns `FALSE`. Note that for nodes that are not elements, it always returns `FALSE`.

Syntax

    boolean hasAttributes() const;

Returns

`(boolean)` `TRUE` is this node is an element and has attributes

### hasChildNodes

Tests if this node has children. Only `Element`, `Document`, `DTD`, and `DocumentFragment` nodes may have children.

Syntax

    boolean hasChildNodes() const;

Returns

`(boolean)` `TRUE` if this node has any children

### insertBefore

Inserts the node `newChild` before the existing child node `refChild` in this node. `refChild` must be a child of this node. If`newChild` is a `DocumentFragment`, all of its children are inserted (in the same order) before `refChild`; the `DocumentFragment` node itself is not. If `newChild` is already in the DOM tree, it is first removed from its current position.

Syntax

    Node* insertBefore(
       NodeRef& newChild,
       NodeRef& refChild)
    throw (DOMException);

Parameter | Description
--- | ---
    newChild
| new node
    refChild
| reference node

Returns

`(Node*)` the node being inserted

### isSupported

Tests if the feature, specified by the arguments, is supported by the DOM implementation of this node.

Syntax

    boolean isSupported(
       oratext* feature,
       oratext* version) const;

Parameter | Description
--- | ---
    feature
| package name of feature
    version
| version of package

Returns

`(boolean)` `TRUE` is specified feature is supported

### markToDelete

Sets the mark indicating that the referenced node should be deleted at the time when destructor of this reference is called. All other references to the node become invalid. This behavior is inherited by all other reference classes. This member function is Oracle extension.

Syntax

    void markToDelete();

### normalize

"Normalizes" the subtree rooted at an element, merges adjacent `Text` nodes children of elements. Note that adjacent `Text` nodes will never be created during a normal parse, only after manipulation of the document with DOM calls.

Syntax

    void normalize();

### removeChild

Removes the node from this node's list of children and returns it. The node is orphaned; its parent will be `NULL` after removal.

Syntax

    Node* removeChild(
       NodeRef& oldChild)
    throw (DOMException);

Parameter | Description
--- | ---
    oldChild
| old node

Returns

`(Node*)` node removed

### replaceChild

Replaces the child node `oldChild` with the new node `newChild` in this node's children list, and returns `oldChild` (which is now orphaned, with a `NULL` parent). If `newChild` is a `DocumentFragment`, all of its children are inserted in place of `oldChild`; the `DocumentFragment` node itself is not. If `newChild` is already in the DOM tree, it is first removed from its current position.

Syntax

    Node* replaceChild(
       NodeRef& newChild,
       NodeRef& oldChild)
    throw (DOMException);

Parameter | Description
--- | ---
    newChild
| new node
    oldChild
| old node

Returns

`(Node*)` the node replaced

### resetNode

This function resets `NodeRef` to reference `Node` given as an argument

Syntax

    void resetNode(
       Node* nptr);

Parameter | Description
--- | ---
    nptr
| reference node

### setNodeValue

Sets a node's value (character data) as a `NULL`-terminated string. Does not allow setting the value to `NULL`. Only `Attr`, `CDATA`, `Comment`, `ProcessingInstruction`, and `Text` nodes have values. Trying to set the value of another kind of node is a no-op. The new value must be in the data encoding! It is not verified, converted, or checked. The value is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

It throws the `NO_MODIFICATION_ALLOWED_ERR` exception, if no modifications are allowed, or `UNDEFINED_ERR`, with an appropriate Oracle XML error code (see xml.h), in the case of an implementation defined error.

Syntax

    void setNodeValue(
       oratext* data)
    throw (DOMException);

Parameter | Description
--- | ---
    data
| new value for node

### setPrefix

Sets the namespace prefix of this node (as `NULL`-terminated string). Does not verify the prefix is defined! And does not verify that the prefix is in the current data encoding. Just causes a new qualified name to be formed from the new prefix and the old local name.

It throws the `NO_MODIFICATION_ALLOWED_ERR` exception, if no modifications are allowed. Or it throws `NAMESPACE_ERR` if the `namespaceURI` of this node is `NULL`, or if the specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace", or if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/". Note that the `INVALID_CHARACTER_ERR` exception is never thrown since it is not checked how the prefix is formed

Syntax

    void setPrefix(
       oratext* prefix)
    throw (DOMException);

Parameter | Description
--- | ---
    prefix
| new namespace prefix

### ~NodeRef

This is the default destructor. It cleans the reference to the node and, if the node is marked for deletion, deletes the node. If the node was marked for deep deletion, the tree under the node is also deleted (deallocated). It is usually called by the environment. But it can be called by the user directly if necessary.

Syntax

    ~NodeRef();