1//
2// Element.h
3//
4// Library: XML
5// Package: DOM
6// Module: DOM
7//
8// Definition of the DOM Element 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_Element_INCLUDED
18#define DOM_Element_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/DOM/AbstractContainerNode.h"
23#include "Poco/XML/Name.h"
24
25
26namespace Poco {
27namespace XML {
28
29
30class Attr;
31class NodeList;
32class Document;
33
34
35class XML_API Element: public AbstractContainerNode
36 /// The Element interface represents an element in an XML document.
37 /// Elements may have attributes associated with them; since the Element interface
38 /// inherits from Node, the generic Node interface attribute attributes may
39 /// be used to retrieve the set of all attributes for an element. There are
40 /// methods on the Element interface to retrieve either an Attr object by name
41 /// or an attribute value by name. In XML, where an attribute value may contain
42 /// entity references, an Attr object should be retrieved to examine the possibly
43 /// fairly complex sub-tree representing the attribute value.
44{
45public:
46 const XMLString& tagName() const;
47 /// Returns the name of the element.
48 ///
49 /// For example, in
50 ///
51 /// <elementExample id="demo">
52 /// ...
53 /// </elementExample>
54 ///
55 /// tagName has the value "elementExample". Note that this is case-preserving in XML,
56 /// as are all of the operations of the DOM.
57
58 const XMLString& getAttribute(const XMLString& name) const;
59 /// Retrieves an attribute value by name.
60 ///
61 /// Returns the attribute's value, if the attribute
62 /// exists, or an empty string otherwise.
63
64 void setAttribute(const XMLString& name, const XMLString& value);
65 /// Adds a new attribute. If an attribute with that name is already present
66 /// in the element, its value is changed to be that of the value parameter.
67 /// This value is a simple string; it is not parsed as it is being set. So any
68 /// markup (such as syntax to be recognized as an entity reference) is treated
69 /// as literal text, and needs to be appropriately escaped by the implementation
70 /// when it is written out.
71
72 void removeAttribute(const XMLString& name);
73 /// Removes an attribute by name.
74
75 Attr* getAttributeNode(const XMLString& name) const;
76 /// Retrieves an Attr node by name.
77
78 Attr* setAttributeNode(Attr* newAttr);
79 /// Adds a new attribute. If an attribute with that name is already
80 /// present in the element, it is replaced by the new one.
81
82 Attr* addAttributeNodeNP(Attr* oldAttr, Attr* newAttr);
83 /// For internal use only.
84 /// Adds a new attribute after oldAttr.
85 /// If oldAttr is 0, newAttr is set as first attribute.
86 /// Returns newAttr.
87 /// Does not fire any events.
88
89 Attr* removeAttributeNode(Attr* oldAttr);
90 /// Removes the specified attribute.
91
92 NodeList* getElementsByTagName(const XMLString& name) const;
93 /// Returns a NodeList of all descendant elements with a given tag
94 /// name, in the order in which they would be encountered in a
95 /// preorder traversal of the Element tree.
96 ///
97 /// The special name "*" matches all tags.
98 ///
99 /// The returned NodeList must be released with a call
100 /// to release() when no longer needed.
101
102 void normalize();
103 /// Puts all Text nodes in the full depth of the sub-tree underneath this Element,
104 /// including attribute nodes, into a "normal" form where only markup (e.g.,
105 /// tags, comments, processing instructions, CDATA sections, and entity references)
106 /// separates Text nodes, i.e., there are no adjacent Text nodes. This can be
107 /// used to ensure that the DOM view of a document is the same as if it were
108 /// saved and re-loaded, and is useful when operations (such as XPointer
109 /// lookups) that depend on a particular document tree structure are to be used.
110 ///
111 /// Note: In cases where the document contains CDATASections, the normalize
112 /// operation alone may not be sufficient, since XPointers do not differentiate
113 /// between Text nodes and CDATASection nodes.
114
115 // DOM Level 2
116 const XMLString& getAttributeNS(const XMLString& namespaceURI, const XMLString& localName) const;
117 /// Retrieves an attribute value by name.
118 ///
119 /// Returns the attribute's value, if the attribute
120 /// exists, or an empty string otherwise.
121
122 void setAttributeNS(const XMLString& namespaceURI, const XMLString& qualifiedName, const XMLString& value);
123 /// Adds a new attribute. If an attribute with that name
124 /// is already present in the element, its value is changed
125 /// to be that of the value parameter.
126
127 void removeAttributeNS(const XMLString& namespaceURI, const XMLString& localName);
128 /// Removes an attribute by name.
129
130 Attr* getAttributeNodeNS(const XMLString& namespaceURI, const XMLString& localName) const;
131 /// Retrieves an Attr node by name.
132
133 Attr* setAttributeNodeNS(Attr* newAttr);
134 /// Adds a new attribute. If an attribute with that name is already
135 /// present in the element, it is replaced by the new one.
136
137 bool hasAttribute(const XMLString& name) const;
138 /// Returns true if and only if the element has the specified attribute.
139
140 bool hasAttributeNS(const XMLString& namespaceURI, const XMLString& localName) const;
141 /// Returns true if and only if the element has the specified attribute.
142
143 NodeList* getElementsByTagNameNS(const XMLString& namespaceURI, const XMLString& localName) const;
144 /// Returns a NodeList of all the descendant Elements with a given local name and namespace URI
145 /// in the order in which they are encountered in a preorder traversal of this Element tree.
146 ///
147 /// The special value "*" matches all namespaces, or local names respectively.
148 ///
149 /// The returned NodeList must be released with a call
150 /// to release() when no longer needed.
151
152 const XMLString& namespaceURI() const;
153 XMLString prefix() const;
154 const XMLString& localName() const;
155 bool hasAttributes() const;
156 XMLString innerText() const;
157
158 Element* getChildElement(const XMLString& name) const;
159 /// Returns the first child element with the given name, or null
160 /// if such an element does not exist.
161 ///
162 /// This method is an extension to the W3C Document Object Model.
163
164 Element* getChildElementNS(const XMLString& namespaceURI, const XMLString& localName) const;
165 /// Returns the first child element with the given namespaceURI and localName,
166 /// or null if such an element does not exist.
167 ///
168 /// This method is an extension to the W3C Document Object Model.
169
170 Element* getElementById(const XMLString& elementId, const XMLString& idAttribute) const;
171 /// Returns the first Element whose ID attribute (given in idAttribute)
172 /// has the given elementId. If no such element exists, returns null.
173 ///
174 /// This method is an extension to the W3C Document Object Model.
175
176 Element* getElementByIdNS(const XMLString& elementId, const XMLString& idAttributeURI, const XMLString& idAttributeLocalName) const;
177 /// Returns the first Element whose ID attribute (given in idAttributeURI and idAttributeLocalName)
178 /// has the given elementId. If no such element exists, returns null.
179 ///
180 /// This method is an extension to the W3C Document Object Model.
181
182 // Node
183 const XMLString& nodeName() const;
184 NamedNodeMap* attributes() const;
185 unsigned short nodeType() const;
186
187protected:
188 Element(Document* pOwnerDocument, const XMLString& namespaceURI, const XMLString& localName, const XMLString& qname);
189 Element(Document* pOwnerDocument, const Element& elem);
190 ~Element();
191
192 Node* copyNode(bool deep, Document* pOwnerDocument) const;
193
194 void dispatchNodeRemovedFromDocument();
195 void dispatchNodeInsertedIntoDocument();
196
197private:
198 const Name& _name;
199 Attr* _pFirstAttr;
200
201 friend class Attr;
202 friend class Document;
203 friend class AttrMap;
204};
205
206
207//
208// inlines
209//
210inline const XMLString& Element::tagName() const
211{
212 return _name.qname();
213}
214
215
216} } // namespace Poco::XML
217
218
219#endif // DOM_Element_INCLUDED
220