1 | // |
2 | // Node.h |
3 | // |
4 | // Library: XML |
5 | // Package: DOM |
6 | // Module: DOM |
7 | // |
8 | // Definition of the DOM Node interface. |
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_Node_INCLUDED |
18 | #define DOM_Node_INCLUDED |
19 | |
20 | |
21 | #include "Poco/XML/XML.h" |
22 | #include "Poco/DOM/EventTarget.h" |
23 | #include "Poco/XML/XMLString.h" |
24 | #include "Poco/SAX/NamespaceSupport.h" |
25 | |
26 | |
27 | namespace Poco { |
28 | namespace XML { |
29 | |
30 | |
31 | class NamedNodeMap; |
32 | class Document; |
33 | class NodeList; |
34 | |
35 | |
36 | class XML_API Node: public EventTarget |
37 | /// The Node interface is the primary datatype for the entire Document Object |
38 | /// Model. It represents a single node in the document tree. While all objects |
39 | /// implementing the Node interface expose methods for dealing with children, |
40 | /// not all objects implementing the Node interface may have children. For |
41 | /// example, Text nodes may not have children, and adding children to such |
42 | /// nodes results in a DOMException being raised. |
43 | /// |
44 | /// The attributes nodeName, nodeValue and attributes are included as a mechanism |
45 | /// to get at node information without casting down to the specific derived |
46 | /// interface. In cases where there is no obvious mapping of these attributes |
47 | /// for a specific nodeType (e.g., nodeValue for an Element or attributes for |
48 | /// a Comment), this returns null. Note that the specialized interfaces may |
49 | /// contain additional and more convenient mechanisms to get and set the relevant |
50 | /// information. |
51 | /// |
52 | /// This implementation differs in some ways from the W3C DOM recommendations. |
53 | /// For example, the DOM specifies that some methods can return null strings. |
54 | /// Instead of null strings, this implementation always returns empty strings. |
55 | { |
56 | public: |
57 | enum |
58 | { |
59 | ELEMENT_NODE = 1, /// The node is an Element. |
60 | ATTRIBUTE_NODE, /// The node is an Attr. |
61 | TEXT_NODE, /// The node is a Text node. |
62 | CDATA_SECTION_NODE, /// The node is a CDATASection. |
63 | ENTITY_REFERENCE_NODE, /// The node is an EntityReference. |
64 | ENTITY_NODE, /// The node is an Entity. |
65 | PROCESSING_INSTRUCTION_NODE, /// The node is a ProcessingInstruction. |
66 | , /// The node is a Comment. |
67 | DOCUMENT_NODE, /// The node is a Document. |
68 | DOCUMENT_TYPE_NODE, /// The node is a DocumentType. |
69 | DOCUMENT_FRAGMENT_NODE, /// The node is a DocumentFragment. |
70 | NOTATION_NODE /// The node is a Notation. |
71 | }; |
72 | |
73 | virtual const XMLString& nodeName() const = 0; |
74 | /// Returns the name of this node, depending on its type. |
75 | |
76 | const XMLString& nodeValue() const; |
77 | /// Returns the value of this node, depending on its type. |
78 | |
79 | virtual const XMLString& getNodeValue() const = 0; |
80 | /// Returns the value of this node, depending on its type. |
81 | |
82 | virtual void setNodeValue(const XMLString& value) = 0; |
83 | /// Sets the value of this node. Throws an exception |
84 | /// if the node is read-only. |
85 | |
86 | virtual unsigned short nodeType() const = 0; |
87 | /// Returns a code representing the type of the underlying object. |
88 | |
89 | virtual Node* parentNode() const = 0; |
90 | /// The parent of this node. All nodes, except Attr, Document, DocumentFragment, |
91 | /// Entity, and Notation may have a parent. However, if a node has just been |
92 | /// created and not yet added to the tree, or if it has been removed from the |
93 | /// tree, this is null. |
94 | |
95 | virtual NodeList* childNodes() const = 0; |
96 | /// Returns a NodeList containing all children of this node. |
97 | /// |
98 | /// The returned NodeList must be released with a call |
99 | /// to release() when no longer needed. |
100 | |
101 | virtual Node* firstChild() const = 0; |
102 | /// Returns the first child of this node. If there is no such |
103 | /// node, this returns null. |
104 | |
105 | virtual Node* lastChild() const = 0; |
106 | /// Returns the last child of this node. If there is no such |
107 | /// node, this returns null. |
108 | |
109 | virtual Node* previousSibling() const = 0; |
110 | /// Returns the node immediately preceding this node. If there |
111 | /// is no such node, this returns null. |
112 | |
113 | virtual Node* nextSibling() const = 0; |
114 | /// Returns the node immediately following this node. If there |
115 | /// is no such node, this returns null. |
116 | |
117 | virtual NamedNodeMap* attributes() const = 0; |
118 | /// Returns a NamedNodeMap containing the attributes of this |
119 | /// node (if it is an Element) or null otherwise. |
120 | /// |
121 | /// The returned NamedNodeMap must be released with a call |
122 | /// to release() when no longer needed. |
123 | |
124 | virtual Document* ownerDocument() const = 0; |
125 | /// Returns the Document object associated with this node. |
126 | /// This is also the Document object used to create new nodes. |
127 | /// When this node is a Document, this is null. |
128 | |
129 | virtual Node* insertBefore(Node* newChild, Node* refChild) = 0; |
130 | /// Inserts the node newChild before the existing child node refChild. |
131 | /// |
132 | /// If refChild is null, insert newChild at the end of the list of children. |
133 | /// If newChild is a DocumentFragment object, all of its children are |
134 | /// inserted in the same order, before refChild. If the newChild is already |
135 | /// in the tree, it is first removed. |
136 | |
137 | virtual Node* replaceChild(Node* newChild, Node* oldChild) = 0; |
138 | /// Replaces the child node oldChild with newChild in the list of children, |
139 | /// and returns the oldChild node. |
140 | /// If newChild is a DocumentFragment object, oldChild is replaced by all of |
141 | /// the DocumentFragment children, which are inserted in the same order. If |
142 | /// the newChild is already in the tree, it is first removed. |
143 | |
144 | virtual Node* removeChild(Node* oldChild) = 0; |
145 | /// Removes the child node indicated by oldChild from the list of children |
146 | /// and returns it. |
147 | |
148 | virtual Node* appendChild(Node* newChild) = 0; |
149 | /// Appends the node newChild to the end of the list of children of this node. |
150 | /// If newChild is already in the tree, it is first removed. |
151 | |
152 | virtual bool hasChildNodes() const = 0; |
153 | /// This is a convenience method to allow easy determination of whether a |
154 | /// node has any children. |
155 | /// Returns true if the node has any children, false otherwise. |
156 | |
157 | virtual Node* cloneNode(bool deep) const = 0; |
158 | /// Returns a duplicate of this node, i.e., serves as a generic copy constructor |
159 | /// for nodes. The duplicate node has no parent; (parentNode is null.). |
160 | /// Cloning an Element copies all attributes and their values, including those |
161 | /// generated by the XML processor to represent defaulted attributes, but this |
162 | /// method does not copy any text it contains unless it is a deep clone, since |
163 | /// the text is contained in a child Text node. Cloning an Attribute directly, |
164 | /// as opposed to be cloned as part of an Element cloning operation, returns |
165 | /// a specified attribute (specified is true). Cloning any other type of node |
166 | /// simply returns a copy of this node. |
167 | /// Note that cloning an immutable subtree results in a mutable copy, but the |
168 | /// children of an EntityReference clone are readonly. In addition, clones of |
169 | /// unspecified Attr nodes are specified. And, cloning Document, DocumentType, |
170 | /// Entity, and Notation nodes is implementation dependent. |
171 | |
172 | // DOM Level 2 |
173 | virtual void normalize() = 0; |
174 | /// Puts all Text nodes in the full depth of the sub-tree underneath this Node, |
175 | /// including attribute nodes, into a "normal" form where only structure (e.g., |
176 | /// elements, comments, processing instructions, CDATA sections, and entity |
177 | /// references) separates Text nodes, i.e., there are neither adjacent Text |
178 | /// nodes nor empty Text nodes. This can be used to ensure that the DOM view |
179 | /// of a document is the same as if it were saved and re-loaded, and is useful |
180 | /// when operations (such as XPointer lookups) that depend on a particular |
181 | /// document tree structure are to be used. |
182 | /// |
183 | /// Note: In cases where the document contains CDATASections, the normalize |
184 | /// operation alone may not be sufficient, since XPointers do not differentiate |
185 | /// between Text nodes and CDATASection nodes. |
186 | |
187 | virtual bool isSupported(const XMLString& feature, const XMLString& version) const = 0; |
188 | /// Tests whether the DOM implementation implements a specific |
189 | /// feature and that feature is supported by this node. |
190 | |
191 | virtual const XMLString& namespaceURI() const = 0; |
192 | /// Returns the namespace URI of the node. |
193 | /// This is not a computed value that is the result of a namespace lookup based on an |
194 | /// examination of the namespace declarations in scope. It is merely the namespace URI |
195 | /// given at creation time. |
196 | /// |
197 | /// For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a |
198 | /// DOM Level 1 method, such as createElement from the Document interface, this is always the |
199 | /// empty string. |
200 | |
201 | virtual XMLString prefix() const = 0; |
202 | /// Returns the namespace prefix from the qualified name of the node. |
203 | |
204 | virtual const XMLString& localName() const = 0; |
205 | /// Returns the local name of the node. |
206 | |
207 | virtual bool hasAttributes() const = 0; |
208 | /// Returns whether this node (if it is an element) has any attributes. |
209 | |
210 | // Extensions |
211 | typedef Poco::XML::NamespaceSupport NSMap; |
212 | |
213 | virtual XMLString innerText() const = 0; |
214 | /// Returns a string containing the concatenated values of the node |
215 | /// and all its child nodes. |
216 | /// |
217 | /// This method is not part of the W3C Document Object Model. |
218 | |
219 | virtual Node* getNodeByPath(const XMLString& path) const = 0; |
220 | /// Searches a node (element or attribute) based on a simplified XPath |
221 | /// expression. |
222 | /// |
223 | /// Only simple XPath expressions are supported. These are the slash |
224 | /// notation for specifying paths to elements, and the square bracket |
225 | /// expression for finding elements by their index, by attribute value, |
226 | /// or finding attributes by names. |
227 | /// |
228 | /// The slash at the beginning is optional, the evaluation always starts |
229 | /// at this element. A double-slash at the beginning recursively searches |
230 | /// the entire subtree for the first element. |
231 | /// |
232 | /// Examples: |
233 | /// elem1/elem2/elem3 |
234 | /// /elem1/elem2/elem3 |
235 | /// /elem1/elem2[1] |
236 | /// /elem1/elem2[@attr1] |
237 | /// /elem1/elem2[@attr1='value'] |
238 | /// //elem2[@attr1='value'] |
239 | /// //[@attr1='value'] |
240 | /// |
241 | /// This method is an extension to the W3C Document Object Model. |
242 | |
243 | virtual Node* getNodeByPathNS(const XMLString& path, const NSMap& nsMap) const = 0; |
244 | /// Searches a node (element or attribute) based on a simplified XPath |
245 | /// expression. The given NSMap must contain mappings from namespace |
246 | /// prefixes to namespace URIs for all namespace prefixes used in |
247 | /// the path expression. |
248 | /// |
249 | /// Only simple XPath expressions are supported. These are the slash |
250 | /// notation for specifying paths to elements, and the square bracket |
251 | /// expression for finding elements by their index, by attribute value, |
252 | /// or finding attributes by names. |
253 | /// |
254 | /// The slash at the beginning is optional, the evaluation always starts |
255 | /// at this element. A double-slash at the beginning recursively searches |
256 | /// the entire subtree for the first element. |
257 | /// |
258 | /// Examples: |
259 | /// /ns1:elem1/ns2:elem2/ns2:elem3 |
260 | /// /ns1:elem1/ns2:elem2[1] |
261 | /// /ns1:elem1/ns2:elem2[@attr1] |
262 | /// /ns1:elem1/ns2:elem2[@attr1='value'] |
263 | /// //ns2:elem2[@ns1:attr1='value'] |
264 | /// //[@ns1:attr1='value'] |
265 | /// |
266 | /// This method is an extension to the W3C Document Object Model. |
267 | |
268 | protected: |
269 | virtual ~Node(); |
270 | }; |
271 | |
272 | |
273 | // |
274 | // inlines |
275 | // |
276 | inline const XMLString& Node::nodeValue() const |
277 | { |
278 | return getNodeValue(); |
279 | } |
280 | |
281 | |
282 | } } // namespace Poco::XML |
283 | |
284 | |
285 | #endif // DOM_Node_INCLUDED |
286 | |