xmltooling/XMLObjectBuilder.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file xmltooling/XMLObjectBuilder.h
  23  *
  24  * Factory interface for XMLObjects.
  25  */
  26
  27 #ifndef __xmltooling_xmlobjbuilder_h__
  28 #define __xmltooling_xmlobjbuilder_h__
  29
  30 #include <xmltooling/QName.h>
  31 #include <xmltooling/XMLObject.h>
  32 #include <xmltooling/util/XMLHelper.h>
  33
  34 #include <map>
  35 #include <memory>
  36
  37 #if defined (_MSC_VER)
  38     #pragma warning( push )
  39     #pragma warning( disable : 4250 4251 )
  40 #endif
  41
  42 namespace xmltooling {
  43
  44     /**
  45      * A factory interface for obtaining an XMLObject.
  46      */
  47     class XMLTOOL_API XMLObjectBuilder
  48     {
  49     MAKE_NONCOPYABLE(XMLObjectBuilder);
  50     public:
  51         virtual ~XMLObjectBuilder();
  52
  53         /**
  54          * Creates an empty XMLObject with a particular element name.
  55          * <p>The results are undefined if localName is nullptr or empty.
  56          * <p>The caller is responsible for freeing the resulting object.
  57          *
  58          * @param nsURI         namespace URI for element
  59          * @param localName     local name of element
  60          * @param prefix        prefix of element name
  61          * @param schemaType    xsi:type of the object
  62          * @return the empty XMLObject
  63          */
  64         virtual XMLObject* buildObject(
  65             const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=nullptr, const QName* schemaType=nullptr
  66             ) const=0;
  67
  68         /**
  69          * Creates an empty XMLObject with a particular element name.
  70          * <p>The caller is responsible for freeing the resulting object.
  71          *
  72          * @param q     QName of element for object
  73          * @return the empty XMLObject
  74          */
  75         XMLObject* buildFromQName(const QName& q) const;
  76
  77         /**
  78          * Creates an unmarshalled XMLObject from a DOM Element.
  79          * <p>The caller is responsible for freeing the resulting object.
  80          *
  81          * @param element       the unmarshalling source
  82          * @param bindDocument  true iff the XMLObject should take ownership of the DOM Document
  83          * @return the unmarshalled XMLObject
  84          */
  85         XMLObject* buildFromElement(xercesc::DOMElement* element, bool bindDocument=false) const;
  86
  87         /**
  88          * Creates an unmarshalled XMLObject from the root of a DOM Document.
  89          * <p>The caller is responsible for freeing the resulting object.
  90          *
  91          * @param doc           the unmarshalling source
  92          * @param bindDocument  true iff the XMLObject should take ownership of the DOM Document
  93          * @return the unmarshalled XMLObject
  94          */
  95         XMLObject* buildFromDocument(xercesc::DOMDocument* doc, bool bindDocument=true) const;
  96
  97         /**
  98          * Creates an unmarshalled XMLObject using the default build method, if a builder can be found.
  99          * <p>The caller is responsible for freeing the resulting object.
 100          *
 101          * @param element       the unmarshalling source
 102          * @param bindDocument  true iff the new XMLObject should take ownership of the DOM Document
 103          * @return  the unmarshalled object or nullptr if no builder is available
 104          */
 105         static XMLObject* buildOneFromElement(xercesc::DOMElement* element, bool bindDocument=false);
 106
 107         /**
 108          * Retrieves an XMLObjectBuilder using the key it was registered with.
 109          *
 110          * @param key the key used to register the builder
 111          * @return the builder or nullptr
 112          */
 113         static const XMLObjectBuilder* getBuilder(const QName& key);
 114
 115         /**
 116          * Retrieves an XMLObjectBuilder for a given DOM element.
 117          * If no match is found, the default builder is returned, if any.
 118          *
 119          * @param element the element for which to locate a builder
 120          * @return the builder or nullptr
 121          */
 122         static const XMLObjectBuilder* getBuilder(const xercesc::DOMElement* element);
 123
 124         /**
 125          * Retrieves the default XMLObjectBuilder for DOM elements
 126          *
 127          * @return the default builder or nullptr
 128          */
 129         static const XMLObjectBuilder* getDefaultBuilder();
 130
 131         /**
 132          * Gets an immutable list of all the builders currently registered.
 133          *
 134          * @return list of all the builders currently registered
 135          */
 136         static const std::map<QName,XMLObjectBuilder*>& getBuilders();
 137
 138         /**
 139          * Registers a new builder for the given key.
 140          *
 141          * @param builderKey the key used to retrieve this builder later
 142          * @param builder the builder
 143          */
 144         static void registerBuilder(const QName& builderKey, XMLObjectBuilder* builder);
 145
 146         /**
 147          * Registers a default builder
 148          *
 149          * @param builder the default builder
 150          */
 151         static void registerDefaultBuilder(XMLObjectBuilder* builder);
 152
 153         /**
 154          * Deregisters a builder.
 155          *
 156          * @param builderKey the key for the builder to be deregistered
 157          */
 158         static void deregisterBuilder(const QName& builderKey);
 159
 160         /**
 161          * Deregisters default builder.
 162          */
 163         static void deregisterDefaultBuilder();
 164
 165         /**
 166          * Unregisters and destroys all registered builders.
 167          */
 168         static void destroyBuilders();
 169
 170     protected:
 171         XMLObjectBuilder();
 172
 173     private:
 174         static std::map<QName,XMLObjectBuilder*> m_map;
 175         static XMLObjectBuilder* m_default;
 176     };
 177
 178 };
 179
 180 #if defined (_MSC_VER)
 181     #pragma warning( pop )
 182 #endif
 183
 184 #endif /* __xmltooling_xmlobjbuilder_h__ */