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
27namespace Poco {
28namespace XML {
29
30
31class NamedNodeMap;
32class Document;
33class NodeList;
34
35
36class 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{
56public:
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 COMMENT_NODE, /// 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
268protected:
269 virtual ~Node();
270};
271
272
273//
274// inlines
275//
276inline const XMLString& Node::nodeValue() const
277{
278 return getNodeValue();
279}
280
281
282} } // namespace Poco::XML
283
284
285#endif // DOM_Node_INCLUDED
286