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