domnodes.h

简单的xml解析类

//************************************************************************************************************************** 
//* Blue Xml Extension
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* Blue - General Purpose C++ Library
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* This software is provided 'as-is', without any express or implied warranty. In no event
//* will the authors be held liable for any damages arising from the use of this software.
//* 
//* Permission is granted to anyone to use this software for any purpose, including commercial
//* applications, and to alter it and redistribute it freely, subject to the following restrictions:
//* 
//* 	1. The origin of this software must not be misrepresented; you must not claim that you
//* 	wrote the original software. If you use this software in a product, an acknowledgment in the
//* 	product documentation would be appreciated but is not required.
//* 
//* 	2. Altered source versions must be plainly marked as such, and must not be misrepresented as
//* 	being the original software.
//* 
//* 	3. This notice may not be removed or altered from any source distribution.
//*
//*
//* file   Blue/Extension/Xml/DomNodes.h
//**

#ifndef __blue_ext_xml_DomNodes_h_included__
#define __blue_ext_xml_DomNodes_h_included__

// Public Headers ==========================================================================================================

// Extension headers
#include "Blue/Extension/Xml/Xml.h"

// Blue library headers
#include "Blue/Common/Array.h"


// Public Defines/Enums/Typedefs/Etc. ======================================================================================

// Public Classes/Structs ==================================================================================================

namespace blue {
namespace ext {
namespace xml {

	/****
	 * Forward Declarations
	 */
	class DomNode;
		class DomDocumentNode;
		class DomElementNode;
		class DomAttributeNode;
		class DomTextNode;
			class DomCDataNode;
		class DomProcInstNode;
		class DomCommentNode;


	/**
	 * \class DomNode
	 * \brief The DomNode class is the base class for all the possible
	 * Dom node types.
	 * \ingroup Xml
	 *
	 * Depending on the node type, the core accessor functions -
	 * getName() and getValue() will return different values.  See the
	 * documentation for the node type class in question for more
	 * information.
	 *
	 * \sa DomParser, DomDocumentNode, DomElementNode,
	 *     DomAttributeNode, DomTextNode, DomCDataNode,
	 *     DomProcInstNode, DomCommentNode
	 */
	class BLUE_EXPORT_XML DomNode
	{
	public:

		/** The type of dom node this represents. */
		enum node_type_e
		{
			DOCUMENT,   //!< Node represents the Xml document
			ELEMENT,    //!< Node represents an element
			ATTRIBUTE,  //!< Node represents an attribute of an element or processing instruction
			TEXT,       //!< Node represents text of an element
			CDATA,      //!< Node represents text of an element in CDATA format
			PROC_INST,  //!< Node represents a processing instruction for the document
			COMMENT     //!< Node represents a comment in the document
		};

		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Destructor. */
		virtual ~DomNode();


		// ===========================================================
		//  query
		// ===========================================================

		/**
		 * Returns the name of the node.  This value varies for each
		 * node type.
		 */
		virtual String getName() const = 0;
		/**
		 * Returns the value of the node.  This value varies for each
		 * node type.
		 */
		virtual String getValue() const = 0;
		/**
		 * Returns the type of the node.
		 */
		virtual node_type_e getNodeType() const = 0;

		/**
		 * Returns the path of the node.  This path represents a manner
		 * of identifying the node and can be used as an XPath expression
		 * to return this node.
		 *
		 * If this returns <code>String::null</code>, there is no way
		 * of identifying this node through its path.
		 */
		virtual String getPath() const;

		/** Returns the parent of this node. */
		DomNode* getParent() const;

		/** Returns all sub nodes of this node. */
		Array<DomNode*> getSubNodes();
		/** overload. */
		const Array<DomNode*> getSubNodes() const;

		/** Returns all sub nodes of this node that are of the given type. */
		Array<DomNode*> getSubNodes( node_type_e type );
		/** overload. */
		const Array<DomNode*> getSubNodes( node_type_e type ) const;

		/** Returns an individual sub node whose name matches the given name. */
		DomNode* getSubNode( String name );
		/** overload. */
		const DomNode* getSubNode( String name ) const;


		// ===========================================================
		//  manipulation
		// ===========================================================

		/**
		 * Sets the name of the node.  The actual functionality varies
		 * for each node type and the value given may be ignored. 
		 */
		virtual void setName( String name );
		/**
		 * Sets the value of the node.  The actual functionality varies
		 * for each node type and the value given may be ignored. 
		 */
		virtual void setValue( String value );

		/** Adds a sub node to this node. */
		void addSubNode( DomNode* node );
		/** Removes a sub node from this node. */
		void removeSubNode( DomNode* node );

		/** Copies the Dom tree starting with this node. */
		DomNode* copyTree( DomNode* parent );


	protected:
		/** Constructor. */
		DomNode( DomNode* parent );

		virtual DomNode* clone( DomNode* parent ) = 0;

		DomNode* m_parent;
		Array<DomNode*> m_nodes;


	private:
		/**
		 * Copy constructor. Private because DomNodes should not be
		 * manipulated by more than one instance.
		 */
		DomNode( const DomNode& );
		/** Private assignment operator. See copy constructor documentation. */
		const DomNode& operator=( const DomNode& );

	};



	/**
	 * \class DomNodeException
	 * \brief Thrown when an error occurs within a DomNode class.
	 * \ingroup XmlExceptions
	 */
	class BLUE_EXPORT_XML DomNodeException :public XmlException
	{
	public:
		DomNodeException( String desc )
			:XmlException(desc) {}

		virtual String getException() const {
			return (String("DomNodeException", String::STATIC));
		}
	};



	/**
	 * \class DomDocumentNode
	 * \brief Represents the Xml document.
	 * \ingroup Xml
	 *
	 * This node provides access to all processing instructions
	 * that are provided by the Xml document as well as the root
	 * element of the document.
	 *
	 * getName() returns "##document"
	 * <br>getValue() returns String::null
	 */
	class BLUE_EXPORT_XML DomDocumentNode :public DomNode
	{
	public:
		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Constructor. */
		DomDocumentNode();

		/** Destructor. */
		virtual ~DomDocumentNode();


		// ===========================================================
		//  query
		// ===========================================================

		/** Meaningless for this node type. */
		virtual String getName() const;
		/** Meaningless for this node type. */
		virtual String getValue() const;
		/*** overload. */
		virtual node_type_e getNodeType() const;
		
		/*** overload. */
		virtual String getPath() const;

		/** Returns the root element of the Xml document. */
		DomElementNode* getRootElement();
		/** overload. */
		const DomElementNode* getRootElement() const;


		// ===========================================================
		//  manipulation
		// ===========================================================


	private:
		/**
		 * Copy constructor. Private because DomDocumentNodes should not be
		 * manipulated by more than one instance.
		 */
		DomDocumentNode( const DomDocumentNode& );
		/** Private assignment operator. See copy constructor documentation. */
		const DomDocumentNode& operator=( const DomDocumentNode& );

		virtual DomNode* clone( DomNode* parent );
	};


	/**
	 * \class DomElementNode
	 * \brief Represents an Xml element.
	 * \ingroup Xml
	 *
	 * getName() returns name of element
	 * <br>getValue() returns String::null
	 */
	class BLUE_EXPORT_XML DomElementNode :public DomNode
	{
	public:
		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Constructor. */
		DomElementNode( DomNode* parent, String name = String::null, String text = String::null );

		/** Destructor. */
		virtual ~DomElementNode();


		// ===========================================================
		//  query
		// ===========================================================

		/** Returns the name of the element */
		virtual String getName() const;
		/** Returns the combined text values of the element. */
		virtual String getValue() const;
		/*** overload. */
		virtual node_type_e getNodeType() const;

		/*** overload. */
		virtual String getPath() const;

		/** Returns all of the sub nodes of this node that are elements. */
		Array<DomElementNode*> getElementNodes();
		/** overload. */
		const Array<DomElementNode*> getElementNodes() const;

		/** Returns all of the sibling nodes of this node that are elements. */
		Array<DomElementNode*> getSiblingElementNodes();
		/** overload. */
		const Array<DomElementNode*> getSiblingElementNodes() const;

		/** Returns all of the sub nodes of this node that are text nodes. */
		Array<DomTextNode*> getTextNodes();
		/** overload. */
		const Array<DomTextNode*> getTextNodes() const;

		/** Returns all of the sub nodes of this node that are attributes. */
		Array<DomAttributeNode*> getAttributeNodes();
		/** overload. */
		const Array<DomAttributeNode*> getAttributeNodes() const;

		/** Determines if this element contains the given attribute name. */
		bool hasAttribute( String attribute ) const;

		/** Returns the attribute node for the given attribute name. */
		DomAttributeNode* getAttributeNode( String attribute );
		/** overload. */
		const DomAttributeNode* getAttributeNode( String attribute ) const;

		/**
		 * Returns an array that contains the names of all the attributes
		 * of this element.
		 */
		Array<String> getAttributeNames() const;

		/** Returns the value of the given attribute. */
		String getAttributeValue( String attribute ) const;

		/**
		 * Returns an array that contains the text data of all the text
		 * nodes of this element.
		 */
		Array<String> getTextValues() const;

		/** Returns the text values appended together. */
		String getTextValue() const;


		// ===========================================================
		//  manipulation
		// ===========================================================

		/** Sets the name of this element. */