Tagging 1.1 release.

[shibboleth/xmltooling.git] / xmltooling / XMLObjectBuilder.h

diff --git a/xmltooling/XMLObjectBuilder.h b/xmltooling/XMLObjectBuilder.h
index de34c89..ef54e17 100644 (file)
--- a/xmltooling/XMLObjectBuilder.h
+++ b/xmltooling/XMLObjectBuilder.h
@@ -1,5 +1,5 @@
 /*\r
- *  Copyright 2001-2006 Internet2\r
+ *  Copyright 2001-2007 Internet2\r
  * \r
  * Licensed under the Apache License, Version 2.0 (the "License");\r
  * you may not use this file except in compliance with the License.\r
@@ -15,20 +15,19 @@
  */\r
 \r
 /**\r
- * @file XMLObjectBuilder.h\r
+ * @file xmltooling/XMLObjectBuilder.h\r
  * \r
- * Factory interface for XMLObjects \r
+ * Factory interface for XMLObjects.\r
  */\r
 \r
-#if !defined(__xmltooling_xmlobjbuilder_h__)\r
+#ifndef __xmltooling_xmlobjbuilder_h__\r
 #define __xmltooling_xmlobjbuilder_h__\r
 \r
 #include <map>\r
-#include <xercesc/dom/DOM.hpp>\r
+#include <memory>\r
 #include <xmltooling/QName.h>\r
 #include <xmltooling/XMLObject.h>\r
-\r
-using namespace xercesc;\r
+#include <xmltooling/util/XMLHelper.h>\r
 \r
 #if defined (_MSC_VER)\r
     #pragma warning( push )\r
@@ -48,21 +47,65 @@ namespace xmltooling {
         virtual ~XMLObjectBuilder() {}\r
         \r
         /**\r
-         * Creates an empty XMLObject.\r
+         * Creates an empty XMLObject with a particular element name.\r
+         * <p>The results are undefined if localName is NULL or empty.\r
          * \r
+         * @param nsURI         namespace URI for element\r
+         * @param localName     local name of element\r
+         * @param prefix        prefix of element name\r
+         * @param schemaType    xsi:type of the object\r
          * @return the empty XMLObject\r
          */\r
-        virtual XMLObject* buildObject() const=0;\r
+        virtual XMLObject* buildObject(\r
+            const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=NULL, const QName* schemaType=NULL\r
+            ) const=0;\r
+\r
+        /**\r
+         * Creates an empty XMLObject with a particular element name.\r
+         * \r
+         * @param q     QName of element for object\r
+         * @return the empty XMLObject\r
+         */\r
+        XMLObject* buildFromQName(const QName& q) const {\r
+            return buildObject(q.getNamespaceURI(),q.getLocalPart(),q.getPrefix());\r
+        }\r
+\r
+        /**\r
+         * Creates an unmarshalled XMLObject from a DOM Element.\r
+         * \r
+         * @param element       the unmarshalling source\r
+         * @param bindDocument  true iff the XMLObject should take ownership of the DOM Document\r
+         * @return the unmarshalled XMLObject\r
+         */\r
+        XMLObject* buildFromElement(xercesc::DOMElement* element, bool bindDocument=false) const {\r
+            std::auto_ptr<XMLObject> ret(\r
+                buildObject(element->getNamespaceURI(),element->getLocalName(),element->getPrefix(),XMLHelper::getXSIType(element))\r
+                );\r
+            ret->unmarshall(element,bindDocument);\r
+            return ret.release();\r
+        }\r
+\r
+        /**\r
+         * Creates an unmarshalled XMLObject from the root of a DOM Document.\r
+         * \r
+         * @param doc           the unmarshalling source\r
+         * @param bindDocument  true iff the XMLObject should take ownership of the DOM Document\r
+         * @return the unmarshalled XMLObject\r
+         */\r
+        XMLObject* buildFromDocument(xercesc::DOMDocument* doc, bool bindDocument=true) const {\r
+            return buildFromElement(doc->getDocumentElement(),bindDocument);\r
+        }\r
 \r
         /**\r
-         * Creates an empty XMLObject using the default build method, if a builder can be found.\r
+         * Creates an unmarshalled XMLObject using the default build method, if a builder can be found.\r
          * \r
-         * @param key   the key used to locate a builder\r
-         * @return  the empty object or NULL if no builder is available \r
+         * @param element       the unmarshalling source\r
+         * @param bindDocument  true iff the new XMLObject should take ownership of the DOM Document\r
+         * @return  the unmarshalled object or NULL if no builder is available \r
          */\r
-        static XMLObject* buildObject(const QName& key) {\r
-            const XMLObjectBuilder* b=getBuilder(key);\r
-            return b ? b->buildObject() : NULL;\r
+        static XMLObject* buildOneFromElement(xercesc::DOMElement* element, bool bindDocument=false) {\r
+            const XMLObjectBuilder* b=getBuilder(element);\r
+            return b ? b->buildFromElement(element,bindDocument) : NULL;\r
         }\r
 \r
         /**\r
@@ -83,14 +126,14 @@ namespace xmltooling {
          * @param element the element for which to locate a builder\r
          * @return the builder or NULL\r
          */\r
-        static const XMLObjectBuilder* getBuilder(const DOMElement* element);\r
+        static const XMLObjectBuilder* getBuilder(const xercesc::DOMElement* element);\r
 \r
         /**\r
          * Retrieves the default XMLObjectBuilder for DOM elements\r
          * \r
          * @return the default builder or NULL\r
          */\r
-        static const XMLObjectBuilder* getDefaultBuilder(const DOMElement* element) {\r
+        static const XMLObjectBuilder* getDefaultBuilder() {\r
             return m_default;\r
         }\r
 \r