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/XMLToolingConfig.h
24 * Library configuration.
27 #ifndef __xmltooling_config_h__
28 #define __xmltooling_config_h__
30 #include <xmltooling/Lockable.h>
31 #include <xmltooling/PluginManager.h>
32 #include <xmltooling/soap/SOAPTransport.h>
35 #include <xercesc/dom/DOM.hpp>
37 #if defined (_MSC_VER)
38 #pragma warning( push )
39 #pragma warning( disable : 4251 )
42 namespace xmltooling {
44 class XMLTOOL_API Mutex;
45 class XMLTOOL_API ParserPool;
46 class XMLTOOL_API PathResolver;
47 class XMLTOOL_API TemplateEngine;
48 class XMLTOOL_API URLEncoder;
49 #ifndef XMLTOOLING_LITE
50 class XMLTOOL_API ReplayCache;
51 class XMLTOOL_API StorageService;
53 #ifndef XMLTOOLING_NO_XMLSEC
54 class XMLTOOL_API CredentialResolver;
55 class XMLTOOL_API KeyInfoResolver;
56 class XMLTOOL_API PathValidator;
57 class XMLTOOL_API TrustEngine;
58 class XMLTOOL_API XSECCryptoX509CRL;
62 * Singleton object that manages library startup/shutdown.configuration.
64 * <p>A locking interface is supplied as a convenience for code that wants to
65 * obtain a global system lock, but the actual configuration itself is not
68 class XMLTOOL_API XMLToolingConfig : public virtual Lockable
70 MAKE_NONCOPYABLE(XMLToolingConfig);
74 #ifndef XMLTOOLING_NO_XMLSEC
75 /** Global KeyInfoResolver instance. */
76 KeyInfoResolver* m_keyInfoResolver;
78 /** Global ReplayCache instance. */
79 ReplayCache* m_replayCache;
82 /** Global PathResolver instance. */
83 PathResolver* m_pathResolver;
85 /** Global TemplateEngine instance. */
86 TemplateEngine* m_templateEngine;
88 /** Global URLEncoder instance for use by URL-related functions. */
89 URLEncoder* m_urlEncoder;
92 virtual ~XMLToolingConfig();
95 * Returns the global configuration object for the library.
97 * @return reference to the global library configuration object
99 static XMLToolingConfig& getConfig();
102 * Initializes library
104 * Each process using the library MUST call this function exactly once
105 * before using any library classes except for the LogConfig method.
107 * @return true iff initialization was successful
109 virtual bool init()=0;
113 * <p>Each process using the library SHOULD call this function exactly once
114 * before terminating itself
116 virtual void term()=0;
119 * Loads a shared/dynamic library extension.
121 * <p>Extension libraries are managed using a pair of "C" linkage functions:<br>
122 * extern "C" int xmltooling_extension_init(void* context);<br>
123 * extern "C" void xmltooling_extension_term();
125 * <p>This method is internally synchronized.
127 * @param path pathname of shared library to load into process
128 * @param context arbitrary data to pass to library initialization hook
129 * @return true iff library was loaded successfully
131 virtual bool load_library(const char* path, void* context=nullptr)=0;
134 * Configure logging system.
135 * <p>May be called first, before initializing the library. Other calls to it
136 * must be externally synchronized.
138 * @param config either a logging configuration file, or a level from the set
139 * (DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, ALERT, FATAL, EMERG)
140 * @return true iff configuration was successful
142 virtual bool log_config(const char* config=nullptr)=0;
145 * Obtains a non-validating parser pool.
146 * <p>Library must be initialized first.
148 * @return reference to a non-validating parser pool.
150 virtual ParserPool& getParser() const=0;
153 * Obtains a validating parser pool.
154 * <p>Library must be initialized first. Schema/catalog registration must be
155 * externally synchronized.
157 * @return reference to a validating parser pool.
159 virtual ParserPool& getValidatingParser() const=0;
162 * Returns a reference to a named mutex.
163 * <p>The first access to a given name will create the object.
165 * @param name name of mutex to access
166 * @return reference to a mutex object
168 virtual Mutex& getNamedMutex(const char* name)=0;
170 #ifndef XMLTOOLING_NO_XMLSEC
172 * Returns the global KeyInfoResolver instance.
174 * @return global KeyInfoResolver or nullptr
176 const KeyInfoResolver* getKeyInfoResolver() const;
179 * Returns the global ReplayCache instance.
181 * @return global ReplayCache or nullptr
183 ReplayCache* getReplayCache() const;
186 * Sets the global KeyInfoResolver instance.
187 * <p>This method must be externally synchronized with any code that uses the object.
188 * Any previously set object is destroyed.
190 * @param keyInfoResolver new KeyInfoResolver instance to store
192 void setKeyInfoResolver(KeyInfoResolver* keyInfoResolver);
195 * Sets the global ReplayCache instance.
196 * <p>This method must be externally synchronized with any code that uses the object.
197 * Any previously set object is destroyed.
199 * @param replayCache new ReplayCache instance to store
201 void setReplayCache(ReplayCache* replayCache);
205 * Returns the global PathResolver instance.
207 * @return global PathResolver or nullptr
209 PathResolver* getPathResolver() const;
212 * Returns the global TemplateEngine instance.
214 * @return global TemplateEngine or nullptr
216 TemplateEngine* getTemplateEngine() const;
219 * Returns the global URLEncoder instance.
221 * @return global URLEncoder or nullptr
223 const URLEncoder* getURLEncoder() const;
226 * Sets the global PathResolver instance.
227 * <p>This method must be externally synchronized with any code that uses the object.
228 * Any previously set object is destroyed.
230 * @param pathResolver new PathResolver instance to store
232 void setPathResolver(PathResolver* pathResolver);
235 * Sets the global TemplateEngine instance.
236 * <p>This method must be externally synchronized with any code that uses the object.
237 * Any previously set object is destroyed.
239 * @param templateEngine new TemplateEngine instance to store
241 void setTemplateEngine(TemplateEngine* templateEngine);
244 * Sets the global URLEncoder instance.
245 * <p>This method must be externally synchronized with any code that uses the object.
246 * Any previously set object is destroyed.
248 * @param urlEncoder new URLEncoder instance to store
250 void setURLEncoder(URLEncoder* urlEncoder);
254 * List of catalog files to load into validating parser pool at initialization time.
255 * <p>Like other path settings, the separator depends on the platform
256 * (semicolon on Windows, colon otherwise).
258 std::string catalog_path;
260 /** A User-Agent header to include in HTTP client requests. */
261 std::string user_agent;
264 * Adjusts any clock comparisons to be more liberal/permissive by the
265 * indicated number of seconds.
267 unsigned int clock_skew_secs;
269 #ifndef XMLTOOLING_LITE
271 * Manages factories for StorageService plugins.
273 PluginManager<StorageService,std::string,const xercesc::DOMElement*> StorageServiceManager;
276 #ifndef XMLTOOLING_NO_XMLSEC
278 * Returns an X.509 CRL implementation object.
280 virtual XSECCryptoX509CRL* X509CRL() const=0;
283 * Manages factories for CredentialResolver plugins.
285 PluginManager<CredentialResolver,std::string,const xercesc::DOMElement*> CredentialResolverManager;
288 * Manages factories for KeyInfoResolver plugins.
290 PluginManager<KeyInfoResolver,std::string,const xercesc::DOMElement*> KeyInfoResolverManager;
293 * Manages factories for PathValidator plugins.
295 PluginManager<PathValidator,std::string,const xercesc::DOMElement*> PathValidatorManager;
298 * Manages factories for TrustEngine plugins.
300 PluginManager<TrustEngine,std::string,const xercesc::DOMElement*> TrustEngineManager;
303 * Maps an XML Signature/Encryption algorithm identifier to a library-specific
304 * key algorithm and size for use in resolving credentials.
306 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
307 * @return a general key algorithm and key size (or 0 if the size is irrelevant)
309 virtual std::pair<const char*,unsigned int> mapXMLAlgorithmToKeyAlgorithm(const XMLCh* xmlAlgorithm) const=0;
312 * Types of XML Security algorithms.
314 enum XMLSecurityAlgorithmType {
325 * Registers an XML Signature/Encryption algorithm identifier against a library-specific
326 * key algorithm and size for use in resolving credentials.
328 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
329 * @param keyAlgorithm a key algorithm
330 * @param size a key size (or 0 if the size is irrelevant)
331 * @param type type of algorithm, if known
333 virtual void registerXMLAlgorithm(
334 const XMLCh* xmlAlgorithm, const char* keyAlgorithm, unsigned int size=0, XMLSecurityAlgorithmType type=ALGTYPE_UNK
338 * Checks for implementation support of a particular XML Security algorithm.
340 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
341 * @param type type of algorithm, or ALGTYPE_UNK to ignore
342 * @return true iff the algorithm is supported by the underlying libraries
344 virtual bool isXMLAlgorithmSupported(const XMLCh* xmlAlgorithm, XMLSecurityAlgorithmType type=ALGTYPE_UNK)=0;
348 * Manages factories for SOAPTransport plugins.
350 * <p>The factory interface takes a peer name/endpoint pair.
352 PluginManager<SOAPTransport,std::string,SOAPTransport::Address> SOAPTransportManager;
357 #if defined (_MSC_VER)
358 #pragma warning( pop )
361 #endif /* __xmltooling_config_h__ */