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 ParserPool;
45 class XMLTOOL_API PathResolver;
46 class XMLTOOL_API TemplateEngine;
47 class XMLTOOL_API URLEncoder;
48 #ifndef XMLTOOLING_LITE
49 class XMLTOOL_API ReplayCache;
50 class XMLTOOL_API StorageService;
52 #ifndef XMLTOOLING_NO_XMLSEC
53 class XMLTOOL_API CredentialResolver;
54 class XMLTOOL_API KeyInfoResolver;
55 class XMLTOOL_API TrustEngine;
56 class XMLTOOL_API XSECCryptoX509CRL;
60 * Singleton object that manages library startup/shutdown.configuration.
62 * <p>A locking interface is supplied as a convenience for code that wants to
63 * obtain a global system lock, but the actual configuration itself is not
66 class XMLTOOL_API XMLToolingConfig : public virtual Lockable
68 MAKE_NONCOPYABLE(XMLToolingConfig);
72 #ifndef XMLTOOLING_NO_XMLSEC
73 /** Global KeyInfoResolver instance. */
74 KeyInfoResolver* m_keyInfoResolver;
76 /** Global ReplayCache instance. */
77 ReplayCache* m_replayCache;
80 /** Global PathResolver instance. */
81 PathResolver* m_pathResolver;
83 /** Global TemplateEngine instance. */
84 TemplateEngine* m_templateEngine;
86 /** Global URLEncoder instance for use by URL-related functions. */
87 URLEncoder* m_urlEncoder;
90 virtual ~XMLToolingConfig();
93 * Returns the global configuration object for the library.
95 * @return reference to the global library configuration object
97 static XMLToolingConfig& getConfig();
100 * Initializes library
102 * Each process using the library MUST call this function exactly once
103 * before using any library classes except for the LogConfig method.
105 * @return true iff initialization was successful
107 virtual bool init()=0;
111 * <p>Each process using the library SHOULD call this function exactly once
112 * before terminating itself
114 virtual void term()=0;
117 * Loads a shared/dynamic library extension.
119 * <p>Extension libraries are managed using a pair of "C" linkage functions:<br>
120 * extern "C" int xmltooling_extension_init(void* context);<br>
121 * extern "C" void xmltooling_extension_term();
123 * <p>This method is internally synchronized.
125 * @param path pathname of shared library to load into process
126 * @param context arbitrary data to pass to library initialization hook
127 * @return true iff library was loaded successfully
129 virtual bool load_library(const char* path, void* context=nullptr)=0;
132 * Configure logging system.
133 * <p>May be called first, before initializing the library. Other calls to it
134 * must be externally synchronized.
136 * @param config either a logging configuration file, or a level from the set
137 * (DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, ALERT, FATAL, EMERG)
138 * @return true iff configuration was successful
140 virtual bool log_config(const char* config=nullptr)=0;
143 * Obtains a non-validating parser pool.
144 * <p>Library must be initialized first.
146 * @return reference to a non-validating parser pool.
148 virtual ParserPool& getParser() const=0;
151 * Obtains a validating parser pool.
152 * <p>Library must be initialized first. Schema/catalog registration must be
153 * externally synchronized.
155 * @return reference to a validating parser pool.
157 virtual ParserPool& getValidatingParser() const=0;
159 #ifndef XMLTOOLING_NO_XMLSEC
161 * Returns the global KeyInfoResolver instance.
163 * @return global KeyInfoResolver or nullptr
165 const KeyInfoResolver* getKeyInfoResolver() const;
168 * Returns the global ReplayCache instance.
170 * @return global ReplayCache or nullptr
172 ReplayCache* getReplayCache() const;
175 * Sets the global KeyInfoResolver instance.
176 * <p>This method must be externally synchronized with any code that uses the object.
177 * Any previously set object is destroyed.
179 * @param keyInfoResolver new KeyInfoResolver instance to store
181 void setKeyInfoResolver(KeyInfoResolver* keyInfoResolver);
184 * Sets the global ReplayCache instance.
185 * <p>This method must be externally synchronized with any code that uses the object.
186 * Any previously set object is destroyed.
188 * @param replayCache new ReplayCache instance to store
190 void setReplayCache(ReplayCache* replayCache);
194 * Returns the global PathResolver instance.
196 * @return global PathResolver or nullptr
198 PathResolver* getPathResolver() const;
201 * Returns the global TemplateEngine instance.
203 * @return global TemplateEngine or nullptr
205 TemplateEngine* getTemplateEngine() const;
208 * Returns the global URLEncoder instance.
210 * @return global URLEncoder or nullptr
212 const URLEncoder* getURLEncoder() const;
215 * Sets the global PathResolver instance.
216 * <p>This method must be externally synchronized with any code that uses the object.
217 * Any previously set object is destroyed.
219 * @param pathResolver new PathResolver instance to store
221 void setPathResolver(PathResolver* pathResolver);
224 * Sets the global TemplateEngine instance.
225 * <p>This method must be externally synchronized with any code that uses the object.
226 * Any previously set object is destroyed.
228 * @param templateEngine new TemplateEngine instance to store
230 void setTemplateEngine(TemplateEngine* templateEngine);
233 * Sets the global URLEncoder instance.
234 * <p>This method must be externally synchronized with any code that uses the object.
235 * Any previously set object is destroyed.
237 * @param urlEncoder new URLEncoder instance to store
239 void setURLEncoder(URLEncoder* urlEncoder);
242 * List of catalog files to load into validating parser pool at initialization time.
243 * <p>Like other path settings, the separator depends on the platform
244 * (semicolon on Windows, colon otherwise).
246 std::string catalog_path;
248 /** A User-Agent header to include in HTTP client requests. */
249 std::string user_agent;
252 * Adjusts any clock comparisons to be more liberal/permissive by the
253 * indicated number of seconds.
255 unsigned int clock_skew_secs;
257 #ifndef XMLTOOLING_NO_XMLSEC
259 * Returns an X.509 CRL implementation object.
261 virtual XSECCryptoX509CRL* X509CRL() const=0;
264 * Manages factories for KeyInfoResolver plugins.
266 PluginManager<KeyInfoResolver,std::string,const xercesc::DOMElement*> KeyInfoResolverManager;
269 * Manages factories for CredentialResolver plugins.
271 PluginManager<CredentialResolver,std::string,const xercesc::DOMElement*> CredentialResolverManager;
274 * Manages factories for TrustEngine plugins.
276 PluginManager<TrustEngine,std::string,const xercesc::DOMElement*> TrustEngineManager;
279 * Manages factories for StorageService plugins.
281 PluginManager<StorageService,std::string,const xercesc::DOMElement*> StorageServiceManager;
284 * Maps an XML Signature/Encryption algorithm identifier to a library-specific
285 * key algorithm and size for use in resolving credentials.
287 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
288 * @return a general key algorithm and key size (or 0 if the size is irrelevant)
290 virtual std::pair<const char*,unsigned int> mapXMLAlgorithmToKeyAlgorithm(const XMLCh* xmlAlgorithm) const=0;
293 * Types of XML Security algorithms.
295 enum XMLSecurityAlgorithmType {
305 * Registers an XML Signature/Encryption algorithm identifier against a library-specific
306 * key algorithm and size for use in resolving credentials.
308 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
309 * @param keyAlgorithm a key algorithm
310 * @param size a key size (or 0 if the size is irrelevant)
311 * @param type type of algorithm, if known
313 virtual void registerXMLAlgorithm(
314 const XMLCh* xmlAlgorithm, const char* keyAlgorithm, unsigned int size=0, XMLSecurityAlgorithmType type=ALGTYPE_UNK
318 * Checks for implementation support of a particular XML Security algorithm.
320 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
321 * @param type type of algorithm, or ALGTYPE_UNK to ignore
322 * @return true iff the algorithm is supported by the underlying libraries
324 virtual bool isXMLAlgorithmSupported(const XMLCh* xmlAlgorithm, XMLSecurityAlgorithmType type=ALGTYPE_UNK)=0;
328 * Manages factories for SOAPTransport plugins.
330 * <p>The factory interface takes a peer name/endpoint pair.
332 PluginManager<SOAPTransport,std::string,SOAPTransport::Address> SOAPTransportManager;
337 #if defined (_MSC_VER)
338 #pragma warning( pop )
341 #endif /* __xmltooling_config_h__ */