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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file xmltooling/XMLObjectBuilder.h
24 * Factory interface for XMLObjects.
27 #ifndef __xmltooling_xmlobjbuilder_h__
28 #define __xmltooling_xmlobjbuilder_h__
30 #include <xmltooling/QName.h>
31 #include <xmltooling/XMLObject.h>
32 #include <xmltooling/util/XMLHelper.h>
37 #if defined (_MSC_VER)
38 #pragma warning( push )
39 #pragma warning( disable : 4250 4251 )
42 namespace xmltooling {
45 * A factory interface for obtaining an XMLObject.
47 class XMLTOOL_API XMLObjectBuilder
49 MAKE_NONCOPYABLE(XMLObjectBuilder);
51 virtual ~XMLObjectBuilder();
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.
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
64 virtual XMLObject* buildObject(
65 const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=nullptr, const QName* schemaType=nullptr
69 * Creates an empty XMLObject with a particular element name.
70 * <p>The caller is responsible for freeing the resulting object.
72 * @param q QName of element for object
73 * @return the empty XMLObject
75 XMLObject* buildFromQName(const QName& q) const;
78 * Creates an unmarshalled XMLObject from a DOM Element.
79 * <p>The caller is responsible for freeing the resulting object.
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
85 XMLObject* buildFromElement(xercesc::DOMElement* element, bool bindDocument=false) const;
88 * Creates an unmarshalled XMLObject from the root of a DOM Document.
89 * <p>The caller is responsible for freeing the resulting object.
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
95 XMLObject* buildFromDocument(xercesc::DOMDocument* doc, bool bindDocument=true) const;
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.
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
105 static XMLObject* buildOneFromElement(xercesc::DOMElement* element, bool bindDocument=false);
108 * Retrieves an XMLObjectBuilder using the key it was registered with.
110 * @param key the key used to register the builder
111 * @return the builder or nullptr
113 static const XMLObjectBuilder* getBuilder(const QName& key);
116 * Retrieves an XMLObjectBuilder for a given DOM element.
117 * If no match is found, the default builder is returned, if any.
119 * @param element the element for which to locate a builder
120 * @return the builder or nullptr
122 static const XMLObjectBuilder* getBuilder(const xercesc::DOMElement* element);
125 * Retrieves the default XMLObjectBuilder for DOM elements
127 * @return the default builder or nullptr
129 static const XMLObjectBuilder* getDefaultBuilder();
132 * Gets an immutable list of all the builders currently registered.
134 * @return list of all the builders currently registered
136 static const std::map<QName,XMLObjectBuilder*>& getBuilders();
139 * Registers a new builder for the given key.
141 * @param builderKey the key used to retrieve this builder later
142 * @param builder the builder
144 static void registerBuilder(const QName& builderKey, XMLObjectBuilder* builder);
147 * Registers a default builder
149 * @param builder the default builder
151 static void registerDefaultBuilder(XMLObjectBuilder* builder);
154 * Deregisters a builder.
156 * @param builderKey the key for the builder to be deregistered
158 static void deregisterBuilder(const QName& builderKey);
161 * Deregisters default builder.
163 static void deregisterDefaultBuilder();
166 * Unregisters and destroys all registered builders.
168 static void destroyBuilders();
174 static std::map<QName,XMLObjectBuilder*> m_map;
175 static XMLObjectBuilder* m_default;
180 #if defined (_MSC_VER)
181 #pragma warning( pop )
184 #endif /* __xmltooling_xmlobjbuilder_h__ */