xmltooling/util/XMLHelper.h

   1 /*
   2  *  Copyright 2001-2006 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 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/QName.h>
  27 #include <xercesc/dom/DOM.hpp>
  28
  29 using namespace xercesc;
  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         XercesJanitor(T* resource) : m_held(resource) {}
  42
  43         ~XercesJanitor() {
  44             if (m_held)
  45                 m_held->release();
  46         }
  47
  48         /**
  49          * Returns resource held by this object and releases it to the caller.
  50          *
  51          * @return  the resource held or NULL
  52          */
  53         T* release() {
  54             T* ret=m_held;
  55             m_held=NULL;
  56             return ret;
  57         }
  58     };
  59
  60     /**
  61      * A helper class for working with W3C DOM objects.
  62      */
  63     class XMLTOOL_API XMLHelper
  64     {
  65     public:
  66         /**
  67          * Checks if the given element has an xsi:type defined for it
  68          *
  69          * @param e the DOM element
  70          * @return true if there is a type, false if not
  71          */
  72         static bool hasXSIType(const DOMElement* e);
  73
  74         /**
  75          * Gets the XSI type for a given element if it has one.
  76          *
  77          * @param e the element
  78          * @return the type or null
  79          */
  80         static QName* getXSIType(const DOMElement* e);
  81
  82         /**
  83          * Gets the ID attribute of a DOM element.
  84          *
  85          * @param domElement the DOM element
  86          * @return the ID attribute or null if there isn't one
  87          */
  88         static DOMAttr* getIdAttribute(const DOMElement* domElement);
  89
  90         /**
  91          * Gets the QName for the given DOM node.
  92          *
  93          * @param domNode the DOM node
  94          * @return the QName for the element or null if the element was null
  95          */
  96         static QName* getNodeQName(const DOMNode* domNode);
  97
  98         /**
  99          * Constructs a QName from an attribute's value.
 100          *
 101          * @param attribute the attribute with a QName value
 102          * @return a QName from an attribute's value, or null if the given attribute is null
 103          */
 104         static QName* getAttributeValueAsQName(const DOMAttr* attribute);
 105
 106         /**
 107          * Appends the child Element to the parent Element,
 108          * importing the child Element into the parent's Document if needed.
 109          *
 110          * @param parentElement the parent Element
 111          * @param childElement the child Element
 112          * @return the child Element that was added (may be an imported copy)
 113          */
 114         static DOMElement* appendChildElement(DOMElement* parentElement, DOMElement* childElement);
 115
 116         /**
 117          * Checks the qualified name of a node.
 118          *
 119          * @param n     node to check
 120          * @param ns    namespace to compare with
 121          * @param local local name to compare with
 122          * @return  true iff the node's qualified name matches the other parameters
 123          */
 124         static bool isNodeNamed(const DOMNode* n, const XMLCh* ns, const XMLCh* local) {
 125             return (n && XMLString::equals(local,n->getLocalName()) && XMLString::equals(ns,n->getNamespaceURI()));
 126         }
 127
 128         /**
 129          * Returns the first matching child element of the node if any.
 130          *
 131          * @param n         node to check
 132          * @param localName local name to compare with or NULL for any match
 133          * @return  the first matching child node of type Element, or NULL
 134          */
 135         static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* localName=NULL);
 136
 137         /**
 138          * Returns the last matching child element of the node if any.
 139          *
 140          * @param n     node to check
 141          * @param localName local name to compare with or NULL for any match
 142          * @return  the last matching child node of type Element, or NULL
 143          */
 144         static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* localName=NULL);
 145
 146         /**
 147          * Returns the next matching sibling element of the node if any.
 148          *
 149          * @param n     node to check
 150          * @param localName local name to compare with or NULL for any match
 151          * @return  the next matching sibling node of type Element, or NULL
 152          */
 153         static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);
 154
 155         /**
 156          * Returns the previous matching sibling element of the node if any.
 157          *
 158          * @param n     node to check
 159          * @param localName local name to compare with or NULL for any match
 160          * @return  the previous matching sibling node of type Element, or NULL
 161          */
 162         static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);
 163
 164         /**
 165          * Returns the first matching child element of the node if any.
 166          *
 167          * @param n         node to check
 168          * @param ns        namespace to compare with
 169          * @param localName local name to compare with
 170          * @return  the first matching child node of type Element, or NULL
 171          */
 172         static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 173
 174         /**
 175          * Returns the last matching child element of the node if any.
 176          *
 177          * @param n         node to check
 178          * @param ns        namespace to compare with
 179          * @param localName local name to compare with
 180          * @return  the last matching child node of type Element, or NULL
 181          */
 182         static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 183
 184         /**
 185          * Returns the next matching sibling element of the node if any.
 186          *
 187          * @param n         node to check
 188          * @param ns        namespace to compare with
 189          * @param localName local name to compare with
 190          * @return  the next matching sibling node of type Element, or NULL
 191          */
 192         static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 193
 194         /**
 195          * Returns the previous matching sibling element of the node if any.
 196          *
 197          * @param n         node to check
 198          * @param ns        namespace to compare with
 199          * @param localName local name to compare with
 200          * @return  the previous matching sibling node of type Element, or NULL
 201          */
 202         static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);
 203
 204         /**
 205          * Returns the content of the first Text node found in the element, if any.
 206          * This is roughly similar to the DOM getTextContent function, but only
 207          * examples the immediate children of the element.
 208          *
 209          * @param e     element to examine
 210          * @return the content of the first Text node found, or NULL
 211          */
 212         static const XMLCh* getTextContent(const DOMElement* e);
 213
 214         /**
 215          * Serializes the DOM Element provided into a buffer using UTF-8 encoding and
 216          * the default XML serializer available. No manipulation or formatting is applied.
 217          *
 218          * @param e     element to serialize
 219          * @param buf   buffer to serialize element into
 220          */
 221         static void serialize(const DOMElement* e, std::string& buf);
 222     };
 223
 224 };
 225
 226 #endif /* __xmltooling_xmlhelper_h__ */