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/XMLToolingConfig.h
20 * Library configuration.
23 #ifndef __xmltooling_config_h__
24 #define __xmltooling_config_h__
26 #include <xmltooling/Lockable.h>
27 #include <xmltooling/PluginManager.h>
28 #include <xmltooling/soap/SOAPTransport.h>
31 #include <xercesc/dom/DOM.hpp>
33 #if defined (_MSC_VER)
34 #pragma warning( push )
35 #pragma warning( disable : 4251 )
38 namespace xmltooling {
40 class XMLTOOL_API ParserPool;
41 class XMLTOOL_API PathResolver;
42 class XMLTOOL_API TemplateEngine;
43 class XMLTOOL_API URLEncoder;
44 #ifndef XMLTOOLING_LITE
45 class XMLTOOL_API ReplayCache;
46 class XMLTOOL_API StorageService;
48 #ifndef XMLTOOLING_NO_XMLSEC
49 class XMLTOOL_API CredentialResolver;
50 class XMLTOOL_API KeyInfoResolver;
51 class XMLTOOL_API TrustEngine;
52 class XMLTOOL_API XSECCryptoX509CRL;
56 * Singleton object that manages library startup/shutdown.configuration.
58 * <p>A locking interface is supplied as a convenience for code that wants to
59 * obtain a global system lock, but the actual configuration itself is not
62 class XMLTOOL_API XMLToolingConfig : public virtual Lockable
64 MAKE_NONCOPYABLE(XMLToolingConfig);
68 #ifndef XMLTOOLING_NO_XMLSEC
69 /** Global KeyInfoResolver instance. */
70 KeyInfoResolver* m_keyInfoResolver;
72 /** Global ReplayCache instance. */
73 ReplayCache* m_replayCache;
76 /** Global PathResolver instance. */
77 PathResolver* m_pathResolver;
79 /** Global TemplateEngine instance. */
80 TemplateEngine* m_templateEngine;
82 /** Global URLEncoder instance for use by URL-related functions. */
83 URLEncoder* m_urlEncoder;
86 virtual ~XMLToolingConfig();
89 * Returns the global configuration object for the library.
91 * @return reference to the global library configuration object
93 static XMLToolingConfig& getConfig();
98 * Each process using the library MUST call this function exactly once
99 * before using any library classes except for the LogConfig method.
101 * @return true iff initialization was successful
103 virtual bool init()=0;
107 * <p>Each process using the library SHOULD call this function exactly once
108 * before terminating itself
110 virtual void term()=0;
113 * Loads a shared/dynamic library extension.
115 * <p>Extension libraries are managed using a pair of "C" linkage functions:<br>
116 * extern "C" int xmltooling_extension_init(void* context);<br>
117 * extern "C" void xmltooling_extension_term();
119 * <p>This method is internally synchronized.
121 * @param path pathname of shared library to load into process
122 * @param context arbitrary data to pass to library initialization hook
123 * @return true iff library was loaded successfully
125 virtual bool load_library(const char* path, void* context=nullptr)=0;
128 * Configure logging system.
129 * <p>May be called first, before initializing the library. Other calls to it
130 * must be externally synchronized.
132 * @param config either a logging configuration file, or a level from the set
133 * (DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, ALERT, FATAL, EMERG)
134 * @return true iff configuration was successful
136 virtual bool log_config(const char* config=nullptr)=0;
139 * Obtains a non-validating parser pool.
140 * <p>Library must be initialized first.
142 * @return reference to a non-validating parser pool.
144 virtual ParserPool& getParser() const=0;
147 * Obtains a validating parser pool.
148 * <p>Library must be initialized first. Schema/catalog registration must be
149 * externally synchronized.
151 * @return reference to a validating parser pool.
153 virtual ParserPool& getValidatingParser() const=0;
155 #ifndef XMLTOOLING_NO_XMLSEC
157 * Returns the global KeyInfoResolver instance.
159 * @return global KeyInfoResolver or nullptr
161 const KeyInfoResolver* getKeyInfoResolver() const;
164 * Returns the global ReplayCache instance.
166 * @return global ReplayCache or nullptr
168 ReplayCache* getReplayCache() const;
171 * Sets the global KeyInfoResolver instance.
172 * <p>This method must be externally synchronized with any code that uses the object.
173 * Any previously set object is destroyed.
175 * @param keyInfoResolver new KeyInfoResolver instance to store
177 void setKeyInfoResolver(KeyInfoResolver* keyInfoResolver);
180 * Sets the global ReplayCache instance.
181 * <p>This method must be externally synchronized with any code that uses the object.
182 * Any previously set object is destroyed.
184 * @param replayCache new ReplayCache instance to store
186 void setReplayCache(ReplayCache* replayCache);
190 * Returns the global PathResolver instance.
192 * @return global PathResolver or nullptr
194 PathResolver* getPathResolver() const;
197 * Returns the global TemplateEngine instance.
199 * @return global TemplateEngine or nullptr
201 TemplateEngine* getTemplateEngine() const;
204 * Returns the global URLEncoder instance.
206 * @return global URLEncoder or nullptr
208 const URLEncoder* getURLEncoder() const;
211 * Sets the global PathResolver instance.
212 * <p>This method must be externally synchronized with any code that uses the object.
213 * Any previously set object is destroyed.
215 * @param pathResolver new PathResolver instance to store
217 void setPathResolver(PathResolver* pathResolver);
220 * Sets the global TemplateEngine instance.
221 * <p>This method must be externally synchronized with any code that uses the object.
222 * Any previously set object is destroyed.
224 * @param templateEngine new TemplateEngine instance to store
226 void setTemplateEngine(TemplateEngine* templateEngine);
229 * Sets the global URLEncoder instance.
230 * <p>This method must be externally synchronized with any code that uses the object.
231 * Any previously set object is destroyed.
233 * @param urlEncoder new URLEncoder instance to store
235 void setURLEncoder(URLEncoder* urlEncoder);
238 * List of catalog files to load into validating parser pool at initialization time.
239 * <p>Like other path settings, the separator depends on the platform
240 * (semicolon on Windows, colon otherwise).
242 std::string catalog_path;
244 /** A User-Agent header to include in HTTP client requests. */
245 std::string user_agent;
248 * Adjusts any clock comparisons to be more liberal/permissive by the
249 * indicated number of seconds.
251 unsigned int clock_skew_secs;
253 #ifndef XMLTOOLING_NO_XMLSEC
255 * Returns an X.509 CRL implementation object.
257 virtual XSECCryptoX509CRL* X509CRL() const=0;
260 * Manages factories for KeyInfoResolver plugins.
262 PluginManager<KeyInfoResolver,std::string,const xercesc::DOMElement*> KeyInfoResolverManager;
265 * Manages factories for CredentialResolver plugins.
267 PluginManager<CredentialResolver,std::string,const xercesc::DOMElement*> CredentialResolverManager;
270 * Manages factories for TrustEngine plugins.
272 PluginManager<TrustEngine,std::string,const xercesc::DOMElement*> TrustEngineManager;
275 * Manages factories for StorageService plugins.
277 PluginManager<StorageService,std::string,const xercesc::DOMElement*> StorageServiceManager;
280 * Maps an XML Signature/Encryption algorithm identifier to a library-specific
281 * key algorithm and size for use in resolving credentials.
283 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
284 * @return a general key algorithm and key size (or 0 if the size is irrelevant)
286 virtual std::pair<const char*,unsigned int> mapXMLAlgorithmToKeyAlgorithm(const XMLCh* xmlAlgorithm) const=0;
289 * Types of XML Security algorithms.
291 enum XMLSecurityAlgorithmType {
301 * Registers an XML Signature/Encryption algorithm identifier against a library-specific
302 * key algorithm and size for use in resolving credentials.
304 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
305 * @param keyAlgorithm a key algorithm
306 * @param size a key size (or 0 if the size is irrelevant)
307 * @param type type of algorithm, if known
309 virtual void registerXMLAlgorithm(
310 const XMLCh* xmlAlgorithm, const char* keyAlgorithm, unsigned int size=0, XMLSecurityAlgorithmType type=ALGTYPE_UNK
314 * Checks for implementation support of a particular XML Security algorithm.
316 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier
317 * @param type type of algorithm, or ALGTYPE_UNK to ignore
318 * @return true iff the algorithm is supported by the underlying libraries
320 virtual bool isXMLAlgorithmSupported(const XMLCh* xmlAlgorithm, XMLSecurityAlgorithmType type=ALGTYPE_UNK)=0;
324 * Manages factories for SOAPTransport plugins.
326 * <p>The factory interface takes a peer name/endpoint pair.
328 PluginManager<SOAPTransport,std::string,SOAPTransport::Address> SOAPTransportManager;
333 #if defined (_MSC_VER)
334 #pragma warning( pop )
337 #endif /* __xmltooling_config_h__ */