2 * Copyright 2001-2009 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.
18 * @file xmltooling/util/XMLHelper.h
20 * A helper class for working with W3C DOM objects.
23 #ifndef __xmltooling_xmlhelper_h__
24 #define __xmltooling_xmlhelper_h__
26 #include <xmltooling/base.h>
29 #include <xercesc/dom/DOM.hpp>
31 namespace xmltooling {
33 class XMLTOOL_API QName;
34 class XMLTOOL_API XMLObject;
37 * RAII wrapper for Xerces resources.
39 template<class T> class XercesJanitor
41 MAKE_NONCOPYABLE(XercesJanitor);
47 * @param resource object to release when leaving scope
49 XercesJanitor(T* resource) : m_held(resource) {}
57 * Returns resource held by this object.
59 * @return the resource held or NULL
66 * Returns resource held by this object.
68 * @return the resource held or NULL
75 * Returns resource held by this object and releases it to the caller.
77 * @return the resource held or NULL
87 * A helper class for working with W3C DOM objects.
89 class XMLTOOL_API XMLHelper
93 * Checks if the given element has an xsi:type defined for it
95 * @param e the DOM element
96 * @return true if there is a type, false if not
98 static bool hasXSIType(const xercesc::DOMElement* e);
101 * Gets the XSI type for a given element if it has one.
103 * @param e the element
104 * @return the type or null
106 static QName* getXSIType(const xercesc::DOMElement* e);
109 * Gets the ID attribute of a DOM element.
111 * @param domElement the DOM element
112 * @return the ID attribute or null if there isn't one
114 static xercesc::DOMAttr* getIdAttribute(const xercesc::DOMElement* domElement);
117 * Attempts to locate an XMLObject from this point downward in the tree whose
118 * XML ID matches the supplied value.
120 * @param tree root of tree to search
121 * @param id ID value to locate
122 * @return XMLObject in the tree with a matching ID value, or NULL
124 static const XMLObject* getXMLObjectById(const XMLObject& tree, const XMLCh* id);
127 * Attempts to locate an XMLObject from this point downward in the tree whose
128 * XML ID matches the supplied value.
130 * @param tree root of tree to search
131 * @param id ID value to locate
132 * @return XMLObject in the tree with a matching ID value, or NULL
134 static XMLObject* getXMLObjectById(XMLObject& tree, const XMLCh* id);
137 * Gets the QName for the given DOM node.
139 * @param domNode the DOM node
140 * @return the QName for the element or null if the element was null
142 static QName* getNodeQName(const xercesc::DOMNode* domNode);
146 * Constructs a QName from an attribute's value.
148 * @param attribute the attribute with a QName value
149 * @return a QName from an attribute's value, or null if the given attribute is null
151 static QName* getAttributeValueAsQName(const xercesc::DOMAttr* attribute);
154 * Constructs a QName from a node's value.
156 * @param domNode the DOM node with a QName value
157 * @return a QName from a node's value, or null if the given node has no value
159 static QName* getNodeValueAsQName(const xercesc::DOMNode* domNode);
162 * Appends the child Element to the parent Element,
163 * importing the child Element into the parent's Document if needed.
165 * @param parentElement the parent Element
166 * @param childElement the child Element
167 * @return the child Element that was added (may be an imported copy)
169 static xercesc::DOMElement* appendChildElement(xercesc::DOMElement* parentElement, xercesc::DOMElement* childElement);
172 * Checks the qualified name of a node.
174 * @param n node to check
175 * @param ns namespace to compare with
176 * @param local local name to compare with
177 * @return true iff the node's qualified name matches the other parameters
179 static bool isNodeNamed(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* local) {
180 return (n && xercesc::XMLString::equals(local,n->getLocalName()) && xercesc::XMLString::equals(ns,n->getNamespaceURI()));
184 * Returns the first matching child element of the node if any.
186 * @param n node to check
187 * @param localName local name to compare with or NULL for any match
188 * @return the first matching child node of type Element, or NULL
190 static xercesc::DOMElement* getFirstChildElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
193 * Returns the last matching child element of the node if any.
195 * @param n node to check
196 * @param localName local name to compare with or NULL for any match
197 * @return the last matching child node of type Element, or NULL
199 static xercesc::DOMElement* getLastChildElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
202 * Returns the next matching sibling element of the node if any.
204 * @param n node to check
205 * @param localName local name to compare with or NULL for any match
206 * @return the next matching sibling node of type Element, or NULL
208 static xercesc::DOMElement* getNextSiblingElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
211 * Returns the previous matching sibling element of the node if any.
213 * @param n node to check
214 * @param localName local name to compare with or NULL for any match
215 * @return the previous matching sibling node of type Element, or NULL
217 static xercesc::DOMElement* getPreviousSiblingElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
220 * Returns the first matching child element of the node if any.
222 * @param n node to check
223 * @param ns namespace to compare with
224 * @param localName local name to compare with
225 * @return the first matching child node of type Element, or NULL
227 static xercesc::DOMElement* getFirstChildElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
230 * Returns the last matching child element of the node if any.
232 * @param n node to check
233 * @param ns namespace to compare with
234 * @param localName local name to compare with
235 * @return the last matching child node of type Element, or NULL
237 static xercesc::DOMElement* getLastChildElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
240 * Returns the next matching sibling element of the node if any.
242 * @param n node to check
243 * @param ns namespace to compare with
244 * @param localName local name to compare with
245 * @return the next matching sibling node of type Element, or NULL
247 static xercesc::DOMElement* getNextSiblingElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
250 * Returns the previous matching sibling element of the node if any.
252 * @param n node to check
253 * @param ns namespace to compare with
254 * @param localName local name to compare with
255 * @return the previous matching sibling node of type Element, or NULL
257 static xercesc::DOMElement* getPreviousSiblingElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
260 * Returns the content of the first Text node found in the element, if any.
261 * This is roughly similar to the DOM getTextContent function, but only
262 * examples the immediate children of the element.
264 * @param e element to examine
265 * @return the content of the first Text node found, or NULL
267 static const XMLCh* getTextContent(const xercesc::DOMElement* e);
270 * Serializes the DOM node provided into a buffer using UTF-8 encoding and
271 * the default XML serializer available. No manipulation or formatting is applied.
273 * @param n node to serialize
274 * @param buf buffer to serialize element into
275 * @param pretty enable pretty printing if supported
277 static void serialize(const xercesc::DOMNode* n, std::string& buf, bool pretty=false);
280 * Serializes the DOM node provided to a stream using UTF-8 encoding and
281 * the default XML serializer available. No manipulation or formatting is applied.
283 * @param n node to serialize
284 * @param out stream to serialize element into
285 * @param pretty enable pretty printing if supported
286 * @return reference to output stream
288 static std::ostream& serialize(const xercesc::DOMNode* n, std::ostream& out, bool pretty=false);
292 * Serializes the DOM node provided to a stream using UTF-8 encoding and
293 * the default XML serializer available. No manipulation or formatting is applied.
295 * @param n node to serialize
296 * @param ostr stream to serialize element into
297 * @return reference to output stream
299 extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const xercesc::DOMNode& n);
302 * Marshalls and serializes the XMLObject provided to a stream using UTF-8 encoding and
303 * the default XML serializer available. No manipulation or formatting is applied.
305 * <p>The marshaller operation takes no parameters.
307 * @param obj object to serialize
308 * @param ostr stream to serialize object into
309 * @return reference to output stream
311 extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const XMLObject& obj);
314 #endif /* __xmltooling_xmlhelper_h__ */