Merged marshalling/unmarshalling methods into core interface.

[shibboleth/cpp-xmltooling.git] / xmltooling / XMLObject.h

diff --git a/xmltooling/XMLObject.h b/xmltooling/XMLObject.h
index 1ff2ce7..b613e50 100644 (file)
--- a/xmltooling/XMLObject.h
+++ b/xmltooling/XMLObject.h
@@ -25,11 +25,46 @@
 \r
 #include <set>\r
 #include <list>\r
+#include <vector>\r
+#include <xercesc/dom/DOM.hpp>\r
 #include <xmltooling/QName.h>\r
 #include <xmltooling/Namespace.h>\r
 \r
+using namespace xercesc;\r
+\r
+#if defined (_MSC_VER)\r
+    #pragma warning( push )\r
+    #pragma warning( disable : 4250 4251 )\r
+#endif\r
+\r
 namespace xmltooling {\r
 \r
+#ifndef XMLTOOLING_NO_XMLSEC\r
+    class XMLTOOL_API Signature;\r
+    class XMLTOOL_API SigningContext;\r
+#endif\r
+\r
+    /**\r
+     * Supplies additional information to the marshalling process.\r
+     * Currently this only consists of signature related information.\r
+     */\r
+    class XMLTOOL_API MarshallingContext\r
+    {\r
+        MAKE_NONCOPYABLE(MarshallingContext);\r
+    public:\r
+        MarshallingContext() {}\r
+        ~MarshallingContext() {}\r
+\r
+#ifndef XMLTOOLING_NO_XMLSEC\r
+        MarshallingContext(Signature* sig, const SigningContext* ctx) {\r
+            m_signingContexts.push_back(std::make_pair(sig,ctx));\r
+        }\r
+        \r
+        /** Array of signing contexts, keyed off of the associated Signature */\r
+        std::vector< std::pair<Signature*,const SigningContext*> > m_signingContexts;\r
+#endif\r
+    };\r
+\r
     /**\r
      * Object that represents an XML Element that has been unmarshalled into this C++ object.\r
      */\r
@@ -79,7 +114,7 @@ namespace xmltooling {
          * \r
          * @param ns the namespace to add\r
          */\r
-        virtual void addNamespace(const Namespace& ns)=0;\r
+        virtual void addNamespace(const Namespace& ns) const=0;\r
         \r
         /**\r
          * Removes a namespace from this element\r
@@ -143,10 +178,60 @@ namespace xmltooling {
          */\r
         virtual const std::list<XMLObject*>& getOrderedChildren() const=0;\r
 \r
+        /**\r
+         * Marshalls the XMLObject, and its children, into a DOM element.\r
+         * If a document is supplied, then it will be used to create the resulting elements.\r
+         * If the document does not have a Document Element set, then the resulting\r
+         * element will be set as the Document Element. If no document is supplied, then\r
+         * a new document will be created and bound to the lifetime of the root object being\r
+         * marshalled, unless an existing DOM can be reused without creating a new document. \r
+         * \r
+         * @param document  the DOM document the marshalled element will be placed in, or NULL\r
+         * @param ctx       optional marshalling context\r
+         * @return the DOM element representing this XMLObject\r
+         * \r
+         * @throws MarshallingException thrown if there is a problem marshalling the given object\r
+         * @throws SignatureException thrown if a problem occurs during signature creation \r
+         */\r
+        virtual DOMElement* marshall(DOMDocument* document=NULL, MarshallingContext* ctx=NULL) const=0;\r
+        \r
+        /**\r
+         * Marshalls the XMLObject and appends it as a child of the given parent element.\r
+         * \r
+         * <strong>NOTE:</strong> The given Element must be within a DOM tree rooted in \r
+         * the Document owning the given Element.\r
+         * \r
+         * @param parentElement the parent element to append the resulting DOM tree\r
+         * @param ctx       optional marshalling context\r
+         * @return the marshalled element tree\r
+\r
+         * @throws MarshallingException thrown if the given XMLObject can not be marshalled.\r
+         * @throws SignatureException thrown if a problem occurs during signature creation \r
+         */\r
+        virtual DOMElement* marshall(DOMElement* parentElement, MarshallingContext* ctx=NULL) const=0;\r
+\r
+        /**\r
+         * Unmarshalls the given W3C DOM element into the XMLObject.\r
+         * The root of a given XML construct should be unmarshalled with the bindDocument parameter\r
+         * set to true.\r
+         * \r
+         * @param element       the DOM element to unmarshall\r
+         * @param bindDocument  true iff the resulting XMLObject should take ownership of the DOM's Document \r
+         * \r
+         * @return the unmarshalled XMLObject\r
+         * \r
+         * @throws UnmarshallingException thrown if an error occurs unmarshalling the DOM element into the XMLObject\r
+         */\r
+        virtual XMLObject* unmarshall(DOMElement* element, bool bindDocument=false)=0;\r
+\r
     protected:\r
         XMLObject() {}\r
     };\r
 \r
+#if defined (_MSC_VER)\r
+    #pragma warning( pop )\r
+#endif\r
+\r
 };\r
 \r
 #endif /* __xmltooling_xmlobj_h__ */\r