xmltooling/XMLToolingConfig.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file xmltooling/XMLToolingConfig.h
  19  *
  20  * Library configuration.
  21  */
  22
  23 #ifndef __xmltooling_config_h__
  24 #define __xmltooling_config_h__
  25
  26 #include <xmltooling/Lockable.h>
  27 #include <xmltooling/PluginManager.h>
  28 #include <xmltooling/soap/SOAPTransport.h>
  29
  30 #include <string>
  31 #include <xercesc/dom/DOM.hpp>
  32
  33 #if defined (_MSC_VER)
  34     #pragma warning( push )
  35     #pragma warning( disable : 4251 )
  36 #endif
  37
  38 namespace xmltooling {
  39
  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;
  47 #endif
  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;
  53 #endif
  54
  55     /**
  56      * Singleton object that manages library startup/shutdown.configuration.
  57      *
  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
  60      * synchronized.
  61      */
  62     class XMLTOOL_API XMLToolingConfig : public virtual Lockable
  63     {
  64         MAKE_NONCOPYABLE(XMLToolingConfig);
  65     protected:
  66         XMLToolingConfig();
  67
  68 #ifndef XMLTOOLING_NO_XMLSEC
  69         /** Global KeyInfoResolver instance. */
  70         KeyInfoResolver* m_keyInfoResolver;
  71
  72         /** Global ReplayCache instance. */
  73         ReplayCache* m_replayCache;
  74 #endif
  75
  76         /** Global PathResolver instance. */
  77         PathResolver* m_pathResolver;
  78
  79         /** Global TemplateEngine instance. */
  80         TemplateEngine* m_templateEngine;
  81
  82         /** Global URLEncoder instance for use by URL-related functions. */
  83         URLEncoder* m_urlEncoder;
  84
  85     public:
  86         virtual ~XMLToolingConfig();
  87
  88         /**
  89          * Returns the global configuration object for the library.
  90          *
  91          * @return reference to the global library configuration object
  92          */
  93         static XMLToolingConfig& getConfig();
  94
  95         /**
  96          * Initializes library
  97          *
  98          * Each process using the library MUST call this function exactly once
  99          * before using any library classes except for the LogConfig method.
 100          *
 101          * @return true iff initialization was successful
 102          */
 103         virtual bool init()=0;
 104
 105         /**
 106          * Shuts down library
 107          * <p>Each process using the library SHOULD call this function exactly once
 108          * before terminating itself
 109          */
 110         virtual void term()=0;
 111
 112         /**
 113          * Loads a shared/dynamic library extension.
 114          *
 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();
 118          *
 119          * <p>This method is internally synchronized.
 120          *
 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
 124          */
 125         virtual bool load_library(const char* path, void* context=nullptr)=0;
 126
 127         /**
 128          * Configure logging system.
 129          * <p>May be called first, before initializing the library. Other calls to it
 130          * must be externally synchronized.
 131          *
 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
 135          */
 136         virtual bool log_config(const char* config=nullptr)=0;
 137
 138         /**
 139          * Obtains a non-validating parser pool.
 140          * <p>Library must be initialized first.
 141          *
 142          * @return reference to a non-validating parser pool.
 143          */
 144         virtual ParserPool& getParser() const=0;
 145
 146         /**
 147          * Obtains a validating parser pool.
 148          * <p>Library must be initialized first. Schema/catalog registration must be
 149          * externally synchronized.
 150          *
 151          * @return reference to a validating parser pool.
 152          */
 153         virtual ParserPool& getValidatingParser() const=0;
 154
 155 #ifndef XMLTOOLING_NO_XMLSEC
 156         /**
 157          * Returns the global KeyInfoResolver instance.
 158          *
 159          * @return  global KeyInfoResolver or nullptr
 160          */
 161         const KeyInfoResolver* getKeyInfoResolver() const;
 162
 163         /**
 164          * Returns the global ReplayCache instance.
 165          *
 166          * @return  global ReplayCache or nullptr
 167          */
 168         ReplayCache* getReplayCache() const;
 169
 170         /**
 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.
 174          *
 175          * @param keyInfoResolver   new KeyInfoResolver instance to store
 176          */
 177         void setKeyInfoResolver(KeyInfoResolver* keyInfoResolver);
 178
 179         /**
 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.
 183          *
 184          * @param replayCache   new ReplayCache instance to store
 185          */
 186         void setReplayCache(ReplayCache* replayCache);
 187 #endif
 188
 189         /**
 190          * Returns the global PathResolver instance.
 191          *
 192          * @return  global PathResolver or nullptr
 193          */
 194         PathResolver* getPathResolver() const;
 195
 196         /**
 197          * Returns the global TemplateEngine instance.
 198          *
 199          * @return  global TemplateEngine or nullptr
 200          */
 201         TemplateEngine* getTemplateEngine() const;
 202
 203         /**
 204          * Returns the global URLEncoder instance.
 205          *
 206          * @return  global URLEncoder or nullptr
 207          */
 208         const URLEncoder* getURLEncoder() const;
 209
 210         /**
 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.
 214          *
 215          * @param pathResolver   new PathResolver instance to store
 216          */
 217         void setPathResolver(PathResolver* pathResolver);
 218
 219         /**
 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.
 223          *
 224          * @param templateEngine   new TemplateEngine instance to store
 225          */
 226         void setTemplateEngine(TemplateEngine* templateEngine);
 227
 228         /**
 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.
 232          *
 233          * @param urlEncoder   new URLEncoder instance to store
 234          */
 235         void setURLEncoder(URLEncoder* urlEncoder);
 236
 237         /**
 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).
 241          */
 242         std::string catalog_path;
 243
 244         /** A User-Agent header to include in HTTP client requests. */
 245         std::string user_agent;
 246
 247         /**
 248          * Adjusts any clock comparisons to be more liberal/permissive by the
 249          * indicated number of seconds.
 250          */
 251         unsigned int clock_skew_secs;
 252
 253 #ifndef XMLTOOLING_NO_XMLSEC
 254         /**
 255          * Returns an X.509 CRL implementation object.
 256          */
 257         virtual XSECCryptoX509CRL* X509CRL() const=0;
 258
 259         /**
 260          * Manages factories for KeyInfoResolver plugins.
 261          */
 262         PluginManager<KeyInfoResolver,std::string,const xercesc::DOMElement*> KeyInfoResolverManager;
 263
 264         /**
 265          * Manages factories for CredentialResolver plugins.
 266          */
 267         PluginManager<CredentialResolver,std::string,const xercesc::DOMElement*> CredentialResolverManager;
 268
 269         /**
 270          * Manages factories for TrustEngine plugins.
 271          */
 272         PluginManager<TrustEngine,std::string,const xercesc::DOMElement*> TrustEngineManager;
 273
 274         /**
 275          * Manages factories for StorageService plugins.
 276          */
 277         PluginManager<StorageService,std::string,const xercesc::DOMElement*> StorageServiceManager;
 278
 279         /**
 280          * Maps an XML Signature/Encryption algorithm identifier to a library-specific
 281          * key algorithm and size for use in resolving credentials.
 282          *
 283          * @param xmlAlgorithm  XML Signature/Encryption algorithm identifier
 284          * @return  a general key algorithm and key size (or 0 if the size is irrelevant)
 285          */
 286         virtual std::pair<const char*,unsigned int> mapXMLAlgorithmToKeyAlgorithm(const XMLCh* xmlAlgorithm) const=0;
 287
 288         /**
 289          * Registers an XML Signature/Encryption algorithm identifier against a library-specific
 290          * key algorithm and size for use in resolving credentials.
 291          *
 292          * @param xmlAlgorithm  XML Signature/Encryption algorithm identifier
 293          * @param keyAlgorithm  a key algorithm
 294          * @param size          a key size (or 0 if the size is irrelevant)
 295          */
 296         virtual void registerXMLAlgorithm(const XMLCh* xmlAlgorithm, const char* keyAlgorithm, unsigned int size=0)=0;
 297
 298         /**
 299          * Checks for implementation support of a particular XML security algorithm.
 300          *
 301          * @return  true iff the algorithm is supported by the underlying libraries
 302          */
 303         virtual bool isXMLAlgorithmSupported(const XMLCh* xmlAlgorithm)=0;
 304 #endif
 305
 306         /**
 307          * Manages factories for SOAPTransport plugins.
 308          *
 309          * <p>The factory interface takes a peer name/endpoint pair.
 310          */
 311         PluginManager<SOAPTransport,std::string,SOAPTransport::Address> SOAPTransportManager;
 312     };
 313
 314 };
 315
 316 #if defined (_MSC_VER)
 317     #pragma warning( pop )
 318 #endif
 319
 320 #endif /* __xmltooling_config_h__ */