Skip Headers

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

Previous Next  

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();