Skip Headers

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

## 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`]

See Also: XmlDomGetAttrNS, XmlDomGetAttrs, XmlDomGetAttrNode

### 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`]

See Also: XmlDomGetAttr, XmlDomGetAttrs, XmlDomGetAttrNode

### 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`]

See Also: XmlDomGetAttrNodeNS, XmlDomGetAttr

### 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`]

See Also: XmlDomGetAttrNode, XmlDomGetAttr

### 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

See Also: XmlDomGetChildrenByTagNS, XmlDomFreeNodeList

### 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

See Also: XmlDomGetChildrenByTag, XmlDomFreeNodeList

### 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

See Also: XmlDomGetElemsByTagNS, XmlDomFreeNodeList

### 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

See Also: XmlDomGetDocElemsByTag, XmlDomFreeNodeList

### 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

See Also: XmlDomRemoveAttrNS, XmlDomRemoveAttrNode

### 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

See Also: XmlDomRemoveAttr, XmlDomRemoveAttrNode

### 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

See Also: XmlDomSetAttrNS, XmlDomCreateAttr, XmlDomSetAttrValue, XmlDomRemoveAttr

### 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

See Also: XmlDomSetAttr, XmlDomCreateAttr, XmlDomSetAttrValue, XmlDomRemoveAttr

### 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`)

See Also: XmlDomSetAttrNodeNS, XmlDomCreateAttr, XmlDomSetAttrValue

### 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`]

See Also: XmlDomSetAttrNode, XmlDomCreateAttr, XmlDomSetAttrValue