2 * Copyright 2001-2006 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
20 * A helper class for working with W3C DOM objects.
23 #ifndef __xmltooling_xmlhelper_h__
24 #define __xmltooling_xmlhelper_h__
26 #include <xmltooling/XMLObject.h>
27 #include <xercesc/dom/DOM.hpp>
31 using namespace xercesc;
33 namespace xmltooling {
36 * RAII wrapper for Xerces resources.
38 template<class T> class XercesJanitor
40 MAKE_NONCOPYABLE(XercesJanitor);
43 XercesJanitor(T* resource) : m_held(resource) {}
51 * Returns resource held by this object and releases it to the caller.
53 * @return the resource held or NULL
63 * A helper class for working with W3C DOM objects.
65 class XMLTOOL_API XMLHelper
69 * Checks if the given element has an xsi:type defined for it
71 * @param e the DOM element
72 * @return true if there is a type, false if not
74 static bool hasXSIType(const DOMElement* e);
77 * Gets the XSI type for a given element if it has one.
79 * @param e the element
80 * @return the type or null
82 static QName* getXSIType(const DOMElement* e);
85 * Gets the ID attribute of a DOM element.
87 * @param domElement the DOM element
88 * @return the ID attribute or null if there isn't one
90 static DOMAttr* getIdAttribute(const DOMElement* domElement);
93 * Gets the QName for the given DOM node.
95 * @param domNode the DOM node
96 * @return the QName for the element or null if the element was null
98 static QName* getNodeQName(const DOMNode* domNode);
101 * Constructs a QName from an attribute's value.
103 * @param attribute the attribute with a QName value
104 * @return a QName from an attribute's value, or null if the given attribute is null
106 static QName* getAttributeValueAsQName(const DOMAttr* attribute);
109 * Appends the child Element to the parent Element,
110 * importing the child Element into the parent's Document if needed.
112 * @param parentElement the parent Element
113 * @param childElement the child Element
114 * @return the child Element that was added (may be an imported copy)
116 static DOMElement* appendChildElement(DOMElement* parentElement, DOMElement* childElement);
119 * Checks the qualified name of a node.
121 * @param n node to check
122 * @param ns namespace to compare with
123 * @param local local name to compare with
124 * @return true iff the node's qualified name matches the other parameters
126 static bool isNodeNamed(const DOMNode* n, const XMLCh* ns, const XMLCh* local) {
127 return (n && XMLString::equals(local,n->getLocalName()) && XMLString::equals(ns,n->getNamespaceURI()));
131 * Returns the first matching child element of the node if any.
133 * @param n node to check
134 * @param localName local name to compare with or NULL for any match
135 * @return the first matching child node of type Element, or NULL
137 static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* localName=NULL);
140 * Returns the last matching child element of the node if any.
142 * @param n node to check
143 * @param localName local name to compare with or NULL for any match
144 * @return the last matching child node of type Element, or NULL
146 static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* localName=NULL);
149 * Returns the next matching sibling element of the node if any.
151 * @param n node to check
152 * @param localName local name to compare with or NULL for any match
153 * @return the next matching sibling node of type Element, or NULL
155 static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);
158 * Returns the previous matching sibling element of the node if any.
160 * @param n node to check
161 * @param localName local name to compare with or NULL for any match
162 * @return the previous matching sibling node of type Element, or NULL
164 static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);
167 * Returns the first matching child element of the node if any.
169 * @param n node to check
170 * @param ns namespace to compare with
171 * @param localName local name to compare with
172 * @return the first matching child node of type Element, or NULL
174 static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
177 * Returns the last matching child element of the node if any.
179 * @param n node to check
180 * @param ns namespace to compare with
181 * @param localName local name to compare with
182 * @return the last matching child node of type Element, or NULL
184 static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
187 * Returns the next matching sibling element of the node if any.
189 * @param n node to check
190 * @param ns namespace to compare with
191 * @param localName local name to compare with
192 * @return the next matching sibling node of type Element, or NULL
194 static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
197 * Returns the previous matching sibling element of the node if any.
199 * @param n node to check
200 * @param ns namespace to compare with
201 * @param localName local name to compare with
202 * @return the previous matching sibling node of type Element, or NULL
204 static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
207 * Returns the content of the first Text node found in the element, if any.
208 * This is roughly similar to the DOM getTextContent function, but only
209 * examples the immediate children of the element.
211 * @param e element to examine
212 * @return the content of the first Text node found, or NULL
214 static const XMLCh* getTextContent(const DOMElement* e);
217 * Serializes the DOM node provided into a buffer using UTF-8 encoding and
218 * the default XML serializer available. No manipulation or formatting is applied.
220 * @param n node to serialize
221 * @param buf buffer to serialize element into
223 static void serialize(const DOMNode* n, std::string& buf);
226 * Serializes the DOM node provided to a stream using UTF-8 encoding and
227 * the default XML serializer available. No manipulation or formatting is applied.
229 * @param n node to serialize
230 * @param out stream to serialize element into
232 static void serialize(const DOMNode* n, std::ostream& out);
236 * Serializes the DOM node provided to a stream using UTF-8 encoding and
237 * the default XML serializer available. No manipulation or formatting is applied.
239 * @param n node to serialize
240 * @param ostr stream to serialize element into
241 * @return reference to output stream
243 extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const DOMNode& n);
246 * Marshalls and serializes the XMLObject provided to a stream using UTF-8 encoding and
247 * the default XML serializer available. No manipulation or formatting is applied.
249 * <p>The marshaller operation takes no parameters.
251 * @param obj object to serialize
252 * @param ostr stream to serialize object into
253 * @return reference to output stream
255 extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const XMLObject& obj);
258 #endif /* __xmltooling_xmlhelper_h__ */