1//
2// Document.h
3//
4// Library: XML
5// Package: DOM
6// Module: DOM
7//
8// Definition of the DOM Document class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_Document_INCLUDED
18#define DOM_Document_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/DOM/AbstractContainerNode.h"
23#include "Poco/DOM/DocumentEvent.h"
24#include "Poco/DOM/Element.h"
25#include "Poco/XML/XMLString.h"
26#include "Poco/XML/NamePool.h"
27#include "Poco/AutoReleasePool.h"
28
29
30namespace Poco {
31namespace XML {
32
33
34class NamePool;
35class DocumentType;
36class DOMImplementation;
37class DocumentFragment;
38class Text;
39class Comment;
40class CDATASection;
41class ProcessingInstruction;
42class Attr;
43class EntityReference;
44class NodeList;
45class Entity;
46class Notation;
47
48
49class XML_API Document: public AbstractContainerNode, public DocumentEvent
50 /// The Document interface represents the entire HTML or XML document. Conceptually,
51 /// it is the root of the document tree, and provides the primary access to the
52 /// document's data.
53 ///
54 /// Since elements, text nodes, comments, processing instructions, etc. cannot exist
55 /// outside the context of a Document, the Document interface also contains the
56 /// factory methods needed to create these objects. The Node objects created have a
57 /// ownerDocument attribute which associates them with the Document within whose
58 /// context they were created.
59{
60public:
61 typedef Poco::AutoReleasePool<DOMObject> AutoReleasePool;
62
63 explicit Document(NamePool* pNamePool = 0);
64 /// Creates a new document. If pNamePool == 0, the document
65 /// creates its own name pool, otherwise it uses the given name pool.
66 /// Sharing a name pool makes sense for documents containing instances
67 /// of the same schema, thus reducing memory usage.
68
69 explicit Document(unsigned long namePoolSize);
70 /// Creates a new document using a name pool with the given size, which
71 /// should be a prime number (e.g., 251, 509, 1021, 4093).
72
73 Document(DocumentType* pDocumentType, NamePool* pNamePool = 0);
74 /// Creates a new document. If pNamePool == 0, the document
75 /// creates its own name pool, otherwise it uses the given name pool.
76 /// Sharing a name pool makes sense for documents containing instances
77 /// of the same schema, thus reducing memory usage.
78
79 Document(DocumentType* pDocumentType, unsigned long namePoolSize);
80 /// Creates a new document using a name pool with the given size, which
81 /// should be a prime number (e.g., 251, 509, 1021, 4093).
82
83 NamePool& namePool();
84 /// Returns a pointer to the documents Name Pool.
85
86 AutoReleasePool& autoReleasePool();
87 /// Returns a pointer to the documents Auto Release Pool.
88
89 void collectGarbage();
90 /// Releases all objects in the Auto Release Pool.
91
92 void suspendEvents();
93 /// Suspends all events until resumeEvents() is called.
94
95 void resumeEvents();
96 /// Resumes all events suspended with suspendEvent();
97
98 bool eventsSuspended() const;
99 /// Returns true if events are suspended.
100
101 bool events() const;
102 /// Returns true if events are not suspended.
103
104 const DocumentType* doctype() const;
105 /// The Document Type Declaration (see DocumentType) associated with this document.
106 /// For HTML documents as well as XML documents without a document type declaration
107 /// this returns null. The DOM Level 1 does not support editing the Document
108 /// Type Declaration. docType cannot be altered in any way, including through
109 /// the use of methods inherited from the Node interface, such as insertNode
110 /// or removeNode.
111
112 const DOMImplementation& implementation() const;
113 /// The DOMImplementation object that handles this document. A DOM application
114 /// may use objects from multiple implementations.
115
116 Element* documentElement() const;
117 /// This is a convenience attribute that allows direct access to the child node
118 /// that is the root element of the document. For HTML documents, this is the
119 /// element with the tagName "HTML".
120
121 Element* createElement(const XMLString& tagName) const;
122 /// Creates an element of the type specified. Note that the instance returned
123 /// implements the Element interface, so attributes can be specified directly
124 /// on the returned object.
125 ///
126 /// In addition, if there are known attributes with default values, Attr nodes
127 /// representing them are automatically created and attached to the element.
128
129 DocumentFragment* createDocumentFragment() const;
130 /// Creates an empty DocumentFragment object.
131
132 Text* createTextNode(const XMLString& data) const;
133 /// Creates a text node given the specified string.
134
135 Comment* createComment(const XMLString& data) const;
136 /// Creates a comment node given the specified string.
137
138 CDATASection* createCDATASection(const XMLString& data) const;
139 /// Creates a CDATASection node whose value is the specified string.
140
141 ProcessingInstruction* createProcessingInstruction(const XMLString& target, const XMLString& data) const;
142 /// Creates a ProcessingInstruction node given the specified target and data strings.
143
144 Attr* createAttribute(const XMLString& name) const;
145 /// Creates an Attr of the given name. Note that the Attr instance can then
146 /// be set on an Element using the setAttributeNode method.
147
148 EntityReference* createEntityReference(const XMLString& name) const;
149 /// Creates an EntityReference object. In addition, if the referenced entity
150 /// is known, the child list of the EntityReference node is made the same as
151 /// that of the corresponding Entity node.
152
153 NodeList* getElementsByTagName(const XMLString& name) const;
154 /// Returns a NodeList of all Elements with a given tag name in the order
155 /// in which they would be encountered in a preorder traversal of the
156 /// document tree.
157 ///
158 /// The returned NodeList must be released with a call to release()
159 /// when no longer needed.
160
161 // DOM Level 2
162 Node* importNode(Node* importedNode, bool deep);
163 /// Imports a node from another document to this document. The returned node
164 /// has no parent; (parentNode is null). The source node is not altered or removed
165 /// from the original document; this method creates a new copy of the source
166 /// node.
167 /// For all nodes, importing a node creates a node object owned by the importing
168 /// document, with attribute values identical to the source node's nodeName
169 /// and nodeType, plus the attributes related to namespaces (prefix, localName,
170 /// and namespaceURI). As in the cloneNode operation on a Node, the source node
171 /// is not altered.
172 /// Additional information is copied as appropriate to the nodeType, attempting
173 /// to mirror the behavior expected if a fragment of XML or HTML source was
174 /// copied from one document to another, recognizing that the two documents
175 /// may have different DTDs in the XML case.
176
177 Element* createElementNS(const XMLString& namespaceURI, const XMLString& qualifiedName) const;
178 /// Creates an element of the given qualified name and namespace URI.
179
180 Attr* createAttributeNS(const XMLString& namespaceURI, const XMLString& qualifiedName) const;
181 /// Creates an attribute of the given qualified name and namespace URI.
182
183 NodeList* getElementsByTagNameNS(const XMLString& namespaceURI, const XMLString& localName) const;
184 /// Returns a NodeList of all the Elements with a given local name and
185 /// namespace URI in the order in which they are encountered in a
186 /// preorder traversal of the Document tree.
187
188 Element* getElementById(const XMLString& elementId) const;
189 /// Returns the Element whose ID is given by elementId. If no such
190 /// element exists, returns null. Behavior is not defined if more
191 /// than one element has this ID.
192 ///
193 /// Note: The DOM implementation must have information that says
194 /// which attributes are of type ID. Attributes with the name "ID"
195 /// are not of type ID unless so defined. Implementations that do
196 /// not know whether attributes are of type ID or not are expected to
197 /// return null. This implementation therefore returns null.
198 ///
199 /// See also the non-standard two argument variant of getElementById()
200 /// and getElementByIdNS().
201
202 // DocumentEvent
203 Event* createEvent(const XMLString& eventType) const;
204
205 // Node
206 const XMLString& nodeName() const;
207 unsigned short nodeType() const;
208
209 // EventTarget
210 bool dispatchEvent(Event* evt);
211
212 // Extensions
213 Entity* createEntity(const XMLString& name, const XMLString& publicId, const XMLString& systemId, const XMLString& notationName) const;
214 /// Creates an Entity with the given name, publicId, systemId and notationName.
215 ///
216 /// This method is not part of the W3C Document Object Model.
217
218 Notation* createNotation(const XMLString& name, const XMLString& publicId, const XMLString& systemId) const;
219 /// Creates a Notation with the given name, publicId and systemId.
220 ///
221 /// This method is not part of the W3C Document Object Model.
222
223 Element* getElementById(const XMLString& elementId, const XMLString& idAttribute) const;
224 /// Returns the first Element whose ID attribute (given in idAttribute)
225 /// has the given elementId. If no such element exists, returns null.
226 ///
227 /// This method is an extension to the W3C Document Object Model.
228
229 Element* getElementByIdNS(const XMLString& elementId, const XMLString& idAttributeURI, const XMLString& idAttributeLocalName) const;
230 /// Returns the first Element whose ID attribute (given in idAttributeURI and idAttributeLocalName)
231 /// has the given elementId. If no such element exists, returns null.
232 ///
233 /// This method is an extension to the W3C Document Object Model.
234
235protected:
236 ~Document();
237
238 Node* copyNode(bool deep, Document* pOwnerDocument) const;
239
240 DocumentType* getDoctype();
241 void setDoctype(DocumentType* pDoctype);
242
243private:
244 DocumentType* _pDocumentType;
245 NamePool* _pNamePool;
246 AutoReleasePool _autoReleasePool;
247 int _eventSuspendLevel;
248
249 static const XMLString NODE_NAME;
250
251 friend class DOMBuilder;
252};
253
254
255//
256// inlines
257//
258inline NamePool& Document::namePool()
259{
260 return *_pNamePool;
261}
262
263
264inline Document::AutoReleasePool& Document::autoReleasePool()
265{
266 return _autoReleasePool;
267}
268
269
270inline const DocumentType* Document::doctype() const
271{
272 return _pDocumentType;
273}
274
275
276inline DocumentType* Document::getDoctype()
277{
278 return _pDocumentType;
279}
280
281
282} } // namespace Poco::XML
283
284
285#endif // DOM_Document_INCLUDED
286