submitted 1.2.0

XML/include/Poco/DOM/Element.h

@@ -0,0 +1,218 @@
+//
+// Element.h
+//
+// $Id: //poco/1.2/XML/include/Poco/DOM/Element.h#1 $
+//
+// 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;
+
+
+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.
+
+	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.
+
+	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.
+		
+	// 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