//
// Node.h
//
// $Id: //poco/Main/XML/include/DOM/Node.h#5 $
//
// Definition of the DOM Node interface.
//
// 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_Node_INCLUDED
#define DOM_Node_INCLUDED


#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef DOM_EventTarget_INCLUDED
#include "DOM/EventTarget.h"
#endif
#ifndef XML_XMLString_INCLUDED
#include "XML/XMLString.h"
#endif


XML_BEGIN


class NamedNodeMap;
class Document;
class NodeList;


class XML_API Node: public EventTarget
	/// The Node interface is the primary datatype for the entire Document Object
	/// Model. It represents a single node in the document tree. While all objects
	/// implementing the Node interface expose methods for dealing with children,
	/// not all objects implementing the Node interface may have children. For
	/// example, Text nodes may not have children, and adding children to such
	/// nodes results in a DOMException being raised.
	/// 
	/// The attributes nodeName, nodeValue and attributes are included as a mechanism
	/// to get at node information without casting down to the specific derived
	/// interface. In cases where there is no obvious mapping of these attributes
	/// for a specific nodeType (e.g., nodeValue for an Element or attributes for
	/// a Comment), this returns null. Note that the specialized interfaces may
	/// contain additional and more convenient mechanisms to get and set the relevant
	/// information.
	///
	/// This implementation differs in some ways from the W3C DOM recommendations.
	/// For example, the DOM specifies that some methods can return null strings.
	/// Instead of null strings, this implementation always returns empty strings.
{
public:
	enum
	{
		ELEMENT_NODE = 1,             /// The node is an Element.
		ATTRIBUTE_NODE,               /// The node is an Attr.
		TEXT_NODE,                    /// The node is a Text node.
		CDATA_SECTION_NODE,           /// The node is a CDATASection.
		ENTITY_REFERENCE_NODE,        /// The node is an EntityReference.
		ENTITY_NODE,                  /// The node is an Entity.
		PROCESSING_INSTRUCTION_NODE,  /// The node is a ProcessingInstruction.
		COMMENT_NODE,                 /// The node is a Comment.
		DOCUMENT_NODE,                /// The node is a Document.
		DOCUMENT_TYPE_NODE,           /// The node is a DocumentType.
		DOCUMENT_FRAGMENT_NODE,       /// The node is a DocumentFragment.
		NOTATION_NODE                 /// The node is a Notation.
	};

	virtual const XMLString& nodeName() const = 0;
		/// Returns the name of this node, depending on its type.

	const XMLString& nodeValue() const;
		/// Returns the value of this node, depending on its type.

	virtual const XMLString& getNodeValue() const = 0;
		/// Returns the value of this node, depending on its type.

	virtual void setNodeValue(const XMLString& value) = 0;
		/// Sets the value of this node. Throws an exception
		/// if the node is read-only.

	virtual unsigned short nodeType() const = 0;
		/// Returns a code representing the type of the underlying object.

	virtual Node* parentNode() const = 0;
		/// The parent of this node. All nodes, except Attr, Document, DocumentFragment,
		/// Entity, and Notation may have a parent. However, if a node has just been
		/// created and not yet added to the tree, or if it has been removed from the
		/// tree, this is null.

	virtual NodeList* childNodes() const = 0;
		/// Returns a NodeList containing all children of this node.
		///
		/// The returned NodeList must be released with a call
		/// to release() when no longer needed.

	virtual Node* firstChild() const = 0;
		/// Returns the first child of this node. If there is no such
		/// node, this returns null.

	virtual Node* lastChild() const = 0;
		/// Returns the last child of this node. If there is no such
		/// node, this returns null.

	virtual Node* previousSibling() const = 0;
		/// Returns the node immediately preceding this node. If there
		/// is no such node, this returns null.

	virtual Node* nextSibling() const = 0;
		/// Returns the node immediately following this node. If there
		/// is no such node, this returns null.

	virtual NamedNodeMap* attributes() const = 0;
		/// 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 Document* ownerDocument() const = 0;
		/// Returns the Document object associated with this node.
		/// This is also the Document object used to create new nodes.
		/// When this node is a Document, this is null.

	virtual Node* insertBefore(Node* newChild, Node* refChild) = 0;
		/// Inserts the node newChild before the existing child node refChild.
		///
		/// If refChild is null, insert newChild at the end of the list of children.
		/// If newChild is a DocumentFragment object, all of its children are
		/// inserted in the same order, before refChild. If the newChild is already
		/// in the tree, it is first removed.

	virtual Node* replaceChild(Node* newChild, Node* oldChild) = 0;
		/// Replaces the child node oldChild with newChild in the list of children,
		/// and returns the oldChild node.
		/// If newChild is a DocumentFragment object, oldChild is replaced by all of
		/// the DocumentFragment children, which are inserted in the same order. If
		/// the newChild is already in the tree, it is first removed.

	virtual Node* removeChild(Node* oldChild) = 0;
		/// Removes the child node indicated by oldChild from the list of children
		/// and returns it. 

	virtual Node* appendChild(Node* newChild) = 0;
		/// Appends the node newChild to the end of the list of children of this node.
		/// If newChild is already in the tree, it is first removed.

	virtual bool hasChildNodes() const = 0;
		/// This is a convenience method to allow easy determination of whether a 
		/// node has any children.
		/// Returns true if the node has any children, false otherwise.

	virtual Node* cloneNode(bool deep) const = 0;
		/// Returns a duplicate of this node, i.e., serves as a generic copy constructor
		/// for nodes. The duplicate node has no parent; (parentNode is null.).
		/// Cloning an Element copies all attributes and their values, including those
		/// generated by the XML processor to represent defaulted attributes, but this
		/// method does not copy any text it contains unless it is a deep clone, since
		/// the text is contained in a child Text node. Cloning an Attribute directly,
		/// as opposed to be cloned as part of an Element cloning operation, returns
		/// a specified attribute (specified is true). Cloning any other type of node
		/// simply returns a copy of this node.
		/// Note that cloning an immutable subtree results in a mutable copy, but the
		/// children of an EntityReference clone are readonly. In addition, clones of
		/// unspecified Attr nodes are specified. And, cloning Document, DocumentType,
		/// Entity, and Notation nodes is implementation dependent.
	
	// DOM Level 2
	virtual void normalize() = 0;
		/// Puts all Text nodes in the full depth of the sub-tree underneath this Node,
		/// including attribute nodes, into a "normal" form where only structure (e.g.,
		/// elements, comments, processing instructions, CDATA sections, and entity
		/// references) separates Text nodes, i.e., there are neither adjacent Text
		/// nodes nor empty 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.

	virtual bool isSupported(const XMLString& feature, const XMLString& version) const = 0;
		/// Tests whether the DOM implementation implements a specific 
		/// feature and that feature is supported by this node.

	virtual const XMLString& namespaceURI() const = 0;
		/// 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 = 0;
		/// Returns the namespace prefix from the qualified name of the node.

	virtual const XMLString& localName() const = 0;
		/// Returns the local name of the node.

	virtual bool hasAttributes() const = 0;
		/// Returns whether this node (if it is an element) has any attributes.
		
	// Extensions
	virtual XMLString innerText() const = 0;
		/// 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.

protected:
	virtual ~Node();
};


//
// inlines
//
inline const XMLString& Node::nodeValue() const
{
	return getNodeValue();
}


XML_END


#endif // DOM_Node_INCLUDED