class Poco::XML::Element

Overview

The Element interface represents an element in an XML document. More…

#include <Element.h>

class Element: public Poco::XML::AbstractContainerNode
{
public:
    // methods

    const XMLString&
    tagName() const;

    const XMLString&
    getAttribute(const XMLString& name) const;

    void
    setAttribute(
        const XMLString& name,
        const XMLString& value
        );

    void
    removeAttribute(const XMLString& name);

    Attr*
    getAttributeNode(const XMLString& name) const;

    Attr*
    setAttributeNode(Attr* newAttr);

    Attr*
    addAttributeNodeNP(
        Attr* oldAttr,
        Attr* newAttr
        );

    Attr*
    removeAttributeNode(Attr* oldAttr);

    NodeList*
    getElementsByTagName(const XMLString& name) const;

    virtual
    void
    normalize();

    const XMLString&
    getAttributeNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        ) const;

    void
    setAttributeNS(
        const XMLString& namespaceURI,
        const XMLString& qualifiedName,
        const XMLString& value
        );

    void
    removeAttributeNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        );

    Attr*
    getAttributeNodeNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        ) const;

    Attr*
    setAttributeNodeNS(Attr* newAttr);

    bool
    hasAttribute(const XMLString& name) const;

    bool
    hasAttributeNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        ) const;

    NodeList*
    getElementsByTagNameNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        ) const;

    virtual
    const XMLString&
    namespaceURI() const;

    virtual
    XMLString
    prefix() const;

    virtual
    const XMLString&
    localName() const;

    virtual
    bool
    hasAttributes() const;

    virtual
    XMLString
    innerText() const;

    Element*
    getChildElement(const XMLString& name) const;

    Element*
    getChildElementNS(
        const XMLString& namespaceURI,
        const XMLString& localName
        ) const;

    Element*
    getElementById(
        const XMLString& elementId,
        const XMLString& idAttribute
        ) const;

    Element*
    getElementByIdNS(
        const XMLString& elementId,
        const XMLString& idAttributeURI,
        const XMLString& idAttributeLocalName
        ) const;

    virtual
    const XMLString&
    nodeName() const;

    virtual
    NamedNodeMap*
    attributes() const;

    virtual
    unsigned short
    nodeType() const;

protected:
    // construction

    Element(
        Document* pOwnerDocument,
        const XMLString& namespaceURI,
        const XMLString& localName,
        const XMLString& qname
        );

    Element(
        Document* pOwnerDocument,
        const Element& elem
        );

    // methods

    virtual
    Node*
    copyNode(
        bool deep,
        Document* pOwnerDocument
        ) const;

    virtual
    void
    dispatchNodeRemovedFromDocument();

    virtual
    void
    dispatchNodeInsertedIntoDocument();
};

Inherited Members

public:
    // typedefs

    typedef Poco::XML::NamespaceSupport NSMap;

    // enums

    enum
    {
        ELEMENT_NODE                = 1,
        ATTRIBUTE_NODE,
        TEXT_NODE,
        CDATA_SECTION_NODE,
        ENTITY_REFERENCE_NODE,
        ENTITY_NODE,
        PROCESSING_INSTRUCTION_NODE,
        COMMENT_NODE,
        DOCUMENT_NODE,
        DOCUMENT_TYPE_NODE,
        DOCUMENT_FRAGMENT_NODE,
        NOTATION_NODE,
    };

    // methods

    void
    duplicate() const;

    void
    release() const;

    virtual
    void
    autoRelease() = 0;

    virtual
    void
    addEventListener(
        const XMLString& type,
        EventListener* listener,
        bool useCapture
        ) = 0;

    virtual
    void
    removeEventListener(
        const XMLString& type,
        EventListener* listener,
        bool useCapture
        ) = 0;

    virtual
    bool
    dispatchEvent(Event* evt) = 0;

    virtual
    const XMLString&
    nodeName() const = 0;

    const XMLString&
    nodeValue() const;

    virtual
    const XMLString&
    getNodeValue() const = 0;

    virtual
    void
    setNodeValue(const XMLString& value) = 0;

    virtual
    unsigned short
    nodeType() const = 0;

    virtual
    Node*
    parentNode() const = 0;

    virtual
    NodeList*
    childNodes() const = 0;

    virtual
    Node*
    firstChild() const = 0;

    virtual
    Node*
    lastChild() const = 0;

    virtual
    Node*
    previousSibling() const = 0;

    virtual
    Node*
    nextSibling() const = 0;

    virtual
    NamedNodeMap*
    attributes() const = 0;

    virtual
    Document*
    ownerDocument() const = 0;

    virtual
    Node*
    insertBefore(
        Node* newChild,
        Node* refChild
        ) = 0;

    virtual
    Node*
    replaceChild(
        Node* newChild,
        Node* oldChild
        ) = 0;

    virtual
    Node*
    removeChild(Node* oldChild) = 0;

    virtual
    Node*
    appendChild(Node* newChild) = 0;

    virtual
    bool
    hasChildNodes() const = 0;

    virtual
    Node*
    cloneNode(bool deep) const = 0;

    virtual
    void
    normalize() = 0;

    virtual
    bool
    isSupported(
        const XMLString& feature,
        const XMLString& version
        ) const = 0;

    virtual
    const XMLString&
    namespaceURI() const = 0;

    virtual
    XMLString
    prefix() const = 0;

    virtual
    const XMLString&
    localName() const = 0;

    virtual
    bool
    hasAttributes() const = 0;

    virtual
    XMLString
    innerText() const = 0;

    virtual
    Node*
    getNodeByPath(const XMLString& path) const = 0;

    virtual
    Node*
    getNodeByPathNS(
        const XMLString& path,
        const NSMap& nsMap
        ) const = 0;

    virtual
    const XMLString&
    nodeName() const;

    virtual
    const XMLString&
    getNodeValue() const;

    virtual
    void
    setNodeValue(const XMLString& value);

    virtual
    Node*
    parentNode() const;

    virtual
    NodeList*
    childNodes() const;

    virtual
    Node*
    firstChild() const;

    virtual
    Node*
    lastChild() const;

    virtual
    Node*
    previousSibling() const;

    virtual
    Node*
    nextSibling() const;

    virtual
    NamedNodeMap*
    attributes() const;

    virtual
    Document*
    ownerDocument() const;

    virtual
    Node*
    insertBefore(
        Node* newChild,
        Node* refChild
        );

    virtual
    Node*
    replaceChild(
        Node* newChild,
        Node* oldChild
        );

    virtual
    Node*
    removeChild(Node* oldChild);

    virtual
    Node*
    appendChild(Node* newChild);

    virtual
    bool
    hasChildNodes() const;

    virtual
    Node*
    cloneNode(bool deep) const;

    virtual
    void
    normalize();

    virtual
    bool
    isSupported(
        const XMLString& feature,
        const XMLString& version
        ) const;

    virtual
    const XMLString&
    namespaceURI() const;

    virtual
    XMLString
    prefix() const;

    virtual
    const XMLString&
    localName() const;

    virtual
    bool
    hasAttributes() const;

    virtual
    void
    addEventListener(
        const XMLString& type,
        EventListener* listener,
        bool useCapture
        );

    virtual
    void
    removeEventListener(
        const XMLString& type,
        EventListener* listener,
        bool useCapture
        );

    virtual
    bool
    dispatchEvent(Event* evt);

    virtual
    XMLString
    innerText() const;

    virtual
    Node*
    getNodeByPath(const XMLString& path) const;

    virtual
    Node*
    getNodeByPathNS(
        const XMLString& path,
        const NSMap& nsMap
        ) const;

    virtual
    void
    autoRelease();

    virtual
    Node*
    firstChild() const;

    virtual
    Node*
    lastChild() const;

    virtual
    Node*
    insertBefore(
        Node* newChild,
        Node* refChild
        );

    virtual
    Node*
    replaceChild(
        Node* newChild,
        Node* oldChild
        );

    virtual
    Node*
    removeChild(Node* oldChild);

    virtual
    Node*
    appendChild(Node* newChild);

    virtual
    bool
    hasChildNodes() const;

    virtual
    bool
    hasAttributes() const;

    virtual
    Node*
    getNodeByPath(const XMLString& path) const;

    virtual
    Node*
    getNodeByPathNS(
        const XMLString& path,
        const NSMap& nsMap
        ) const;

protected:
    // fields

    static const XMLString EMPTY_STRING;

    // methods

    virtual
    Node*
    copyNode(
        bool deep,
        Document* pOwnerDocument
        ) const = 0;

    virtual
    bool
    events() const;

    virtual
    bool
    eventsSuspended() const;

    void
    captureEvent(Event* evt);

    void
    bubbleEvent(Event* evt);

    void
    dispatchSubtreeModified();

    void
    dispatchNodeInserted();

    void
    dispatchNodeRemoved();

    virtual
    void
    dispatchNodeRemovedFromDocument();

    virtual
    void
    dispatchNodeInsertedIntoDocument();

    void
    dispatchAttrModified(
        Attr* pAttr,
        MutationEvent::AttrChangeType changeType,
        const XMLString& prevValue,
        const XMLString& newValue
        );

    void
    dispatchCharacterDataModified(
        const XMLString& prevValue,
        const XMLString& newValue
        );

    void
    setOwnerDocument(Document* pOwnerDocument);

    virtual
    void
    dispatchNodeRemovedFromDocument();

    virtual
    void
    dispatchNodeInsertedIntoDocument();

    bool
    hasAttributeValue(
        const XMLString& name,
        const XMLString& value,
        const NSMap* pNSMap
        ) const;

    static
    const Node*
    findNode(
        XMLString::const_iterator& it,
        const XMLString::const_iterator& end,
        const Node* pNode,
        const NSMap* pNSMap
        );

    static
    const Node*
    findElement(
        const XMLString& name,
        const Node* pNode,
        const NSMap* pNSMap
        );

    static
    const Node*
    findElement(
        int index,
        const Node* pNode,
        const NSMap* pNSMap
        );

    static
    const Node*
    findElement(
        const XMLString& attr,
        const XMLString& value,
        const Node* pNode,
        const NSMap* pNSMap
        );

    static
    const Attr*
    findAttribute(
        const XMLString& name,
        const Node* pNode,
        const NSMap* pNSMap
        );

    static
    bool
    namesAreEqual(
        const Node* pNode1,
        const Node* pNode2,
        const NSMap* pNSMap
        );

    static
    bool
    namesAreEqual(
        const Node* pNode,
        const XMLString& name,
        const NSMap* pNSMap
        );

Detailed Documentation

The Element interface represents an element in an XML document.

Elements may have attributes associated with them; since the Element interface inherits from Node, the generic Node interface attribute attributes may be used to retrieve the set of all attributes for an element. There are methods on the Element interface to retrieve either an Attr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, an Attr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value.

Methods

const XMLString&
tagName() const

Returns the name of the element.

For example, in

<elementExample id="demo">
        ...
</elementExample>

tagName has the value “elementExample”. Note that this is case-preserving in XML, as are all of the operations of the DOM.

const XMLString&
getAttribute(const XMLString& name) const

Retrieves an attribute value by name.

Returns the attribute’s value, if the attribute exists, or an empty string otherwise.

void
setAttribute(
    const XMLString& name,
    const XMLString& value
    )

Adds a new attribute.

If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out.

void
removeAttribute(const XMLString& name)

Removes an attribute by name.

Attr*
getAttributeNode(const XMLString& name) const

Retrieves an Attr node by name.

Attr*
setAttributeNode(Attr* newAttr)

Adds a new attribute.

If an attribute with that name is already present in the element, it is replaced by the new one.

Attr*
addAttributeNodeNP(
    Attr* oldAttr,
    Attr* newAttr
    )

For internal use only.

Adds a new attribute after oldAttr. If oldAttr is 0, newAttr is set as first attribute. Returns newAttr. Does not fire any events.

Attr*
removeAttributeNode(Attr* oldAttr)

Removes the specified attribute.

NodeList*
getElementsByTagName(const XMLString& name) const

Returns a NodeList of all descendant elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the Element tree.

The special name “*” matches all tags.

The returned NodeList must be released with a call to release() when no longer needed.

virtual
void
normalize()

Puts all Text nodes in the full depth of the sub-tree underneath this Element, including attribute nodes, into a “normal” form where only markup (e.g., tags, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are no adjacent Text nodes.

This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on a particular document tree structure are to be used.

Note: In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

const XMLString&
getAttributeNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    ) const

Retrieves an attribute value by name.

Returns the attribute’s value, if the attribute exists, or an empty string otherwise.

void
setAttributeNS(
    const XMLString& namespaceURI,
    const XMLString& qualifiedName,
    const XMLString& value
    )

Adds a new attribute.

If an attribute with that name is already present in the element, its value is changed to be that of the value parameter.

void
removeAttributeNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    )

Removes an attribute by name.

Attr*
getAttributeNodeNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    ) const

Retrieves an Attr node by name.

Attr*
setAttributeNodeNS(Attr* newAttr)

Adds a new attribute.

If an attribute with that name is already present in the element, it is replaced by the new one.

bool
hasAttribute(const XMLString& name) const

Returns true if and only if the element has the specified attribute.

bool
hasAttributeNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    ) const

Returns true if and only if the element has the specified attribute.

NodeList*
getElementsByTagNameNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    ) const

Returns a NodeList of all the descendant Elements with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of this Element tree.

The special value “*” matches all namespaces, or local names respectively.

The returned NodeList must be released with a call to release() when no longer needed.

virtual
const XMLString&
namespaceURI() const

Returns the namespace URI of the node.

This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.

For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always the empty string.

virtual
XMLString
prefix() const

Returns the namespace prefix from the qualified name of the node.

virtual
const XMLString&
localName() const

Returns the local name of the node.

virtual
bool
hasAttributes() const

Returns whether this node (if it is an element) has any attributes.

virtual
XMLString
innerText() const

Returns a string containing the concatenated values of the node and all its child nodes.

This method is not part of the W3C Document Object Model.

Element*
getChildElement(const XMLString& name) const

Returns the first child element with the given name, or null if such an element does not exist.

This method is an extension to the W3C Document Object Model.

Element*
getChildElementNS(
    const XMLString& namespaceURI,
    const XMLString& localName
    ) const

Returns the first child element with the given namespaceURI and localName, or null if such an element does not exist.

This method is an extension to the W3C Document Object Model.

Element*
getElementById(
    const XMLString& elementId,
    const XMLString& idAttribute
    ) const

Returns the first Element whose ID attribute (given in idAttribute) has the given elementId.

If no such element exists, returns null.

This method is an extension to the W3C Document Object Model.

Element*
getElementByIdNS(
    const XMLString& elementId,
    const XMLString& idAttributeURI,
    const XMLString& idAttributeLocalName
    ) const

Returns the first Element whose ID attribute (given in idAttributeURI and idAttributeLocalName) has the given elementId.

If no such element exists, returns null.

This method is an extension to the W3C Document Object Model.

virtual
const XMLString&
nodeName() const

Returns the name of this node, depending on its type.

virtual
NamedNodeMap*
attributes() const

Returns a NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.

The returned NamedNodeMap must be released with a call to release() when no longer needed.

virtual
unsigned short
nodeType() const

Returns a code representing the type of the underlying object.

Table of Contents

Previous topic

Next topic

class Poco::XML::Element

Overview

Inherited Members

Detailed Documentation

Methods