Logo Search packages:      
Sourcecode: poco version File versions  Download package

Element.h

//
// Element.h
//
// $Id: //poco/1.2/XML/include/Poco/DOM/Element.h#2 $
//
// Library: XML
// Package: DOM
// Module:  DOM
//
// Definition of the DOM Element class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// Permission is hereby granted, free of charge, to any person or organization
// obtaining a copy of the software and accompanying documentation covered by
// this license (the "Software") to use, reproduce, display, distribute,
// execute, and transmit the Software, and to prepare derivative works of the
// Software, and to permit third-parties to whom the Software is furnished to
// do so, all subject to the following:
// 
// The copyright notices in the Software and this entire statement, including
// the above license grant, this restriction and the following disclaimer,
// must be included in all copies of the Software, in whole or in part, and
// all derivative works of the Software, unless such copies or derivative
// works are solely in the form of machine-executable object code generated by
// a source language processor.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//


#ifndef DOM_Element_INCLUDED
#define DOM_Element_INCLUDED


#include "Poco/XML/XML.h"
#include "Poco/DOM/AbstractContainerNode.h"
#include "Poco/XML/Name.h"


namespace Poco {
namespace XML {


class Attr;
class NodeList;
class Document;


00057 class XML_API Element: public AbstractContainerNode
      /// 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. 
{
public:
      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* 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.

      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.

      // DOM Level 2
      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.

      const XMLString& namespaceURI() const;
      XMLString prefix() const;
      const XMLString& localName() const;
      bool hasAttributes() const;

      // Non-standard extensions
      XMLString innerText() const;

      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.
      
      // Node
      const XMLString& nodeName() const;
      NamedNodeMap* attributes() const;
      unsigned short nodeType() const;

protected:
      Element(Document* pOwnerDocument, const XMLString& namespaceURI, const XMLString& localName, const XMLString& qname);
      Element(Document* pOwnerDocument, const Element& elem);
      ~Element();

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

      void dispatchNodeRemovedFromDocument();
      void dispatchNodeInsertedIntoDocument();

private:
      const Name& _name;
      Attr*       _pFirstAttr;

      friend class Attr;
      friend class Document;
      friend class AttrMap;
};


//
// inlines
//
inline const XMLString& Element::tagName() const
{
      return _name.qname();
}


} } // namespace Poco::XML


#endif // DOM_Element_INCLUDED

Generated by  Doxygen 1.6.0   Back to index