xmltooling/util/XMLHelper.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file xmltooling/util/XMLHelper.h
  19  *
  20  * A helper class for working with W3C DOM objects.
  21  */
  22
  23 #ifndef __xmltooling_xmlhelper_h__
  24 #define __xmltooling_xmlhelper_h__
  25
  26 #include <xmltooling/XMLObject.h>
  27 #include <xercesc/dom/DOM.hpp>
  28
  29 #include <iostream>
  30
  31 namespace xmltooling {
  32
  33     /**
  34      * RAII wrapper for Xerces resources.
  35      */
  36     template<class T> class XercesJanitor
  37     {
  38         MAKE_NONCOPYABLE(XercesJanitor);
  39         T* m_held;
  40     public:
  41         /**
  42          * Constructor
  43          *
  44          * @param resource  object to release when leaving scope
  45          */
  46         XercesJanitor(T* resource) : m_held(resource) {}
  47
  48         ~XercesJanitor() {
  49             if (m_held)
  50                 m_held->release();
  51         }
  52
  53         /**
  54          * Returns resource held by this object.
  55          *
  56          * @return  the resource held or NULL
  57          */
  58         T* get() {
  59             return m_held;
  60         }
  61
  62         /**
  63          * Returns resource held by this object.
  64          *
  65          * @return  the resource held or NULL
  66          */
  67         T* operator->() {
  68             return m_held;
  69         }
  70
  71         /**
  72          * Returns resource held by this object and releases it to the caller.
  73          *
  74          * @return  the resource held or NULL
  75          */
  76         T* release() {
  77             T* ret=m_held;
  78             m_held=NULL;
  79             return ret;
  80         }
  81     };
  82
  83     /**
  84      * A helper class for working with W3C DOM objects.
  85      */
  86     class XMLTOOL_API XMLHelper
  87     {
  88     public:
  89         /**
  90          * Checks if the given element has an xsi:type defined for it
  91          *
  92          * @param e the DOM element
  93          * @return true if there is a type, false if not
  94          */
  95         static bool hasXSIType(const xercesc::DOMElement* e);
  96
  97         /**
  98          * Gets the XSI type for a given element if it has one.
  99          *
 100          * @param e the element
 101          * @return the type or null
 102          */
 103         static QName* getXSIType(const xercesc::DOMElement* e);
 104
 105         /**
 106          * Gets the ID attribute of a DOM element.
 107          *
 108          * @param domElement the DOM element
 109          * @return the ID attribute or null if there isn't one
 110          */
 111         static xercesc::DOMAttr* getIdAttribute(const xercesc::DOMElement* domElement);
 112
 113         /**
 114          * Attempts to locate an XMLObject from this point downward in the tree whose
 115          * XML ID matches the supplied value.
 116          *
 117          * @param tree  root of tree to search
 118          * @param id    ID value to locate
 119          * @return XMLObject in the tree with a matching ID value, or NULL
 120          */
 121         static const XMLObject* getXMLObjectById(const XMLObject& tree, const XMLCh* id);
 122
 123         /**
 124          * Attempts to locate an XMLObject from this point downward in the tree whose
 125          * XML ID matches the supplied value.
 126          *
 127          * @param tree  root of tree to search
 128          * @param id    ID value to locate
 129          * @return XMLObject in the tree with a matching ID value, or NULL
 130          */
 131         static XMLObject* getXMLObjectById(XMLObject& tree, const XMLCh* id);
 132
 133         /**
 134          * Gets the QName for the given DOM node.
 135          *
 136          * @param domNode the DOM node
 137          * @return the QName for the element or null if the element was null
 138          */
 139         static QName* getNodeQName(const xercesc::DOMNode* domNode);
 140
 141         /**
 142          * @deprecated
 143          * Constructs a QName from an attribute's value.
 144          *
 145          * @param attribute the attribute with a QName value
 146          * @return a QName from an attribute's value, or null if the given attribute is null
 147          */
 148         static QName* getAttributeValueAsQName(const xercesc::DOMAttr* attribute);
 149
 150         /**
 151          * Constructs a QName from a node's value.
 152          *
 153          * @param domNode the DOM node with a QName value
 154          * @return a QName from a node's value, or null if the given node has no value
 155          */
 156         static QName* getNodeValueAsQName(const xercesc::DOMNode* domNode);
 157
 158         /**
 159          * Appends the child Element to the parent Element,
 160          * importing the child Element into the parent's Document if needed.
 161          *
 162          * @param parentElement the parent Element
 163          * @param childElement the child Element
 164          * @return the child Element that was added (may be an imported copy)
 165          */
 166         static xercesc::DOMElement* appendChildElement(xercesc::DOMElement* parentElement, xercesc::DOMElement* childElement);
 167
 168         /**
 169          * Checks the qualified name of a node.
 170          *
 171          * @param n     node to check
 172          * @param ns    namespace to compare with
 173          * @param local local name to compare with
 174          * @return  true iff the node's qualified name matches the other parameters
 175          */
 176         static bool isNodeNamed(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* local) {
 177             return (n && xercesc::XMLString::equals(local,n->getLocalName()) && xercesc::XMLString::equals(ns,n->getNamespaceURI()));
 178         }
 179
 180         /**
 181          * Returns the first matching child element of the node if any.
 182          *
 183          * @param n         node to check
 184          * @param localName local name to compare with or NULL for any match
 185          * @return  the first matching child node of type Element, or NULL
 186          */
 187         static xercesc::DOMElement* getFirstChildElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
 188
 189         /**
 190          * Returns the last matching child element of the node if any.
 191          *
 192          * @param n     node to check
 193          * @param localName local name to compare with or NULL for any match
 194          * @return  the last matching child node of type Element, or NULL
 195          */
 196         static xercesc::DOMElement* getLastChildElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
 197
 198         /**
 199          * Returns the next matching sibling element of the node if any.
 200          *
 201          * @param n     node to check
 202          * @param localName local name to compare with or NULL for any match
 203          * @return  the next matching sibling node of type Element, or NULL
 204          */
 205         static xercesc::DOMElement* getNextSiblingElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
 206
 207         /**
 208          * Returns the previous matching sibling element of the node if any.
 209          *
 210          * @param n     node to check
 211          * @param localName local name to compare with or NULL for any match
 212          * @return  the previous matching sibling node of type Element, or NULL
 213          */
 214         static xercesc::DOMElement* getPreviousSiblingElement(const xercesc::DOMNode* n, const XMLCh* localName=NULL);
 215
 216         /**
 217          * Returns the first matching child element of the node if any.
 218          *
 219          * @param n         node to check
 220          * @param ns        namespace to compare with
 221          * @param localName local name to compare with
 222          * @return  the first matching child node of type Element, or NULL
 223          */
 224         static xercesc::DOMElement* getFirstChildElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 225
 226         /**
 227          * Returns the last matching child element of the node if any.
 228          *
 229          * @param n         node to check
 230          * @param ns        namespace to compare with
 231          * @param localName local name to compare with
 232          * @return  the last matching child node of type Element, or NULL
 233          */
 234         static xercesc::DOMElement* getLastChildElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 235
 236         /**
 237          * Returns the next matching sibling element of the node if any.
 238          *
 239          * @param n         node to check
 240          * @param ns        namespace to compare with
 241          * @param localName local name to compare with
 242          * @return  the next matching sibling node of type Element, or NULL
 243          */
 244         static xercesc::DOMElement* getNextSiblingElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 245
 246         /**
 247          * Returns the previous matching sibling element of the node if any.
 248          *
 249          * @param n         node to check
 250          * @param ns        namespace to compare with
 251          * @param localName local name to compare with
 252          * @return  the previous matching sibling node of type Element, or NULL
 253          */
 254         static xercesc::DOMElement* getPreviousSiblingElement(const xercesc::DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 255
 256         /**
 257          * Returns the content of the first Text node found in the element, if any.
 258          * This is roughly similar to the DOM getTextContent function, but only
 259          * examples the immediate children of the element.
 260          *
 261          * @param e     element to examine
 262          * @return the content of the first Text node found, or NULL
 263          */
 264         static const XMLCh* getTextContent(const xercesc::DOMElement* e);
 265
 266         /**
 267          * Serializes the DOM node provided into a buffer using UTF-8 encoding and
 268          * the default XML serializer available. No manipulation or formatting is applied.
 269          *
 270          * @param n         node to serialize
 271          * @param buf       buffer to serialize element into
 272          * @param pretty    enable pretty printing if supported
 273          */
 274         static void serialize(const xercesc::DOMNode* n, std::string& buf, bool pretty=false);
 275
 276         /**
 277          * Serializes the DOM node provided to a stream using UTF-8 encoding and
 278          * the default XML serializer available. No manipulation or formatting is applied.
 279          *
 280          * @param n         node to serialize
 281          * @param out       stream to serialize element into
 282          * @param pretty    enable pretty printing if supported
 283          * @return reference to output stream
 284          */
 285         static std::ostream& serialize(const xercesc::DOMNode* n, std::ostream& out, bool pretty=false);
 286     };
 287
 288     /**
 289      * Serializes the DOM node provided to a stream using UTF-8 encoding and
 290      * the default XML serializer available. No manipulation or formatting is applied.
 291      *
 292      * @param n      node to serialize
 293      * @param ostr   stream to serialize element into
 294      * @return reference to output stream
 295      */
 296     extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const xercesc::DOMNode& n);
 297
 298     /**
 299      * Marshalls and serializes the XMLObject provided to a stream using UTF-8 encoding and
 300      * the default XML serializer available. No manipulation or formatting is applied.
 301      *
 302      * <p>The marshaller operation takes no parameters.
 303      *
 304      * @param obj    object to serialize
 305      * @param ostr   stream to serialize object into
 306      * @return reference to output stream
 307      */
 308     extern XMLTOOL_API std::ostream& operator<<(std::ostream& ostr, const XMLObject& obj);
 309 };
 310
 311 #endif /* __xmltooling_xmlhelper_h__ */