Skip Headers

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

Previous Next  

Element Interface

Table 4-5 summarizes the methods of available through the Element Interface.

Table 4-5 Summary of Element Methods; DOM Package

Function Summary
XmlDomGetAttr
Return attribute's value given its name.
XmlDomGetAttrNS
Return attribute's value given its URI and local name.
XmlDomGetAttrNode
Get attribute by name.
XmlDomGetAttrNodeNS
Get attribute by name (namespace aware version).
XmlDomGetChildrenByTag
Get children of element with given tag name (non-namespace aware).
XmlDomGetChildrenByTagNS
Get children of element with tag name (namespace aware version).
XmlDomGetDocElemsByTag
Obtain doc elements.
XmlDomGetDocElemsByTagNS
Obtain doc elements (namespace aware version).
XmlDomGetTag
Return an element node's tag name.
XmlDomHasAttr
Does named attribute exist?
XmlDomHasAttrNS
Does named attribute exist (namespace aware version)?
XmlDomRemoveAttr
Remove attribute with specified name.
XmlDomRemoveAttrNS
Remove attribute with specified URI and local name.
XmlDomRemoveAttrNode
Remove attribute node.
XmlDomSetAttr
Set new attribute for element.
XmlDomSetAttrNS
Set new attribute for element (namespace aware version).
XmlDomSetAttrNode
Set attribute node.
XmlDomSetAttrNodeNS
Set attribute node (namespace aware version).


XmlDomGetAttr

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. If the element does not have an attribute with the given name, NULL is returned.


Syntax
oratext* XmlDomGetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name


Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNS

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. If the element does not have an attribute with the given name, NULL is returned.


Syntax
oratext* XmlDomGetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding


Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNode

Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL.


Syntax
xmlattrnode* XmlDomGetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding


Returns

(xmlattrnode *) attribute with the specified name [or NULL]


XmlDomGetAttrNodeNS

Returns an element's attribute specified by URI and localname. If the node is not an element or the named attribute does not exist, returns NULL.


Syntax
xmlattrnode* XmlDomGetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding


Returns

(xmlattrnode *) attribute node with the given URI/local name [or NULL]


XmlDomGetChildrenByTag

Returns a list of children of an element with the given tag name, in the order in which they would be encountered in a preorder traversal of the tree. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetChildrenByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.


Syntax
xmlnodelist* XmlDomGetChildrenByTag(
   xmlctx *xctx, 
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all


Returns

(xmlnodelist *) node list of matching children


XmlDomGetChildrenByTagNS

Returns a list of children of an element with the given URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. The URI and local name should be in the data encoding. The special name "*" matches all URIs or tag names; a NULL name matches nothing. Note that names are case sensitive. See XmlDomGetChildrenByTag for the non-namespace version. The returned list can be freed with XmlDomFreeNodeList.


Syntax
xmlnodelist* XmlDomGetChildrenByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

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


Returns

(xmlnodelist *) node list of matching children


XmlDomGetElemsByTag

Returns a list of all elements (in the document tree rooted at the root node) with a given tag 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 tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.


Syntax
xmlnodelist* XmlDomGetElemsByTag(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all


Returns

(xmlnodelist *) node list of matching elements


XmlDomGetElemsByTagNS

Returns a list of all elements (in the document tree rooted at the root node) with a given URI and localname, 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 tag name should be in the data encoding. The special name "**" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. The returned list can be freed with XmlDomFreeNodeList.


Syntax
xmlnodelist* XmlDomGetElemsByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
namespace URI to match; data encoding; * for all
local
IN
local name to match; data encoding; * for all


Returns

(xmlnodelist *) node list of matching elements


XmlDomGetTag

Returns the tagName} of a node, which is the same as its name. DOM 1.0 states "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy."


Syntax
oratext* XmlDomGetTag(
   xmlctx *xctx,
   xmlelemnode *elem)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node


Returns

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


See Also:

XmlDomGetNodeName


XmlDomHasAttr

Determines if an element has an attribute with the given name. Returns TRUE if so, FALSE if not.


Syntax
boolean XmlDomHasAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node
name
IN
attribute's name; data encoding


Returns

(boolean) TRUE if element has attribute with given name


See Also:

XmlDomHasAttrNS


XmlDomHasAttrNS

Determines if an element has an attribute with the given URI and localname. Returns TRUE if so, FALSE if not.


Syntax
boolean XmlDomHasAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding


Returns

(boolean) TRUE if element has attribute with given URI/localname


See Also:

XmlDomHasAttr


XmlDomRemoveAttr

Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.


Syntax
void XmlDomRemoveAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding


XmlDomRemoveAttrNS

Removes an attribute (specified by URI and local name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.


Syntax
void XmlDomRemoveAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI
local
IN
attribute's local name


XmlDomRemoveAttrNode

Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE). Returns the removed attribute on success, else NULL.


Syntax
xmlattrnode* XmlDomRemoveAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *oldAttr)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
oldAtrr
IN
attribute node to remove


Returns

(xmlattrnode *) replaced attribute node [or NULL]


See Also:

XmlDomRemoveAttr


XmlDomSetAttr

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. The attribute's specified flag will be set.


Syntax
void XmlDomSetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name,
   oratext *value)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNS

Creates a new attribute for an element with the given URI, localname 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.

The attribute's specified flag will be set.


Syntax
void XmlDomSetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri, 
   oratext *qname,
   oratext *value)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
qname
IN
attribute's qualified name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNode

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


Syntax
xmlattrnode* XmlDomSetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add


Returns

(xmlattrnode *) replaced attribute node (or NULL)


XmlDomSetAttrNodeNS

Adds a new attribute to an element. If an attribute with newNode's URI and localname already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.


Syntax
xmlattrnode* XmlDomSetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr)

Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add


Returns

(xmlattrnode *) replaced attribute node [or NULL]