//
// Element.h
//
// $Id: //poco/Main/XML/include/DOM/Element.h#5 $
//
// Definition of the DOM Element class.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
// 
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef DOM_Element_INCLUDED
#define DOM_Element_INCLUDED


#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef DOM_AbstractContainerNode_INCLUDED
#include "DOM/AbstractContainerNode.h"
#endif
#ifndef XML_Name_INCLUDED
#include "XML/Name.h"
#endif


XML_BEGIN


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
	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();
}


XML_END


#endif // DOM_Element_INCLUDED