2 * Copyright 2001-2010 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * @file xmltooling/XMLObjectBuilder.h
20 * Factory interface for XMLObjects.
23 #ifndef __xmltooling_xmlobjbuilder_h__
24 #define __xmltooling_xmlobjbuilder_h__
26 #include <xmltooling/QName.h>
27 #include <xmltooling/XMLObject.h>
28 #include <xmltooling/util/XMLHelper.h>
33 #if defined (_MSC_VER)
34 #pragma warning( push )
35 #pragma warning( disable : 4250 4251 )
38 namespace xmltooling {
41 * A factory interface for obtaining an XMLObject.
43 class XMLTOOL_API XMLObjectBuilder
45 MAKE_NONCOPYABLE(XMLObjectBuilder);
47 virtual ~XMLObjectBuilder();
50 * Creates an empty XMLObject with a particular element name.
51 * <p>The results are undefined if localName is nullptr or empty.
52 * <p>The caller is responsible for freeing the resulting object.
54 * @param nsURI namespace URI for element
55 * @param localName local name of element
56 * @param prefix prefix of element name
57 * @param schemaType xsi:type of the object
58 * @return the empty XMLObject
60 virtual XMLObject* buildObject(
61 const XMLCh* nsURI, const XMLCh* localName, const XMLCh* prefix=nullptr, const QName* schemaType=nullptr
65 * Creates an empty XMLObject with a particular element name.
66 * <p>The caller is responsible for freeing the resulting object.
68 * @param q QName of element for object
69 * @return the empty XMLObject
71 XMLObject* buildFromQName(const QName& q) const;
74 * Creates an unmarshalled XMLObject from a DOM Element.
75 * <p>The caller is responsible for freeing the resulting object.
77 * @param element the unmarshalling source
78 * @param bindDocument true iff the XMLObject should take ownership of the DOM Document
79 * @return the unmarshalled XMLObject
81 XMLObject* buildFromElement(xercesc::DOMElement* element, bool bindDocument=false) const;
84 * Creates an unmarshalled XMLObject from the root of a DOM Document.
85 * <p>The caller is responsible for freeing the resulting object.
87 * @param doc the unmarshalling source
88 * @param bindDocument true iff the XMLObject should take ownership of the DOM Document
89 * @return the unmarshalled XMLObject
91 XMLObject* buildFromDocument(xercesc::DOMDocument* doc, bool bindDocument=true) const;
94 * Creates an unmarshalled XMLObject using the default build method, if a builder can be found.
95 * <p>The caller is responsible for freeing the resulting object.
97 * @param element the unmarshalling source
98 * @param bindDocument true iff the new XMLObject should take ownership of the DOM Document
99 * @return the unmarshalled object or nullptr if no builder is available
101 static XMLObject* buildOneFromElement(xercesc::DOMElement* element, bool bindDocument=false);
104 * Retrieves an XMLObjectBuilder using the key it was registered with.
106 * @param key the key used to register the builder
107 * @return the builder or nullptr
109 static const XMLObjectBuilder* getBuilder(const QName& key);
112 * Retrieves an XMLObjectBuilder for a given DOM element.
113 * If no match is found, the default builder is returned, if any.
115 * @param element the element for which to locate a builder
116 * @return the builder or nullptr
118 static const XMLObjectBuilder* getBuilder(const xercesc::DOMElement* element);
121 * Retrieves the default XMLObjectBuilder for DOM elements
123 * @return the default builder or nullptr
125 static const XMLObjectBuilder* getDefaultBuilder();
128 * Gets an immutable list of all the builders currently registered.
130 * @return list of all the builders currently registered
132 static const std::map<QName,XMLObjectBuilder*>& getBuilders();
135 * Registers a new builder for the given key.
137 * @param builderKey the key used to retrieve this builder later
138 * @param builder the builder
140 static void registerBuilder(const QName& builderKey, XMLObjectBuilder* builder);
143 * Registers a default builder
145 * @param builder the default builder
147 static void registerDefaultBuilder(XMLObjectBuilder* builder);
150 * Deregisters a builder.
152 * @param builderKey the key for the builder to be deregistered
154 static void deregisterBuilder(const QName& builderKey);
157 * Deregisters default builder.
159 static void deregisterDefaultBuilder();
162 * Unregisters and destroys all registered builders.
164 static void destroyBuilders();
170 static std::map<QName,XMLObjectBuilder*> m_map;
171 static XMLObjectBuilder* m_default;
176 #if defined (_MSC_VER)
177 #pragma warning( pop )
180 #endif /* __xmltooling_xmlobjbuilder_h__ */