Skip Headers

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

Previous Next  

Document Interface

Table 4-3 summarizes the methods of available through the Document interface.

Table 4-3 Summary of Document Methods; DOM Package

Function Summary
XmlDomCreateAttr
Create attribute node.
XmlDomCreateAttrNS
Create attribute node with namespace information.
XmlDomCreateCDATA
Create CDATA node.
XmlDomCreateComment
Create comment node.
XmlDomCreateElem
Create an element node.
XmlDomCreateElemNS
Create an element node with namespace information.
XmlDomCreateEntityRef
Create entity reference node.
XmlDomCreateFragment
Create a document fragment.
XmlDomCreatePI
Create PI node.
XmlDomCreateText
Create text node.
XmlDomFreeString
Frees a string allocate by XmlDomSubstringData, and others.
XmlDomGetBaseURI
Returns the base URI for a document.
XmlDomGetDTD
Get DTD for document.
XmlDomGetDecl
Returns a document's XMLDecl information.
XmlDomGetDocElem
Get top-level element for document.
XmlDomGetDocElemByID
Get document element given ID.
XmlDomGetDocElemsByTag
Obtain document elements.
XmlDomGetDocElemsByTagNS
Obtain document elements (namespace aware version).
XmlDomGetLastError
Return last error code for document.
XmlDomGetSchema
Returns URI of schema associated with document.
XmlDomImportNode
Import a node from another DOM.
XmlDomIsSchemaBased
Indicate whether a schema is associated with a document.
XmlDomSaveString
Saves a string permanently in a document's memory pool.
XmlDomSaveString2
Saves a Unicode string permanently in a document's memory pool.
XmlDomSetDTD
Sets DTD for document.
XmlDomSetDocOrder
Set document order for all nodes.
XmlDomSetLastError
Sets last error code for document.
XmlDomSync
Synchronizes the persistent version of a document with its DOM.


XmlDomCreateAttr

Creates an attribute node with the given name and value (in the data encoding). Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

This is the non-namespace aware function (see XmlDomCreateAttrNS): 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.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

See XmlDomSetAttr which creates and adds an attribute in a single operation.

The name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlattrnode* XmlDomCreateAttr(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *name, 
   oratext *value)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
new node's name; data encoding; user control
value
IN
new node's value; data encoding; user control


Returns

(xmlattrnode *) new Attr node.


XmlDomCreateAttrNS

Creates an attribute node with the given namespace URI and qualified name; this is the namespace-aware version of XmlDomCreateAttr. Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. See XmlDomSetAttr which creates and adds an attribute in a single operation.

The URI, qualified name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlattrnode* XmlDomCreateAttrNS(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri, 
   oratext *qname,
   oratext *value)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
node's namespace URI; data encoding; user control
qname
IN
node's qualified name; data encoding; user control
value
IN
new node's value; data encoding; user control


Returns

(xmlattrnode *) new Attr node.


XmlDomCreateCDATA

Creates a CDATASection node with the given initial data (which should be in the data encoding). A CDATASection 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; it must be added to the DOM tree with XmlDomAppendChild and so on.

The CDATA is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlcdatanode* XmlDomCreateCDATA(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *data)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's CDATA; data encoding; user control


Returns

(xmlcdatanode *) new CDATA node.


XmlDomCreateComment

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 a Comment node is always "#comment".

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The comment data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlcommentnode* XmlDomCreateComment(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *data)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's comment; data encoding; user control


Returns

(xmlcommentnode *) new Comment node.


XmlDomCreateElem

Creates an element node with the given tag name (which should be in the data encoding). 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.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The tagname is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlelemnode* XmlDomCreateElem(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *tagname)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
tagname
IN
new node's name; data encoding; user control


Returns

(xmlelemnode *) new Element node.


XmlDomCreateElemNS

Creates an element with the given namespace URI and qualified name. 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, retrievable with XmlDomGetNodePrefix, XmlDomGetNodeLocal, and so on; the tagName will be the full qualified name.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

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
xmlelemnode* XmlDomCreateElemNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *qname)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
new node's namespace URI; data encoding, user control
qname
IN
new node's qualified name; data encoding; user control


Returns

(xmlelemnode *) new Element node.


XmlDomCreateEntityRef

Creates an EntityReference 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.

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

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

The entity reference name is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlentrefnode* XmlDomCreateEntityRef(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
name of referenced entity; data encoding; user control


Returns

(xmlentrefnode *) new EntityReference node.


XmlDomCreateFragment

Creates an empty DocumentFragment 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. See XmlDomInsertBefore, XmlDomReplaceChild, XmlDomAppendChild, and so on. The name of a fragment node is always "#document-fragment".


Syntax
xmlfragnode* XmlDomCreateFragment(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(xmlfragnode *) new empty DocumentFragment node


XmlDomCreatePI

Creates a ProcessingInstruction node with the given target and data (which should be in the data encoding). The data may be NULL initially, and may be changed later (with XmlDomSetPIData), but the target is required and cannot be changed. Note the target and data are not verified, converted, or checked. The name of a PI node is the same as the target.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The PI's target and data are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmlpinode* XmlDomCreatePI(
   xmlctx *xctx
   xmldocnode *doc, 
   oratext *target,
   oratext *data)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
target
IN
new node's target; data encoding; user control
data
IN
new node's data; data encoding; user control


Returns

(xmlpinode *) new PI node.


XmlDomCreateText

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 a fragment node is always "#text". New data for a Text node can be set with XmlDomSetNodeValue; see the CharacterData interface for editing methods.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The text data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.


Syntax
xmltextnode* XmlDomCreateText(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *data)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's text; data encoding; user control


Returns

(xmltextnode *) new Text node.


XmlDomFreeString

Frees the string allocated by XmlDomSubstringData or similar functions. Note that strings explicitly saved with XmlDomSaveString are not freeable individually.


Syntax
void XmlDomFreeString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
document where the string belongs
str
IN
string to free


XmlDomGetBaseURI

Returns the base URI for a document. Usually only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, but a base URI may have been set for them using XmlDomSetBaseURI, for the purposes of resolving relative URIs in inclusion.


Syntax
oratext *XmlDomGetBaseURI(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(oratext *) document's base URI [or NULL]


See Also:

XmlDomSetBaseURI


XmlDomGetDTD

Returns the DTD node associated with current document; if there is no DTD, returns NULL. The DTD cannot be edited, but its children may be retrieved with XmlDomGetChildNodes as for other node types.


Syntax
xmldtdnode* XmlDomGetDTD(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(xmldtdnode *) DTD node for document [or NULL]


XmlDomGetDecl

Returns the information from a document's XMLDecl. If there is no XMLDecl, returns XMLERR_NO_DECL. Returned are the XML version# ("1.0" or "2.0"), the specified encoding, and the standalone value. If encoding is not specified, NULL will be set. The standalone flag is three-state: < 0 if standalone was not specified, 0 if it was specified and FALSE, > 0 if it was specified and TRUE.


Syntax
xmlerr XmlDomGetDecl(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext **ver, 
   oratext **enc,
   sb4 *std)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
ver
OUT
XML version
enc
OUT
encoding specification
std
OUT
standalone specification


Returns

(xmlerr) XML error code, perhaps version/encoding/standalone set


XmlDomGetDocElem

Returns the root element (node) of the DOM tree, or NULL if there is none. Each document has only one uppermost Element node, called the root element. It is created after a document is parsed successfully, or manually by XmlDomCreateElem then XmlDomAppendChild, and so on.


Syntax
xmlelemnode* XmlDomGetDocElem(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(xmlelemnode *) root element [or NULL]


See Also:

XmlDomCreateElem


XmlDomGetDocElemByID

Returns the element node which has the given ID. If no such ID is defined, returns NULL. 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.

The given ID should be in the data encoding or it might not match.


Syntax
xmlelemnode* XmlDomGetDocElemByID(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *id)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
id
IN
element's unique ID; data encoding


Returns

(xmlelemnode *) matching element.


XmlDomGetDocElemsByTag

Returns a list of all elements in the document tree rooted at the root node with a given tag name, in document order (the order in which they would be encountered in a preorder traversal of the tree). If root is NULL, the entire document is searched.

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. See XmlDomGetElemsByTagNS for the namespace-aware version.

The list should be freed with XmlDomFreeNodeList 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.


Syntax
xmlnodelist* XmlDomGetDocElemsByTag(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
tagname to match; data encoding; * for all


Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetDocElemsByTagNS

Returns a list of all elements (in the document tree rooted at the given node) with a given namespace URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched.

The URI and local name should be in the data encoding. The special local 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. See XmlDomGetDocElemsByTag for the non-namespace aware version.

The list should be freed with XmlDomFreeNodeList 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.


Syntax
xmlnodelist* XmlDomGetDocElemsByTagNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
namespace URI to match; data encoding; * matches all
local
IN
local name to match; data encoding; * matches all


Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetLastError

Returns the error code of the last error which occurred in the given document.


Syntax
xmlerr XmlDomGetLastError(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(xmlerr) numeric error code, 0 if no error


XmlDomGetSchema

Returns URI of schema associated with document, if there is one, else returns NULL. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.


Syntax
oratext* XmlDomGetSchema(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(oratext *) Schema URI or NULL


XmlDomImportNode

Imports a node from one Document to another. The new node is an orphan and has no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. 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.

As with XmlDomCloneNode, 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.

Document and DocumentType nodes cannot be imported. Imported attributes will have their specified flags set to TRUE. Elements will have only their specified attributes imported; non-specified (default) attributes are omitted. New default attributes (for the destination document) are then added.


Syntax
xmlnode* XmlDomImportNode(
   xmlctx *xctx,
   xmldocnode *doc, 
   xmlctx *nctx,
   xmlnode *node,
   boolean deep)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
nctx
IN
XML context of imported node
node
IN
node to import
deep
IN
TRUE to import the subtree recursively


Returns

(xmlnode *) newly imported node (in this Document).


See Also:

XmlDomCloneNode


XmlDomIsSchemaBased

Returns flag specifying whether there is a schema associated with this document. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.


Syntax
boolean XmlDomIsSchemaBased(
   xmlctx *xctx,
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(boolean) TRUE if there is a schema associated with the document


XmlDomSaveString

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is freed. Works on single-byte or multibyte encodings; for Unicode strings, use XmlDomSaveString2.


Syntax
oratext* XmlDomSaveString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
str
IN
string to save; data encoding; single- or multi-byte only


Returns

(oratext *) saved copy of string


XmlDomSaveString2

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is free. Works on Unicode strings only; for single-byte or multibyte strings, use XmlDomSaveString.


Syntax
ub2* XmlDomSaveString2(
   xmlctx *xctx,
   xmldocnode *doc,
   ub2 *ustr)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
ustr
IN
string to save; data encoding; Unicode only


Returns

(ub2 *) saved copy of string


XmlDomSetBaseURI

Only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, so this API is used to set a base URI, for the purposes of relative URI resolution in includes. The base URI should be in the data encoding, and a copy will be made.


Syntax
xmlerr XmlDomSetBaseURI(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
base URI to set; data encoding


Returns

(xmlerr) XML error code


See Also:

XmlDomGetBaseURI


XmlDomSetDTD

Sets the DTD for document. Note this call may only be used for a blank document, before any parsing has taken place. A single DTD can be set for multiple documents, so when a document with a set DTD is freed, the set DTD is not also freed.


Syntax
xmlerr XmlDomSetDTD(
   xmlctx *xctx, 
   xmldocnode *doc, 
   xmldtdnode *dtdnode)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
dtdnode
IN
DocumentType node to set


Returns

(xmlerr) numeric error code, 0 on success


XmlDomSetDocOrder

Sets the document order for each node in the current document. Must be called once on the final document before XSLT processing can occur. Note this is called automatically by the XSLT processor, so ordinarily the user need not make this call.


Syntax
ub4 XmlDomSetDocOrder(
   xmlctx *xctx, 
   xmldocnode *doc,
   ub4 start_id)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
start_id
IN
string ID number


Returns

(ub4) highest ordinal assigned


XmlDomSetLastError

Sets the Last Error code for the given document. If doc is NULL, sets the error code for the XML context.


Syntax
xmlerr XmlDomSetLastError(
   xmlctx *xctx, 
   xmldocnode *doc,
   xmlerr errcode)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
errcode
IN
error code to set, 0 to clear error


Returns

(xmlerr) original error code


XmlDomSync

Causes a modified DOM to be written back out to its original source, synchronizing the persistent store and in-memory versions.


Syntax
xmlerr XmlDomSync(
   xmlctx *xctx, 
   xmldocnode *doc)

Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node


Returns

(xmlerr) numeric error code, 0 on success