xmltooling/util/XMLHelper.h

   1 /*\r
   2  *  Copyright 2001-2006 Internet2\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *     http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 /**\r
  18  * @file XMLHelper.h\r
  19  * \r
  20  * A helper class for working with W3C DOM objects. \r
  21  */\r
  22 \r
  23 #ifndef __xmltooling_xmlhelper_h__\r
  24 #define __xmltooling_xmlhelper_h__\r
  25 \r
  26 #include <xmltooling/QName.h>\r
  27 #include <xercesc/dom/DOM.hpp>\r
  28 \r
  29 using namespace xercesc;\r
  30 \r
  31 namespace xmltooling {\r
  32     \r
  33     /**\r
  34      * RAII wrapper for Xerces resources.\r
  35      */\r
  36     template<class T> class XercesJanitor\r
  37     {\r
  38         MAKE_NONCOPYABLE(XercesJanitor);\r
  39         T* m_held;\r
  40     public:\r
  41         XercesJanitor(T* resource) : m_held(resource) {}\r
  42         \r
  43         ~XercesJanitor() {\r
  44             if (m_held)\r
  45                 m_held->release();\r
  46         }\r
  47         \r
  48         /**\r
  49          * Returns resource held by this object and releases it to the caller.\r
  50          * \r
  51          * @return  the resource held or NULL\r
  52          */\r
  53         T* release() {\r
  54             T* ret=m_held;\r
  55             m_held=NULL;\r
  56             return ret;\r
  57         }\r
  58     };\r
  59     \r
  60     /**\r
  61      * A helper class for working with W3C DOM objects. \r
  62      */\r
  63     class XMLTOOL_API XMLHelper\r
  64     {\r
  65     public:\r
  66         /**\r
  67          * Checks if the given element has an xsi:type defined for it\r
  68          * \r
  69          * @param e the DOM element\r
  70          * @return true if there is a type, false if not\r
  71          */\r
  72         static bool hasXSIType(const DOMElement* e);\r
  73 \r
  74         /**\r
  75          * Gets the XSI type for a given element if it has one.\r
  76          * \r
  77          * @param e the element\r
  78          * @return the type or null\r
  79          */\r
  80         static QName* getXSIType(const DOMElement* e);\r
  81 \r
  82         /**\r
  83          * Gets the ID attribute of a DOM element.\r
  84          * \r
  85          * @param domElement the DOM element\r
  86          * @return the ID attribute or null if there isn't one\r
  87          */\r
  88         static DOMAttr* getIdAttribute(const DOMElement* domElement);\r
  89 \r
  90         /**\r
  91          * Gets the QName for the given DOM node.\r
  92          * \r
  93          * @param domNode the DOM node\r
  94          * @return the QName for the element or null if the element was null\r
  95          */\r
  96         static QName* getNodeQName(const DOMNode* domNode);\r
  97 \r
  98         /**\r
  99          * Constructs a QName from an attribute's value.\r
 100          * \r
 101          * @param attribute the attribute with a QName value\r
 102          * @return a QName from an attribute's value, or null if the given attribute is null\r
 103          */\r
 104         static QName* getAttributeValueAsQName(const DOMAttr* attribute);\r
 105 \r
 106         /**\r
 107          * Appends the child Element to the parent Element,\r
 108          * importing the child Element into the parent's Document if needed.\r
 109          * \r
 110          * @param parentElement the parent Element\r
 111          * @param childElement the child Element\r
 112          * @return the child Element that was added (may be an imported copy)\r
 113          */\r
 114         static DOMElement* appendChildElement(DOMElement* parentElement, DOMElement* childElement);\r
 115         \r
 116         /**\r
 117          * Checks the qualified name of a node.\r
 118          * \r
 119          * @param n     node to check\r
 120          * @param ns    namespace to compare with\r
 121          * @param local local name to compare with\r
 122          * @return  true iff the node's qualified name matches the other parameters\r
 123          */\r
 124         static bool isNodeNamed(const DOMNode* n, const XMLCh* ns, const XMLCh* local) {\r
 125             return (n && XMLString::equals(local,n->getLocalName()) && XMLString::equals(ns,n->getNamespaceURI()));\r
 126         }\r
 127 \r
 128         /**\r
 129          * Returns the first matching child element of the node if any.\r
 130          * \r
 131          * @param n         node to check\r
 132          * @param localName local name to compare with or NULL for any match\r
 133          * @return  the first matching child node of type Element, or NULL\r
 134          */\r
 135         static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* localName=NULL);\r
 136         \r
 137         /**\r
 138          * Returns the last matching child element of the node if any.\r
 139          * \r
 140          * @param n     node to check\r
 141          * @param localName local name to compare with or NULL for any match\r
 142          * @return  the last matching child node of type Element, or NULL\r
 143          */\r
 144         static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* localName=NULL);\r
 145         \r
 146         /**\r
 147          * Returns the next matching sibling element of the node if any.\r
 148          * \r
 149          * @param n     node to check\r
 150          * @param localName local name to compare with or NULL for any match\r
 151          * @return  the next matching sibling node of type Element, or NULL\r
 152          */\r
 153         static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);\r
 154         \r
 155         /**\r
 156          * Returns the previous matching sibling element of the node if any.\r
 157          * \r
 158          * @param n     node to check\r
 159          * @param localName local name to compare with or NULL for any match\r
 160          * @return  the previous matching sibling node of type Element, or NULL\r
 161          */\r
 162         static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);\r
 163         \r
 164         /**\r
 165          * Returns the first matching child element of the node if any.\r
 166          * \r
 167          * @param n         node to check\r
 168          * @param ns        namespace to compare with\r
 169          * @param localName local name to compare with\r
 170          * @return  the first matching child node of type Element, or NULL\r
 171          */\r
 172         static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);\r
 173         \r
 174         /**\r
 175          * Returns the last matching child element of the node if any.\r
 176          * \r
 177          * @param n         node to check\r
 178          * @param ns        namespace to compare with\r
 179          * @param localName local name to compare with\r
 180          * @return  the last matching child node of type Element, or NULL\r
 181          */\r
 182         static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);\r
 183         \r
 184         /**\r
 185          * Returns the next matching sibling element of the node if any.\r
 186          * \r
 187          * @param n         node to check\r
 188          * @param ns        namespace to compare with\r
 189          * @param localName local name to compare with\r
 190          * @return  the next matching sibling node of type Element, or NULL\r
 191          */\r
 192         static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);\r
 193         \r
 194         /**\r
 195          * Returns the previous matching sibling element of the node if any.\r
 196          * \r
 197          * @param n         node to check\r
 198          * @param ns        namespace to compare with\r
 199          * @param localName local name to compare with\r
 200          * @return  the previous matching sibling node of type Element, or NULL\r
 201          */\r
 202         static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* ns, const XMLCh* localName);\r
 203 \r
 204         /**\r
 205          * Returns the content of the first Text node found in the element, if any.\r
 206          * This is roughly similar to the DOM getTextContent function, but only\r
 207          * examples the immediate children of the element.\r
 208          *\r
 209          * @param e     element to examine\r
 210          * @return the content of the first Text node found, or NULL\r
 211          */\r
 212         static const XMLCh* getTextContent(const DOMElement* e);\r
 213 \r
 214         /**\r
 215          * Serializes the DOM Element provided into a buffer using UTF-8 encoding and\r
 216          * the default XML serializer available. No manipulation or formatting is applied.\r
 217          * \r
 218          * @param e     element to serialize\r
 219          * @param buf   buffer to serialize element into\r
 220          */\r
 221         static void serialize(const DOMElement* e, std::string& buf);\r
 222     };\r
 223 \r
 224 };\r
 225 \r
 226 #endif /* __xmltooling_xmlhelper_h__ */\r