//
// Document.h
//
// $Id: //poco/Main/XML/include/DOM/Document.h#5 $
//
// Definition of the DOM Document 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_Document_INCLUDED
#define DOM_Document_INCLUDED
#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef DOM_AbstractContainerNode_INCLUDED
#include "DOM/AbstractContainerNode.h"
#endif
#ifndef DOM_DocumentEvent_INCLUDED
#include "DOM/DocumentEvent.h"
#endif
#ifndef XML_XMLString_INCLUDED
#include "XML/XMLString.h"
#endif
#ifndef XML_NamePool_INCLUDED
#include "XML/NamePool.h"
#endif
#ifndef Foundation_AutoReleasePool_INCLUDED
#include "Foundation/AutoReleasePool.h"
#endif
XML_BEGIN
class NamePool;
class DocumentType;
class DOMImplementation;
class Element;
class DocumentFragment;
class Text;
class Comment;
class CDATASection;
class ProcessingInstruction;
class Attr;
class EntityReference;
class NodeList;
class Entity;
class Notation;
class XML_API Document: public AbstractContainerNode, public DocumentEvent
/// The Document interface represents the entire HTML or XML document. Conceptually,
/// it is the root of the document tree, and provides the primary access to the
/// document's data.
///
/// Since elements, text nodes, comments, processing instructions, etc. cannot exist
/// outside the context of a Document, the Document interface also contains the
/// factory methods needed to create these objects. The Node objects created have a
/// ownerDocument attribute which associates them with the Document within whose
/// context they were created.
{
public:
typedef Foundation::AutoReleasePool AutoReleasePool;
Document(NamePool* pNamePool = 0);
/// Creates a new document. If pNamePool == 0, the document
/// creates its own name pool, otherwise it uses the given name pool.
/// Sharing a name pool makes sense for documents containing instances
/// of the same schema, thus reducing memory usage.
Document(DocumentType* pDocumentType, NamePool* pNamePool = 0);
/// Creates a new document. If pNamePool == 0, the document
/// creates its own name pool, otherwise it uses the given name pool.
/// Sharing a name pool makes sense for documents containing instances
/// of the same schema, thus reducing memory usage.
NamePool& namePool();
/// Returns a pointer to the documents Name Pool.
AutoReleasePool& autoReleasePool();
/// Returns a pointer to the documents Auto Release Pool.
void collectGarbage();
/// Releases all objects in the Auto Release Pool.
void suspendEvents();
/// Suspends all events until resumeEvents() is called.
void resumeEvents();
/// Resumes all events suspended with suspendEvent();
bool eventsSuspended() const;
/// Returns true if events are suspeded.
bool events() const;
/// Returns true if events are not suspeded.
const DocumentType* doctype() const;
/// The Document Type Declaration (see DocumentType) associated with this document.
/// For HTML documents as well as XML documents without a document type declaration
/// this returns null. The DOM Level 1 does not support editing the Document
/// Type Declaration. docType cannot be altered in any way, including through
/// the use of methods inherited from the Node interface, such as insertNode
/// or removeNode.
const DOMImplementation& implementation() const;
/// The DOMImplementation object that handles this document. A DOM application
/// may use objects from multiple implementations.
Element* documentElement() const;
/// This is a convenience attribute that allows direct access to the child node
/// that is the root element of the document. For HTML documents, this is the
/// element with the tagName "HTML".
Element* createElement(const XMLString& tagName) const;
/// Creates an element of the type specified. Note that the instance returned
/// implements the Element interface, so attributes can be specified directly
/// on the returned object.
///
/// In addition, if there are known attributes with default values, Attr nodes
/// representing them are automatically created and attached to the element.
DocumentFragment* createDocumentFragment() const;
/// Creates an empty DocumentFragment object.
Text* createTextNode(const XMLString& data) const;
/// Creates a text node given the specified string.
Comment* createComment(const XMLString& data) const;
/// Creates a comment node given the specified string.
CDATASection* createCDATASection(const XMLString& data) const;
/// Creates a CDATASection node whose value is the specified string.
ProcessingInstruction* createProcessingInstruction(const XMLString& target, const XMLString& data) const;
/// Creates a ProcessingInstruction node given the specified target and data strings.
Attr* createAttribute(const XMLString& name) const;
/// Creates an Attr of the given name. Note that the Attr instance can then
/// be set on an Element using the setAttributeNode method.
EntityReference* createEntityReference(const XMLString& name) const;
/// Creates an EntityReference object. In addition, if the referenced entity
/// is known, the child list of the EntityReference node is made the same as
/// that of the corresponding Entity node.
NodeList* getElementsByTagName(const XMLString& name) const;
/// Returns a NodeList of all Elements with a given tag name in the order
/// in which they would be encountered in a preorder traversal of the
/// document tree.
///
/// The returned NodeList must be released with a call to release()
/// when no longer needed.
// DOM Level 2
Node* importNode(Node* importedNode, bool deep);
/// Imports a node from another document to this document. The returned node
/// has no parent; (parentNode is null). The source node is not altered or removed
/// from the original document; this method creates a new copy of the source
/// node.
/// For all nodes, importing a node creates a node object owned by the importing
/// document, with attribute values identical to the source node's nodeName
/// and nodeType, plus the attributes related to namespaces (prefix, localName,
/// and namespaceURI). As in the cloneNode operation on a Node, the source node
/// is not altered.
/// Additional information is copied as appropriate to the nodeType, attempting
/// to mirror the behavior expected if a fragment of XML or HTML source was
/// copied from one document to another, recognizing that the two documents
/// may have different DTDs in the XML case.
Element* createElementNS(const XMLString& namespaceURI, const XMLString& qualifiedName) const;
/// Creates an element of the given qualified name and namespace URI.
Attr* createAttributeNS(const XMLString& namespaceURI, const XMLString& qualifiedName) const;
/// Creates an attribute of the given qualified name and namespace URI.
NodeList* getElementsByTagNameNS(const XMLString& namespaceURI, const XMLString& localName) const;
/// Returns a NodeList of all the Elements with a given local name and
/// namespace URI in the order in which they are encountered in a
/// preorder traversal of the Document tree.
Element* getElementById(const XMLString& elementId) const;
/// Returns the Element whose ID is given by elementId. If no such
/// element exists, returns null. Behavior is not defined if more
/// than one element has this ID.
///
/// Note: The DOM implementation must have information that says
/// which attributes are of type ID. Attributes with the name "ID"
/// are not of type ID unless so defined. Implementations that do
/// not know whether attributes are of type ID or not are expected to
/// return null. This implementation therefore returns null.
// DocumentEvent
Event* createEvent(const XMLString& eventType) const;
// Node
const XMLString& nodeName() const;
unsigned short nodeType() const;
// EventTarget
bool dispatchEvent(Event* evt);
// Extensions
Entity* createEntity(const XMLString& name, const XMLString& publicId, const XMLString& systemId, const XMLString& notationName) const;
/// Creates an Entity with the given name, publicId, systemId and notationName.
///
/// This method is not part of the W3C Document Object Model.
Notation* createNotation(const XMLString& name, const XMLString& publicId, const XMLString& systemId) const;
/// Creates a Notation with the given name, publicId and systemId.
///
/// This method is not part of the W3C Document Object Model.
protected:
~Document();
Node* copyNode(bool deep, Document* pOwnerDocument) const;
DocumentType* getDoctype();
void setDoctype(DocumentType* pDoctype);
private:
DocumentType* _pDocumentType;
NamePool* _pNamePool;
AutoReleasePool _autoReleasePool;
int _eventSuspendLevel;
static const XMLString NODE_NAME;
friend class DOMBuilder;
};
//
// inlines
//
inline NamePool& Document::namePool()
{
return *_pNamePool;
}
inline Document::AutoReleasePool& Document::autoReleasePool()
{
return _autoReleasePool;
}
inline const DocumentType* Document::doctype() const
{
return _pDocumentType;
}
inline DocumentType* Document::getDoctype()
{
return _pDocumentType;
}
XML_END
#endif // DOM_Document_INCLUDED
