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 | |
30 | namespace Poco { |
31 | namespace XML { |
32 | |
33 | |
34 | class NamePool; |
35 | class DocumentType; |
36 | class DOMImplementation; |
37 | class DocumentFragment; |
38 | class Text; |
39 | class ; |
40 | class CDATASection; |
41 | class ProcessingInstruction; |
42 | class Attr; |
43 | class EntityReference; |
44 | class NodeList; |
45 | class Entity; |
46 | class Notation; |
47 | |
48 | |
49 | class 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 | { |
60 | public: |
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* (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 | |
235 | protected: |
236 | ~Document(); |
237 | |
238 | Node* copyNode(bool deep, Document* pOwnerDocument) const; |
239 | |
240 | DocumentType* getDoctype(); |
241 | void setDoctype(DocumentType* pDoctype); |
242 | |
243 | private: |
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 | // |
258 | inline NamePool& Document::namePool() |
259 | { |
260 | return *_pNamePool; |
261 | } |
262 | |
263 | |
264 | inline Document::AutoReleasePool& Document::autoReleasePool() |
265 | { |
266 | return _autoReleasePool; |
267 | } |
268 | |
269 | |
270 | inline const DocumentType* Document::doctype() const |
271 | { |
272 | return _pDocumentType; |
273 | } |
274 | |
275 | |
276 | inline DocumentType* Document::getDoctype() |
277 | { |
278 | return _pDocumentType; |
279 | } |
280 | |
281 | |
282 | } } // namespace Poco::XML |
283 | |
284 | |
285 | #endif // DOM_Document_INCLUDED |
286 | |