include/dmlite/cpp/dmlite.h

Go to the documentation of this file.
00001 /// @file   include/dmlite/cpp/dmlite.h
00002 /// @brief  Entry point for DMLite.
00003 /// @author Alejandro Álvarez Ayllón <aalvarez@cern.ch>
00004 #ifndef DMLITE_CPP_DMLITE_H
00005 #define DMLITE_CPP_DMLITE_H
00006 
00007 #include "../common/config.h"
00008 #include "exceptions.h"
00009 
00010 #include <boost/any.hpp>
00011 #include <list>
00012 #include <map>
00013 #include <string>
00014 
00015 /// Namespace for the dmlite C++ API
00016 namespace dmlite {
00017 
00018   /// API Version.
00019   const unsigned API_VERSION = 20121218;
00020 
00021   // Forward declarations.
00022   class Authn;
00023   class AuthnFactory;
00024   class BaseFactory;
00025   class Catalog;
00026   class CatalogFactory;
00027   class INode;
00028   class INodeFactory;
00029   class IODriver;
00030   class IOFactory;
00031   class PoolDriver;
00032   class PoolDriverFactory;
00033   class PoolManager;
00034   class PoolManagerFactory;
00035   class SecurityContext;  
00036   class SecurityCredentials;
00037   
00038   class StackInstance;
00039 
00040   /// CatalogInterface can only be instantiated through this class.
00041   class PluginManager {
00042    public:
00043     /// Constructor
00044     PluginManager() throw ();
00045 
00046     /// Destructor
00047     ~PluginManager();
00048 
00049     /// Load a plugin. Previously instantiated interfaces won't be affected.
00050     /// @param lib     The .so file. Usually, (path)/plugin_name.so.
00051     /// @param id      The plugin ID. Usually, plugin_name.
00052     void loadPlugin(const std::string& lib,
00053                     const std::string& id) throw (DmException);
00054 
00055     /// Set a configuration parameter. It will be passed to the loaded plugins.
00056     /// @param key   The configuration parameter.
00057     /// @param value The value for the configuration parameter.
00058     void configure(const std::string& key,
00059                    const std::string& value) throw (DmException);
00060 
00061     /// Load a configuration file, with plugins and parameters.
00062     /// @param file The configuration file.
00063     void loadConfiguration(const std::string& file) throw (DmException);
00064 
00065     /// Return an entry from the loaded configuration.
00066     /// @param key The configuration parameter.
00067     std::string getConfiguration(const std::string& key) throw (DmException);
00068 
00069     /// Register a Authn factory. To be used by concrete implementations
00070     /// @param factory The UserDbGroup concrete factory.
00071     /// @note  The same object can be passed to other register functions.
00072     ///        DMLite will take care of freeing it only once.
00073     void registerAuthnFactory(AuthnFactory* factory) throw (DmException);
00074 
00075     /// Register a INode factory. To be used by concrete implementations (i.e. Plugins)
00076     /// @param factory The INode concrete factory.
00077     /// @note  The same object can be passed to other register functions.
00078     ///        DMLite will take care of freeing it only once.
00079     void registerINodeFactory(INodeFactory* factory) throw (DmException);
00080 
00081     /// Register a catalog factory. To be used by concrete implementations (i.e. Plugins)
00082     /// @param factory The catalog concrete factory.
00083     /// @note  The same object can be passed to other register functions.
00084     ///        DMLite will take care of freeing it only once.
00085     void registerCatalogFactory(CatalogFactory* factory) throw (DmException);
00086 
00087     /// Register a pool factory.
00088     /// @param factory The pool concrete factory.
00089     /// @note  The same object can be passed to other register functions.
00090     ///        DMLite will take care of freeing it only once.
00091     void registerPoolManagerFactory(PoolManagerFactory* factory) throw (DmException);
00092 
00093     /// Register a IO factory.
00094     /// @param factory The IO concrete factory.
00095     /// @note  The same object can be passed to other register functions.
00096     ///        DMLite will take care of freeing it only once.
00097     void registerIOFactory(IOFactory* factory) throw (DmException);
00098 
00099     /// Register a PoolDriver factory.
00100     /// @param factory The PoolDriver factory.
00101     /// @note  The same object can be passed to other register functions.
00102     ///        DMLite will take care of freeing it only once.
00103     void registerPoolDriverFactory(PoolDriverFactory* factory) throw (DmException);
00104     
00105     /// Register a bare BaseFactory. Only the configure method will be called.
00106     /// @param factory The BaseFactory.
00107     /// @note  The same object can be passed to other register functions.
00108     ///        DMLite will take care of freeing it only once.
00109     void registerConfigureFactory(BaseFactory* factory) throw (DmException);
00110     
00111     /// Get the AuthnFactory implementation on top of the plugin stack.
00112     AuthnFactory* getAuthnFactory() throw (DmException);
00113 
00114     // Get the INodeFactory implementation on top of the plugin stack.
00115     INodeFactory* getINodeFactory() throw (DmException);
00116 
00117     /// Get the CatalogFactory implementation on top of the plugin stack.
00118     CatalogFactory* getCatalogFactory() throw (DmException);
00119 
00120     /// Get the PoolFactory implementation on top of the plugin stack.
00121     PoolManagerFactory* getPoolManagerFactory() throw (DmException);
00122 
00123     /// Get the appropiate pool driver factory for the pool.
00124     PoolDriverFactory* getPoolDriverFactory(const std::string& pooltype) throw (DmException);
00125 
00126     /// Get the IOFactory implementation on top of the plugin stack.
00127     IOFactory* getIOFactory() throw (DmException);
00128 
00129    private:
00130     /// Configuration key/value
00131     std::map<std::string, std::string> confValues_;
00132 
00133     /// Internal list of loaded plug-ins.
00134     std::list<AuthnFactory*>       authn_plugins_;
00135     std::list<INodeFactory*>       inode_plugins_;
00136     std::list<CatalogFactory*>     catalog_plugins_;
00137     std::list<PoolManagerFactory*> pool_plugins_;
00138     std::list<IOFactory*>          io_plugins_;
00139     std::list<PoolDriverFactory*>  pool_driver_plugins_;
00140     std::list<BaseFactory*>        configure_factory_;
00141 
00142     /// Keep pointers returned by dlopen at hand to free on destruction
00143     std::list<void*> dlHandles_;
00144 
00145     /// Can not be copied
00146     PluginManager(const PluginManager&);
00147   };
00148 
00149   /// We need to have something that allows one plugin stack to access
00150   /// another plugin stack, so this represents a instantiation
00151   /// of each plugin stack.
00152   /// It also keeps common state: user credentials, security context,
00153   /// and run-time parameters (see set)
00154   /// @note Assume a StackInstance (and every instantiated interface under it)
00155   ///       is NOT thread-safe. This means, a StackInstance must be used by only
00156   ///       one thread at the same time.
00157   class StackInstance {
00158    public:
00159     /// Constructor.
00160     StackInstance(PluginManager* pm) throw(DmException);
00161 
00162     /// Destructor.
00163     ~StackInstance();
00164 
00165     /// Set a key-value pair associated with this context.
00166     /// This can be used to pass advanced parameters to and from the plugins.
00167     /// @param key   The key.
00168     /// @param value The value.
00169     void set(const std::string& key, const boost::any& value) throw (DmException);
00170 
00171     /// Get a value associated to a key.
00172     /// This can be used to pass advanced parameters to and from the plugins.
00173     /// @param key The key parameter.
00174     boost::any get(const std::string& key) const throw (DmException);
00175 
00176     /// Erase a key,value pair from.
00177     /// @param key The key of the pair to be erased.
00178     void erase(const std::string& key) throw (DmException);
00179 
00180     /// Erase all the values set previously.
00181     void eraseAll(void) throw ();
00182 
00183     /// Checks if the stack instance contains a value associated with
00184     /// the given key.
00185     bool contains(const std::string& key) throw ();
00186 
00187     /// Get the plugin manager.
00188     PluginManager* getPluginManager() throw (DmException);
00189 
00190     /// Set the security credentials.
00191     void setSecurityCredentials(const SecurityCredentials& cred) throw (DmException);
00192 
00193     /// Set the security context.
00194     void setSecurityContext(const SecurityContext& ctx) throw (DmException);
00195 
00196     /// Return the security context.
00197     const SecurityContext* getSecurityContext(void) const throw ();
00198 
00199     /// Get the UsersDb interface.
00200     Authn* getAuthn() throw (DmException);
00201 
00202     /// Get the INode.
00203     INode* getINode() throw (DmException);
00204 
00205     /// Get the catalog.
00206     Catalog* getCatalog() throw (DmException);
00207 
00208     // Check if there is a PoolManager available
00209     bool isTherePoolManager() throw ();
00210 
00211     /// Get the PoolManager.
00212     PoolManager* getPoolManager() throw (DmException);
00213 
00214     /// Get a pool driver.
00215     PoolDriver* getPoolDriver(const std::string& poolType) throw (DmException);
00216 
00217     /// Get the IO driver.
00218     IODriver* getIODriver() throw (DmException);
00219 
00220   private:
00221     PluginManager* pluginManager_;
00222 
00223     Authn*       authn_;
00224     INode*       inode_;
00225     Catalog*     catalog_;
00226     PoolManager* poolManager_;
00227     IODriver*    ioDriver_;
00228 
00229     SecurityContext* secCtx_;
00230 
00231     std::map<std::string, PoolDriver*> poolDrivers_;
00232 
00233     std::map<std::string, boost::any> stackMsg_;
00234 
00235     void setSecurityContextImpl_(void);
00236   };
00237 
00238   /// Joint between plugins and plugin-manager
00239   struct PluginIdCard {
00240     /// Used to make sure API is consistent.
00241     unsigned const  ApiVersion;
00242     /// Let the plug-in register itself and its concrete factories
00243     void (*registerPlugin)(PluginManager* pm) throw (DmException);
00244   };
00245 
00246   /// Macro intended to allow future expansions of the PluginIdCard header
00247   /// easily.
00248   #define PLUGIN_ID_HEADER dmlite::API_VERSION
00249 
00250 };
00251 
00252 #endif // DMLITE_CPP_DMLITE_H

Generated on 11 Jul 2013 for dmlite by  doxygen 1.4.7