Multi-line svn commit, see body.

[shibboleth/cpp-xmltooling.git] / xmltooling / util / XMLHelper.h

diff --git a/xmltooling/util/XMLHelper.h b/xmltooling/util/XMLHelper.h
index ac6f240..df33c63 100644 (file)
--- a/xmltooling/util/XMLHelper.h
+++ b/xmltooling/util/XMLHelper.h
@@ -20,7 +20,7 @@
  * A helper class for working with W3C DOM objects. \r
  */\r
 \r
-#if !defined(__xmltooling_xmlhelper_h__)\r
+#ifndef __xmltooling_xmlhelper_h__\r
 #define __xmltooling_xmlhelper_h__\r
 \r
 #include <xmltooling/QName.h>\r
@@ -31,6 +31,33 @@ using namespace xercesc;
 namespace xmltooling {\r
     \r
     /**\r
+     * RAII wrapper for Xerces resources.\r
+     */\r
+    template<class T> class XercesJanitor\r
+    {\r
+        MAKE_NONCOPYABLE(XercesJanitor);\r
+        T* m_held;\r
+    public:\r
+        XercesJanitor(T* resource) : m_held(resource) {}\r
+        \r
+        ~XercesJanitor() {\r
+            if (m_held)\r
+                m_held->release();\r
+        }\r
+        \r
+        /**\r
+         * Returns resource held by this object and releases it to the caller.\r
+         * \r
+         * @return  the resource held or NULL\r
+         */\r
+        T* release() {\r
+            T* ret=m_held;\r
+            m_held=NULL;\r
+            return ret;\r
+        }\r
+    };\r
+    \r
+    /**\r
      * A helper class for working with W3C DOM objects. \r
      */\r
     class XMLTOOL_API XMLHelper\r
@@ -69,10 +96,10 @@ namespace xmltooling {
         static QName* getNodeQName(const DOMNode* domNode);\r
 \r
         /**\r
-         * Constructs a QName from an attributes value.\r
+         * Constructs a QName from an attribute's value.\r
          * \r
          * @param attribute the attribute with a QName value\r
-         * @return a QName from an attributes value, or null if the given attribute is null\r
+         * @return a QName from an attribute's value, or null if the given attribute is null\r
          */\r
         static QName* getAttributeValueAsQName(const DOMAttr* attribute);\r
 \r
@@ -99,36 +126,40 @@ namespace xmltooling {
         }\r
 \r
         /**\r
-         * Returns the first child element of the node if any.\r
+         * Returns the first matching child element of the node if any.\r
          * \r
-         * @param n     node to check\r
-         * @return  the first child node of type Element, or NULL\r
+         * @param n         node to check\r
+         * @param localName local name to compare with or NULL for any match\r
+         * @return  the first matching child node of type Element, or NULL\r
          */\r
-        static DOMElement* getFirstChildElement(const DOMNode* n);\r
+        static DOMElement* getFirstChildElement(const DOMNode* n, const XMLCh* localName=NULL);\r
         \r
         /**\r
-         * Returns the last child element of the node if any.\r
+         * Returns the last matching child element of the node if any.\r
          * \r
          * @param n     node to check\r
-         * @return  the last child node of type Element, or NULL\r
+         * @param localName local name to compare with or NULL for any match\r
+         * @return  the last matching child node of type Element, or NULL\r
          */\r
-        static DOMElement* getLastChildElement(const DOMNode* n);\r
+        static DOMElement* getLastChildElement(const DOMNode* n, const XMLCh* localName=NULL);\r
         \r
         /**\r
-         * Returns the next sibling element of the node if any.\r
+         * Returns the next matching sibling element of the node if any.\r
          * \r
          * @param n     node to check\r
-         * @return  the next sibling node of type Element, or NULL\r
+         * @param localName local name to compare with or NULL for any match\r
+         * @return  the next matching sibling node of type Element, or NULL\r
          */\r
-        static DOMElement* getNextSiblingElement(const DOMNode* n);\r
+        static DOMElement* getNextSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);\r
         \r
         /**\r
-         * Returns the previous sibling element of the node if any.\r
+         * Returns the previous matching sibling element of the node if any.\r
          * \r
          * @param n     node to check\r
-         * @return  the previous sibling node of type Element, or NULL\r
+         * @param localName local name to compare with or NULL for any match\r
+         * @return  the previous matching sibling node of type Element, or NULL\r
          */\r
-        static DOMElement* getPreviousSiblingElement(const DOMNode* n);\r
+        static DOMElement* getPreviousSiblingElement(const DOMNode* n, const XMLCh* localName=NULL);\r
         \r
         /**\r
          * Returns the first matching child element of the node if any.\r