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