2 Package Dom APIs for C++

Using Dom

DOM interfaces are represented as generic references to different implementations of the DOM specifications. They are parameterized by Node, which supports various specializations and instantiations. Of them, the most important is xmlnode that corresponds to the current C implementation.

These generic references do not have a NULL-like value. Any implementation should never create a stateless reference. If there is need to signal that something has no state, an exception should be thrown.

Many methods might throw the SYNTAX_ERR exception, if the DOM tree is incorrectly formed, or UNDEFINED_ERR, in the case of wrong parameters or unexpected NULL pointers. If these are the only errors that a particular method might throw, it is not reflected in the method signature.

Actual DOM trees do not dependent on the context (TCtx). However, manipulations on DOM trees in the current, xmlctx based implementation require access to the current context (TCtx). This is accomplished by passing the context pointer to the constructor of DOMImplRef. In multithreaded environment DOMImplRef is always created in the thread context and, so, has the pointer to the right context.

DOMImplRef providea a way to create DOM trees. DomImplRef is a reference to the actual DOMImplementation object that is created when a regular, non-copy constructor of DomImplRef is invoked. This works well in multithreaded environment where DOM trees need to be shared, and each thread has a separate TCtx associated with it. This works equally well in a single threaded environment.

DOMString is only one of encodings supported by Oracle implementations. The support of other encodings is Oracle's extension. The oratext* data type is used for all encodings.

Dom Datatypes

Table 2-1 summarizes the datatypes of the Dom package.

AcceptNodeCodes

Defines values returned by node filters. Used by node iterators and tree walkers.

CPXML2174Definition

typedef enum AcceptNodeCode {
   FILTER_ACCEPT   = 1,
   FILTER_REJECT   = 2,
   FILTER_SKIP     = 3
    } AcceptNodeCode;

CompareHowCode

Defines type of comparison.

CPXML2176Definition

typedef enum CompareHowCode {
   START_TO_START = 0,
   START_TO_END = 1, 
   END_TO_END = 2, 
   END_TO_START = 3 }
CompareHowCode;

DOMNodeType

Defines type of node.

CPXML2178Definition

typedef enum DOMNodeType {
   UNDEFINED_NODE = 0,
   ELEMENT_NODE = 1, 
   ATTRIBUTE_NODE = 2, 
   TEXT_NODE = 3, 
   CDATA_SECTION_NODE = 4, 
   ENTITY_REFERENCE_NODE = 5, 
   ENTITY_NODE = 6, 
   PROCESSING_INSTRUCTION_NODE = 7, 
   COMMENT_NODE = 8, 
   DOCUMENT_NODE = 9, 
   DOCUMENT_TYPE_NODE = 10, 
   DOCUMENT_FRAGMENT_NODE = 11, 
   NOTATION_NODE = 12 
} DOMNodeType;

DOMExceptionCode

Defines codes for DOM exception.

CPXML2180Definition

typedef enum DOMExceptionCode {
   UNDEFINED_ERR               = 0,
   INDEX_SIZE_ERR              = 1,
   DOMSTRING_SIZE_ERR          = 2,
   HIERARCHY_REQUEST_ERR       = 3,
   WRONG_DOCUMENT_ERR          = 4,
   INVALID_CHARACTER_ERR       = 5,
   NO_DATA_ALLOWED_ERR         = 6,
   NO_MODIFICATION_ALLOWED_ERR = 7,
   NOT_FOUND_ERR               = 8,
   NOT_SUPPORTED_ERR           = 9,
   INUSE_ATTRIBUTE_ERR         = 10,
   INVALID_STATE_ERR           = 11,
   SYNTAX_ERR                  = 12,
   INVALID_MODIFICATION_ERR    = 13,
   NAMESPACE_ERR               = 14,
   INVALID_ACCESS_ERR          = 15
} DOMExceptionCode;

WhatToShowCode

Defines codes for filtering.

CPXML2182Definition

typedef unsigned long WhatToShowCode; 
   const unsigned long SHOW_ALL = 0xFFFFFFFF; c
   onst unsigned long SHOW_ELEMENT = 0x00000001; 
   const unsigned long SHOW_ATTRIBUTE = 0x00000002; 
   const unsigned long SHOW_TEXT = 0x00000004; 
   const unsigned long SHOW_CDATA_SECTION = 0x00000008; 
   const unsigned long SHOW_ENTITY_REFERENCE = 0x00000010; 
   const unsigned long SHOW_ENTITY = 0x00000020; 
   const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x00000040; 
   const unsigned long SHOW_COMMENT = 0x00000080; 
   const unsigned long SHOW_DOCUMENT = 0x00000100; 
   const unsigned long SHOW_DOCUMENT_TYPE = 0x00000200; 
   const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x00000400; 
   const unsigned long SHOW_NOTATION = 0x00000800;

RangeExceptionCode

Codes for DOM Range exceptions.

CPXML2184Definition

typedef enum RangeExceptionCode {
   RANGE_UNDEFINED_ERR         = 0,
   BAD_BOUNDARYPOINTS_ERR      = 1,
   INVALID_NODE_TYPE_ERR       = 2
} RangeExceptionCode;
 

AttrRef Interface

Table 2-2 summarizes the methods available through AttrRef interface.

AttrRef()

Class constructor.

AttrRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

AttrRef(
   const AttrRef< Node>& nref);

node_ref

nptr

CPXML2187Returns

(AttrRef) Node reference object

getName()

Returns the fully-qualified name of an attribute (in the data encoding) as a NULL-terminated string.

CPXML2189Syntax

oratext* getName() const;

CPXML2190Returns

(oratext *) name of attribute

getOwnerElement()

Returns attribute's owning element

CPXML2192Syntax

Node* getOwnerElement();

CPXML2193Returns

(Node*) attribute's owning element node.

getSpecified()

Returns the 'specified' value for an attribute. If the attribute was explicitly given a value in the original document, it is TRUE; otherwise, it is FALSE. If the node is not an attribute, returns FALSE. If the user sets attribute's value through DOM, its 'specified' value will be TRUE.

CPXML2195Syntax

boolean getSpecified() const;

CPXML2196Returns

(boolean) attribute's "specified" value

getValue()

Returns the "value" (character data) of an attribute (in the data encoding) as NULL-terminated string. Character and general entities will have been replaced.

CPXML2198Syntax

oratext* getValue() const;

CPXML2199Returns

(oratext*) attribute's value

setValue()

Sets the given attribute's value to data. The new value must be in the data encoding. It is not verified, converted, or checked. The attribute's 'specified' flag will be TRUE after setting a new value.

CPXML2201Syntax

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

data

~AttrRef()

This is the default destructor.

CPXML2203Syntax

~AttrRef();

CDATASectionRef Interface

Table 2-3 summarizes the methods available through CDATASectionRef interface.

CDATASectionRef()

Class constructor.

CDATASectionRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

CDATASectionRef(
   const CDATASectionRef< Node>& nref);

node_ref

nptr

CPXML2206Returns

(CDATASectionRef) Node reference object

~CDATASectionRef()

This is the default destructor.

CPXML2208Syntax

~CDATASectionRef();

CharacterDataRef Interface

Table 2-4 summarizes the methods available through CharacterDataRef interface.

appendData()

Append a string to the end of a CharacterData node's data. The appended data should be in the data encoding. It will not be verified, converted, or checked.

CPXML2211Syntax

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

data

deleteData()

Remove a range of characters from a CharacterData node's data. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted.

CPXML2213Syntax

void deleteData( 
   ub4 offset, 
   ub4 count) 
throw (DOMException);

offset

count

freeString()

Deallocates the string allocated by substringData(). It is Oracle's extension.

CPXML2215Syntax

void freeString( 
   oratext* str);

str

getData()

Returns the data for a CharacterData node (type text, comment or CDATA) in the data encoding.

CPXML2217Syntax

oratext* getData() const;

CPXML2218Returns

(oratext*) node's data

getLength()

Returns the length of the data for a CharacterData node (type Text, Comment or CDATA) in characters (not bytes).

CPXML2220Syntax

ub4 getLength() const;

CPXML2221Returns

(ub4) length in characters (not bytes!) of node's data

insertData()

Insert a string into a CharacterData node's data at the specified position. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.

CPXML2223Syntax

void insertData( 
   ub4 offset,
   oratext* data) 
throw (DOMException);

offset

data

replaceData()

Replaces a range of characters in a CharacterData node's data with a new string. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.

CPXML2225Syntax

void replaceData( 
   ub4 offset, 
   ub4 count, 
   oratext* data)
throw (DOMException);

offset

count

data

setData()

Sets data for a CharacterData node (type text, comment or CDATA), replacing the old data. The new data is not verified, converted, or checked -- it should be in the data encoding.

CPXML2227Syntax

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

data

substringData()

Returns a range of character data from a CharacterData node (type Text, Comment or CDATA). Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned. The substring is permanently allocated in the context managed memory and should be explicitly deallocated by freeString

CPXML2229Syntax

oratext* substringData( 
   ub4 offset, 
   ub4 count) 
throw (DOMException);

offset

count

CPXML2230Returns

(oratext *) specified substring

CommentRef Interface

Table 2-5 summarizes the methods available through CommentRef interface.

CommentRef()

Class constructor.

CommentRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

CommentRef(
   const CommentRef< Node>& nref);

node_ref

nptr

CPXML2233Returns

(CommentRef) Node reference object

~CommentRef()

This is the default destructor.

CPXML2235Syntax

~CommentRef();

DOMException Interface

Table 2-6 summarizes the methods available through the DOMException interface.

getDOMCode()

This is a virtual member function that defines a prototype for implementation defined member functions returning DOM exception codes, defined in DOMExceptionCode, of the exceptional situations during execution

CPXML2238Syntax

virtual DOMExceptionCode getDOMCode() const = 0;

CPXML2239Returns

(DOMExceptionCode) exception code

getMesLang()

Virtual member function inherited from XmlException

CPXML2241Syntax

virtual oratext* getMesLang() const = 0;

CPXML2242Returns

(oratext*) Current language (encoding) of error messages

getMessage()

Virtual member function inherited from XmlException

CPXML2244Syntax

virtual oratext* getMessage() const = 0;

CPXML2245Returns

(oratext *) Error message

DOMImplRef Interface

Table 2-7 summarizes the methods available through DOMImplRef interface.

DOMImplRef()

Class constructor.

DOMImplRef(
   Context* ctx_ptr,
   DOMImplementation< Node>* impl_ptr);

DOMImplRef(
   const DOMImplRef< Context, Node>& iref);

DOMImplRef(
   const DOMImplRef< Context, Node>& iref,
   Context* ctx_ptr);

ctx_ptr

impl_ptr

CPXML2248Returns

(DOMImplRef) reference to the implementation object

createDocument()

Creates document reference

CPXML2250Syntax

DocumentRef< Node>* createDocument(
   oratext* namespaceURI,
   oratext* qualifiedName,
   DocumentTypeRef< Node>& doctype)
throw (DOMException);

namespaceURI

qualifiedName

doctype

CPXML2251Returns

(DocumentRef< Node>*) document reference

createDocumentType()

Creates DTD reference

CPXML2253Syntax

DocumentTypeRef< Node>* createDocumentType(
   oratext* qualifiedName,
   oratext* publicId,
   oratext* systemId)
throw (DOMException);

qualifiedName

publicId

systemId

CPXML2254Returns

(DocumentTypeRef< Node>*) DTD reference

formDocument()

Forms a document reference given a document pointer.

CPXML2256Syntax

DocumentRef< Node>* formDocument( Node* node);

node

CPXML2257Returns

(DocumentRef< Node>*) pointer to the document reference

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.

CPXML2259Syntax

DOMImplementation< Node>* getImplementation() const;

CPXML2260Returns

(DOMImplementation) DOMImplementation reference object

getNoMod()

Get the 'no modification allowed' flag value. This is an Oracle extension.

CPXML2262Syntax

boolean getNoMod() const;

CPXML2263Returns

TRUE if flag's value is TRUE, FALSE otherwise

hasFeature()

Determine if a DOM feature is implemented. Returns TRUE if the feature is implemented in the specified version, FALSE otherwise.

In level 1, the legal values for package are 'HTML' and 'XML' (case-insensitive), and the version is the string "1.0". If the version is not specified, supporting any version of the feature will cause the method to return TRUE.

DOM 1.0 features are "XML" and "HTML".

DOM 2.0 features are "Core", "XML", "HTML", "Views", "StyleSheets", "CSS", "CSS2", "Events", "UIEvents", "MouseEvents", "MutationEvents", "HTMLEvents", "Range", "Traversal"

CPXML2265Syntax

boolean hasFeature(
   oratext* feature, 
   oratext* version);

feature

version

CPXML2266Returns

(boolean) is feature implemented?

setContext()

It is needed to create node references in a different context

CPXML2268Syntax

void setContext(
   NodeRef< Node>& nref, 
   Context* ctx_ptr);

nref

ctx_ptr

~DOMImplRef()

This is the default destructor. It cleans the reference to the implementation object. It is usually called by the environment. But it can be called by the user directly if necessary.

CPXML2270Syntax

~DOMImplRef(); 

DOMImplementation Interface

Table 2-8 summarizes the methods available through DOMImplementation interface.

DOMImplementation()

Creates DOMImplementation object. Sets the 'no modifications allowed' flag to the parameter value.

CPXML2273Syntax

DOMImplementation( 
   boolean no_mod);

no_mod

CPXML2274Returns

(DOMImplementation) implementation object

getNoMod()

Get the 'no modification allowed' flag value. This is an Oracle extension.

CPXML2276Syntax

boolean getNoMod() const; 

CPXML2277Returns

TRUE if flag's value is TRUE, FALSE otherwise

~DOMImplementation()

This is the default destructor. It removes all DOM trees associated with this object.

CPXML2279Syntax

~DOMImplementation(); 

DocumentFragmentRef Interface

Table 2-9 summarizes the methods available through DocumentFragmentRef interface.

DocumentFragmentRef()

Class constructor.

DocumentFragmentRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

DocumentFragmentRef(
   const DocumentFragmentRef< Node>& nref);

node_ref

nptr

CPXML2282Returns

(DocumentFragmentRef) Node reference object

~DocumentFragmentRef()

This is the default destructor.

CPXML2284Syntax

~DocumentFragmentRef() {}

DocumentRange Interface

Table 2-10 summarizes the methods available through DocumentRange interface.

DocumentRange()

Constructs the factory.

CPXML2287Syntax

DocumentRange();

CPXML2288Returns

(DocumentRange) new factory object

createRange()

Create new range object.

CPXML2290Syntax

Range< Node>* createRange( 
   DocumentRef< Node>& doc);

doc

CPXML2291Returns

(Range*) Pointer to new range

destroyRange()

Destroys range object.

CPXML2293Syntax

void destroyRange( 
   Range< Node>* range)
throw (DOMException);

range

~DocumentRange()

Default destructor.

CPXML2295Syntax

~DocumentRange();

DocumentRef Interface

Table 2-11 summarizes the methods available through DocumentRef interface.

DocumentRef()

This is a constructor.

DocumentRef(
   const NodeRef< Node>& nref,
   Node* nptr);

DocumentRef(
   const DocumentRef< Node>& nref);

nref

nptr

CPXML2298Returns

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

CPXML2300Syntax

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

name

CPXML2301Returns

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

CPXML2303Syntax

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

namespaceURI

qualifiedName

CPXML2304Returns

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

CPXML2306Syntax

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

data

CPXML2307Returns

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

CPXML2309Syntax

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

data

CPXML2310Returns

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

CPXML2312Syntax

Node* createDocumentFragment()
throw (DOMException);

CPXML2313Returns

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

CPXML2315Syntax

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

tagname

CPXML2316Returns

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

CPXML2318Syntax

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

namespaceURI

qualifiedName

CPXML2319Returns

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

CPXML2321Syntax

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

name

CPXML2322Returns

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

CPXML2324Syntax

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

target

data

CPXML2325Returns

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

CPXML2327Syntax

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

data

CPXML2328Returns

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

CPXML2330Syntax

Node* getDoctype() const;

CPXML2331Returns

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

CPXML2333Syntax

Node* getDocumentElement() const;

CPXML2334Returns

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

CPXML2336Syntax

Node* getElementById(
   oratext* elementId);

elementId

CPXML2337Returns

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

CPXML2339Syntax

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

tagname

CPXML2340Returns

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

CPXML2342Syntax

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

namespaceURI

localName

CPXML2343Returns

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

CPXML2345Syntax

DOMImplementation< Node>* getImplementation() const;

CPXML2346Returns

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

CPXML2348Syntax

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

importedNode

deep

CPXML2349Returns

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

CPXML2351Syntax

~DocumentRef();

DocumentTraversal Interface

Table 2-12 summarizes the methods available through DocumentTraversal interface.

DocumentTraversal()

Constructs the factory.

CPXML2354Syntax

DocumentTraversal();

CPXML2355Returns

(DocumentTraversal) new factory object

createNodeIterator()

Create new iterator object.

CPXML2357Syntax

NodeIterator< Node>* createNodeIterator(
   NodeRef< Node>& root,
   WhatToShowCode whatToShow,
   boolean entityReferenceExpansion)
throw (DOMException);

root

whatToShow

entityReferenceExpansion

CPXML2358Returns

(NodeIterator*) Pointer to new iterator

createTreeWalker()

Create new TreeWalker object.

CPXML2360Syntax

TreeWalker< Node>* createTreeWalker(
   NodeRef< Node>& root,
   WhatToShowCode whatToShow,
   boolean entityReferenceExpansion)
throw (DOMException);

root

whatToShow

entityReferenceExpansion

CPXML2361Returns

(TreeWalker*) Pointer to new tree walker

destroyNodeIterator()

Destroys node iterator object.

CPXML2363Syntax

void destroyNodeIterator(
   NodeIterator< Node>* iter)
throw (DOMException);

iter

destroyTreeWalker()

Destroys TreeWalker object.

CPXML2365Syntax

void destroyTreeWalker(
   TreeWalker< Node>* walker)
throw (DOMException);

walker

~DocumentTraversal()

Default destructor.

CPXML2367Syntax

~DocumentTraversal();

DocumentTypeRef Interface

Table 2-13 summarizes the methods available through DocumentTypeRef interface.

DocumentTypeRef()

This is a constructor.

DocumentTypeRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

DocumentTypeRef(
   const DocumentTypeRef< Node>& node_ref);

node_ref

nptr

CPXML2370Returns

(DocumentTypeRef) Node reference object

getEntities()

Returns a named node map of general entities defined by the DTD.

CPXML2372Syntax

NamedNodeMap< Node>* getEntities() const;

CPXML2373Returns

(NamedNodeMap< Node>*) map containing entities

getInternalSubset()

Returns the content model for an element. If there is no DTD, returns NULL.

CPXML2375Syntax

Node* getInternalSubset( 
   oratext* name);

name

CPXML2376Returns

(xmlnode*) content model subtree

getName()

Returns DTD's name (specified immediately after the DOCTYPE keyword)

CPXML2378Syntax

oratext* getName() const;

CPXML2379Returns

(oratext*) name of DTD

getNotations()

Returns a named node map of notations declared by the DTD.

CPXML2381Syntax

NamedNodeMap< Node>* getNotations() const;

CPXML2382Returns

(NamedNodeMap< Node>*) map containing notations

getPublicId()

Returns DTD's public identifier

CPXML2384Syntax

oratext* getPublicId() const;

CPXML2385Returns

(oratext*) DTD's public identifier

getSystemId()

Returns DTD's system identifier

CPXML2387Syntax

oratext* getSystemId() const;

CPXML2388Returns

(oratext*) DTD's system identifier

~DocumentTypeRef()

This is the default destructor.

CPXML2390Syntax

~DocumentTypeRef();

ElementRef Interface

Table 2-14 summarizes the methods available through ElementRef interface.

ElementRef()

Class constructor.

ElementRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

ElementRef(
   const ElementRef< Node>& node_ref);

node_ref

nptr

CPXML2393Returns

(ElementRef) Node reference object

getAttribute()

Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL.

CPXML2395Syntax

oratext* getAttribute(
   oratext* name) const;

name

CPXML2396Returns

(oratext*) named attribute's value (in data encoding)

getAttributeNS()

Returns the value of an element's attribute (specified by URI and local name). Note that an attribute may have the empty string as its value, but cannot be NULL.

CPXML2398Syntax

oratext* getAttributeNS(
   oratext* namespaceURI,
   oratext* localName);

namespaceURI

localName

CPXML2399Returns

(oratext *) named attribute's value (in data encoding)

getAttributeNode()

Returns the attribute node given its name.

CPXML2401Syntax

Node* getAttributeNode(
   oratext* name) const;

name

CPXML2402Returns

(Node*) the attribute node

getElementsByTagName()

Returns a list of all elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the subtree. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Tag names are case sensitive. This function is not namespace aware; the full tag names are compared. The returned list should be freed by the user.

CPXML2404Syntax

NodeList< Node>* getElementsByTagName(
   oratext* name);

name

CPXML2405Returns

(NodeList< Node>*) the list of elements

getTagName()

Returns the tag name of an element node which is supposed to have the same value as the node name from the node interface

CPXML2407Syntax

oratext* getTagName() const;

CPXML2408Returns

(oratext*) element's name [in data encoding]

hasAttribute()

Determines if an element has a attribute with the given name

CPXML2410Syntax

boolean hasAttribute(
   oratext* name);

name

CPXML2411Returns

(boolean) TRUE if element has attribute with given name

hasAttributeNS()

Determines if an element has a attribute with the given URI and local name

CPXML2413Syntax

boolean hasAttributeNS(
   oratext* namespaceURI,
   oratext* localName);

namespaceURI

localName

CPXML2414Returns

(boolean) TRUE if element has such attribute

removeAttribute()

Removes an attribute specified by name. The attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

CPXML2416Syntax

void removeAttribute(
   oratext* name) throw (DOMException);

name

removeAttributeNS()

Removes an attribute specified by URI and local name. The attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

CPXML2418Syntax

void removeAttributeNS(
   oratext* namespaceURI,
   oratext* localName)
throw (DOMException);

namespaceURI

localName

removeAttributeNode()

Removes an attribute from an element. Returns a pointer to the removed attribute or NULL

CPXML2420Syntax

Node* removeAttributeNode(
   AttrRef< Node>& oldAttr)
throw (DOMException);

oldAttr

CPXML2421Returns

(Node*) the attribute node (old) or NULL

setAttribute()

Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded.

CPXML2423Syntax

void setAttribute( 
   oratext* name, 
   oratext* value)
throw (DOMException);

name

value

setAttributeNS()

Creates a new attribute for an element with the given URI, local name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded.

CPXML2425Syntax

void setAttributeNS( 
   oratext* namespaceURI,
   oratext* qualifiedName, 
   oratext* value)
throw (DOMException);

namespaceURI

qualifiedName

value

setAttributeNode()

Adds a new attribute to an element. If an attribute with the given name already exists, it is replaced and a pointer to the old attribute returned. If the attribute is new, it is added to the element's list and a pointer to the new attribute is returned.

CPXML2427Syntax

Node* setAttributeNode( 
   AttrRef< Node>& newAttr)
throw (DOMException);

newAttr

CPXML2428Returns

(Node*) the attribute node (old or new)

~ElementRef()

This is the default destructor.

CPXML2430Syntax

~ElementRef();

EntityRef Interface

Table 2-15 summarizes the methods available through EntityRef interface.

EntityRef()

Class constructor.

EntityRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

EntityRef(
   const EntityRef< Node>& nref);

node_ref

nptr

CPXML2433Returns

(EntityRef) Node reference object

getNotationName()

For unparsed entities, returns the name of its notation (in the data encoding). For parsed entities and other node types, returns NULL.

CPXML2435Syntax

oratext* getNotationName() const;

CPXML2436Returns

(oratext*) entity's notation

getPublicId()

Returns an entity's public identifier (in the data encoding).

CPXML2438Syntax

oratext* getPublicId() const;

CPXML2439Returns

(oratext*) entity's public identifier

getSystemId()

Returns an entity's system identifier (in the data encoding).

CPXML2441Syntax

oratext* getSystemId() const;

CPXML2442Returns

(oratext*) entity's system identifier

getType()

Returns a boolean for an entity describing whether it is general (TRUE) or parameter (FALSE).

CPXML2444Syntax

boolean getType() const;

CPXML2445Returns

(boolean) TRUE for general entity, FALSE for parameter entity

~EntityRef()

This is the default destructor.

CPXML2447Syntax

~EntityRef();

EntityReferenceRef Interface

Table 2-16 summarizes the methods available through EntityReferenceRef interface.

EntityReferenceRef()

Class constructor.

EntityReferenceRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

EntityReferenceRef(
   const EntityReferenceRef< Node>& nref);

node_ref

nptr

CPXML2450Returns

(EntityReferenceRef) Node reference object

~EntityReferenceRef()

This is the default destructor.

CPXML2452Syntax

~EntityReferenceRef();

NamedNodeMapRef Interface

Table 2-17 summarizes the methods available through NamedNodeMapRef interface.

NamedNodeMapRef()

Class constructor.

NamedNodeMapRef(
   const NodeRef< Node>& node_ref,
   NamedNodeMap< Node>* mptr);

NamedNodeMapRef(
   const NamedNodeMapRef< Node>& mref);

node_ref

nptr

CPXML2455Returns

(NamedNodeMapRef) Node reference object

getLength()

Get the length of the map.

CPXML2457Syntax

ub4 getLength() const;

CPXML2458Returns

(ub4) map's length

getNamedItem()

Get the name of the item, given its name.

CPXML2460Syntax

Node* getNamedItem( oratext* name) const;

name

CPXML2461Returns

(Node*) pointer to the item

getNamedItemNS()

Get the name of the item, given its namespace URI and local name.

CPXML2463Syntax

Node* getNamedItemNS( 
   oratext* namespaceURI,
   oratext* localName) const;

namespaceURI

localName

CPXML2464Returns

(Node*) pointer to the item

item()

Get item, given its index.

CPXML2466Syntax

Node* item( 
   ub4 index) const;

index

CPXML2467Returns

(Node*) pointer to the item

removeNamedItem()

Remove the item from the map, given its name.

CPXML2469Syntax

Node* removeNamedItem( 
   oratext* name) 
throw (DOMException);

name

CPXML2470Returns

(Node*) pointer to the removed item

removeNamedItemNS()

Remove the item from the map, given its namespace URI and local name.

CPXML2472Syntax

Node* removeNamedItemNS( 
   oratext* namespaceURI,
   oratext* localName)
throw (DOMException);

namespaceURI

localName

CPXML2473Returns

(Node*) pointer to the removed item

setNamedItem()

Add new item to the map.

CPXML2475Syntax

Node* setNamedItem(
   NodeRef< Node>& newItem)
throw (DOMException);

newItem

CPXML2476Returns

(Node*) pointer to new item

setNamedItemNS()

Set named item, which is namespace aware, to the map.

CPXML2478Syntax

Node* setNamedItemNS(
   NodeRef< Node>& newItem)
throw (DOMException);

newItem

CPXML2479Returns

(Node*) pointer to the item

~NamedNodeMapRef()

Default destructor.

CPXML2481Syntax

~NamedNodeMapRef();

NodeFilter Interface

Table 2-18 summarizes the methods available through NodeFilter interface.

acceptNode()

This function is used as a test by NodeIterator and TreeWalker.

CPXML2484Syntax

template< typename Node> AcceptNodeCode AcceptNode(
   NodeRef< Node>& nref);

nref

CPXML2485Returns

(AcceptNodeCode) result returned by the filter function

NodeIterator Interface

Table 2-19 summarizes the methods available through NodeIterator interface.

adjustCtx()

Attaches this iterator to the context associated with a given node reference

CPXML2488Syntax

void adjustCtx( 
   NodeRef< Node>& nref);

nref

detach()

Invalidates the iterator.

CPXML2490Syntax

void detach();

nextNode()

Go to the next node.

CPXML2492Syntax

Node* nextNode() throw (DOMException);

CPXML2493Returns

(Node*) pointer to the next node

previousNode()

Go to the previous node.

CPXML2495Syntax

Node* previousNode() throw (DOMException);

CPXML2496Returns

(Node*) pointer to the previous node

NodeListRef Interface

Table 2-20 summarizes the methods available through NodeListRef interface.

NodeListRef()

Class constructor.

NodeListRef(
   const NodeRef< Node>& node_ref,
   NodeList< Node>* lptr);

NodeListRef(
   const NodeListRef< Node>& lref);

node_ref

lptr

CPXML2499Returns

(NodeListRef) Node reference object

getLength()

Get the length of the list.

CPXML2501Syntax

ub4 getLength() const;

CPXML2502Returns

(ub4) list's length

item()

Get the item, given its index.

CPXML2504Syntax

Node* item( 
   ub4 index) const;

index

CPXML2505Returns

(Node*) pointer to the item

~NodeListRef()

Destructs the object.

CPXML2507Syntax

~NodeListRef();

NodeRef Interface

Table 2-21 summarizes the methods available through NodeRef interface.

NodeRef()

Class constructor.

NodeRef(
   const NodeRef< Node>& nref,
   Node* nptr);

NodeRef(
   const NodeRef< Node>& nref);

node_ref

nptr

CPXML2510Returns

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

CPXML2512Syntax

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

newChild

CPXML2513Returns

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

CPXML2515Syntax

Node* cloneNode( 
   boolean deep);

deep

CPXML2516Returns

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

CPXML2518Syntax

NamedNodeMap< Node>* getAttributes() const;

CPXML2519Returns

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

CPXML2521Syntax

NodeList< Node>* getChildNodes() const;

CPXML2522Returns

(NodeList*) the list of child nodes

getFirstChild()

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

CPXML2524Syntax

Node* getFirstChild() const;

CPXML2525Returns

(Node*) the first child node, or NULL

getLastChild()

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

CPXML2527Syntax

Node* getLastChild() const;

CPXML2528Returns

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

CPXML2530Syntax

oratext* getLocalName() const;

CPXML2531Returns

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

CPXML2533Syntax

oratext* getNamespaceURI() const;

CPXML2534Returns

(oratext*) namespace URI of this node

getNextSibling()

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

CPXML2536Syntax

Node* getNextSibling() const;

CPXML2537Returns

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

CPXML2539Syntax

boolean getNoMod() const;

CPXML2540Returns

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

CPXML2542Syntax

oratext* getNodeName() const;

CPXML2543Returns

(oratext*) name of node in data encoding

getNodeType()

Returns DOMNodeType of the node

CPXML2545Syntax

DOMNodeType getNodeType() const;

CPXML2546Returns

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

CPXML2548Syntax

oratext* getNodeValue() const;

CPXML2549Returns

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

CPXML2551Syntax

Node* getOwnerDocument() const throw (DOMException);

CPXML2552Returns

(Node*) the owning document node

getParentNode()

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

CPXML2554Syntax

Node* getParentNode() const;

CPXML2555Returns

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

CPXML2557Syntax

oratext* getPrefix() const;

CPXML2558Returns

(oratext*) namespace prefix of this node

getPreviousSibling()

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

CPXML2560Syntax

Node* getPreviousSibling() const;

CPXML2561Returns

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

CPXML2563Syntax

boolean hasAttributes() const;

CPXML2564Returns

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

CPXML2566Syntax

boolean hasChildNodes() const;

CPXML2567Returns

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

CPXML2569Syntax

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

newChild

refChild

CPXML2570Returns

(Node*) the node being inserted

isSupported()

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

CPXML2572Syntax

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

feature

version

CPXML2573Returns

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

CPXML2575Syntax

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.

CPXML2577Syntax

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.

CPXML2579Syntax

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

oldChild

CPXML2580Returns

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

CPXML2582Syntax

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

newChild

oldChild

CPXML2583Returns

(Node*) the node replaced

resetNode()

This function resets NodeRef to reference Node given as an argument

CPXML2585Syntax

void resetNode( 
   Node* nptr);

nptr

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.

CPXML2587Syntax

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

data

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

CPXML2589Syntax

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

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.

CPXML2591Syntax

~NodeRef();

NotationRef Interface

Table 2-22 summarizes the methods available through NotationRef interface.

NotationRef()

Class constructor.

NotationRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

NotationRef(
   const NotationRef< Node>& nref);

node_ref

nptr

CPXML2594Returns

(NotationRef) Node reference object

getPublicId()

Get public id.

CPXML2596Syntax

oratext* getPublicId() const;

CPXML2597Returns

(oratext*) public ID

getSystemId()

Get system id.

CPXML2599Syntax

oratext* getSystemId() const;

CPXML2600Returns

(oratext*) system ID

~NotationRef()

This is the default destructor.

CPXML2602Syntax

~NotationRef();

ProcessingInstructionRef Interface

Table 2-23 summarizes the methods available through ProcessingInstructionRef interface.

ProcessingInstructionRef()

Class constructor.

ProcessingInstructionRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

ProcessingInstructionRef(
   const ProcessingInstructionRef< Node>& nref);

node_ref

nptr

CPXML2605Returns

(ProcessingInstructionRef) Node reference object

getData()

Returns the content (data) of a processing instruction (in the data encoding). The content is the part from the first non-whitespace character after the target until the ending "?>".

CPXML2607Syntax

oratext* getData() const;

CPXML2608Returns

(oratext*) processing instruction's data

getTarget()

Returns a processing instruction's target string. The target is the first token following the markup that begins the ProcessingInstruction. All ProcessingInstructions must have a target, though the data part is optional.

CPXML2610Syntax

oratext* getTarget() const;

CPXML2611Returns

(oratext*) processing instruction's target

setData()

Sets processing instruction's data (content), which must be in the data encoding. It is not permitted to set the data to NULL. The new data is not verified, converted, or checked.

CPXML2613Syntax

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

data

~ProcessingInstructionRef()

This is the default destructor.

CPXML2615Syntax

~ProcessingInstructionRef();

Range Interface

Table 2-24 summarizes the methods available through Range interface.

CompareBoundaryPoints()

Compares boundary points.

CPXML2618Syntax

CompareHowCode compareBoundaryPoints( 
   unsigned short how,
   Range< Node>* sourceRange)
throw (DOMException);

how

sourceRange

CPXML2619Returns

(CompareHowCode) result of comparison

cloneContent()

Makes a clone of the node, including its children.

CPXML2621Syntax

Node* cloneContents() throw (DOMException);

CPXML2622Returns

(Node*) subtree cloned

cloneRange()

Clones a range of nodes.

CPXML2624Syntax

Range< Node>* cloneRange();

CPXML2625Returns

(Range< Node>*) new cloned range

deleteContents()

Deletes contents of the node.

CPXML2627Syntax

void deleteContents() throw (DOMException);

detach()

Invalidates the range. It is not recommended to use this method since it leaves the object in invalid state. The preferable way is to call the destructor.

CPXML2629Syntax

void detach();

extractContent()

Extract the node.

CPXML2631Syntax

Node* extractContents() throw (DOMException);

CPXML2632Returns

(Node*) subtree extracted

getCollapsed()

Checks if the range is collapsed.

CPXML2634Syntax

boolean getCollapsed() const;

CPXML2635Returns

(boolean) TRUE if the range is collapsed, FALSE otherwise

getCommonAncestorContainer()

Get the deepest common ancestor of the node.

CPXML2637Syntax

Node* getCommonAncestorContainer() const;

CPXML2638Returns

(Node*) common ancestor node

getEndContainer()

Gets the container node.

CPXML2640Syntax

Node* getEndContainer() const;

CPXML2641Returns

(Node*) end container node

getEndOffset()

Get offset of the end point.

CPXML2643Syntax

long getEndOffset() const;

CPXML2644Returns

(long) offset

getStartContainer()

Get start container node.

CPXML2646Syntax

Node* getStartContainer() const;

CPXML2647Returns

(Node*) start container node

getStartOffset()

Get offset of the start point.

CPXML2649Syntax

long getStartOffset() const;

CPXML2650Returns

(long) offset

insertNode()

Inserts a node.

CPXML2652Syntax

void insertNode( 
   NodeRef< Node>& newNode)
throw (RangeException, DOMException);

newNode

selectNodeContent()

Selects node content by its reference.

CPXML2654Syntax

void selectNodeContent( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

selectNode()

Selects a node.

CPXML2656Syntax

void selectNode( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

setEnd()

Sets an end point.

CPXML2658Syntax

void setEnd( 
   NodeRef< Node>& refNode, 
   long offset)
throw (RangeException, DOMException);

refNode

offset

setEndAfter()

Sets the end pointer after a specified node.

CPXML2660Syntax

void setEndAfter( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

setEndBefore()

Set the end before a specified node.

CPXML2662Syntax

void setEndBefore( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

setStart()

Sets start point.

CPXML2664Syntax

void setStart( 
   NodeRef< Node>& refNode, 
   long offset)
throw (RangeException, DOMException);

refNode

offset

setStartAfter()

Sets start pointer after a specified node.

CPXML2666Syntax

void setStartAfter( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

setStartBefore()

Sets start pointer before a specified node.

CPXML2668Syntax

void setStartBefore( 
   NodeRef< Node>& refNode)
throw (RangeException);

refNode

surroundContents()

Makes a node into a child of the specified node.

CPXML2670Syntax

void surroundContents( 
   NodeRef< Node>& newParent)
throw (RangeException, DOMException);

newParent

toString()

Converts an item into a string.

CPXML2672Syntax

oratext* toString();

CPXML2673Returns

(oratext*) string representation of the range

RangeException Interface

Table 2-25 summarizes the methods available through RangeException interface.

getCode()

Gets Oracle XML error code embedded in the exception. Virtual member function inherited from XmlException.

CPXML2676Syntax

virtual unsigned getCode() const = 0;

CPXML2677Returns

(unsigned) numeric error code (0 on success)

getMesLang()

Gets the current language encoding of error messages. Virtual member function inherited from XmlException.

CPXML2679Syntax

virtual oratext* getMesLang() const = 0;

CPXML2680Returns

(oratext*) Current language (encoding) of error messages

getMessage()

Get XML error message. Virtual member function inherited from XmlException.

CPXML2682Syntax

virtual oratext* getMessage() const = 0;

CPXML2683Returns

(oratext *) Error message

getRangeCode()

This is a virtual member function that defines a prototype for implementation defined member functions returning Range exception codes, defined in RangeExceptionCode, of the exceptional situations during execution.

CPXML2685Syntax

virtual RangeExceptionCode getRangeCode() const = 0;

CPXML2686Returns

(RangeExceptionCode) exception code

TextRef Interface

Table 2-26 summarizes the methods available through TextRef interface.

TextRef()

Class constructor.

TextRef(
   const NodeRef< Node>& node_ref,
   Node* nptr);

TextRef(
   const TextRef< Node>& nref);

node_ref

nptr

CPXML2689Returns

(TextRef) Node reference object

splitText()

Splits a single text node into two text nodes; the original data is split between them. The offset is zero-based, and is in characters, not bytes. The original node is retained, its data is just truncated. A new text node is created which contains the remainder of the original data, and is inserted as the next sibling of the original. The new text node is returned.

CPXML2691Syntax

Node* splitText( 
   ub4 offset) 
throw (DOMException);

offset

CPXML2692Returns

(Node*) new node

~TextRef()

This is the default destructor.

CPXML2694Syntax

~TextRef();

TreeWalker Interface

Table 2-27 summarizes the methods available through TreeWalker interface.

adjustCtx()

Attaches this tree walker to the context associated with a given node reference

CPXML2697Syntax

void adjustCtx( 
   NodeRef< Node>& nref);

nref

firstChild()

Get the first child of the current node.

CPXML2699Syntax

Node* firstChild();

CPXML2700Returns

(Node*) pointer to first child node

lastChild()

Get the last child of the current node.

CPXML2702Syntax

Node* lastChild();

CPXML2703Returns

(Node*) pointer to last child node

nextNode()

Get the next node.

CPXML2705Syntax

Node* nextNode();

CPXML2706Returns

(Node*) pointer to the next node

nextSibling()

Get the next sibling node.

CPXML2708Syntax

Node* nextSibling();

CPXML2709Returns

(Node*) pointer to the next sibling node

parentNode()

Get the parent of the current node.

CPXML2711Syntax

Node* parentNode();

CPXML2712Returns

(Node*) pointer to the parent node

previousNode()

Get the previous node.

CPXML2714Syntax

Node* previousNode();

CPXML2715Returns

(Node*) pointer to previous node

previousSibling()

Get the previous sibling node.

CPXML2717Syntax

Node* previousSibling();

CPXML2718Returns

(Node*) pointer to the previous sibling node