dmlite  0.6
dmlite.h
Go to the documentation of this file.
1 /// @file include/dmlite/cpp/dmlite.h
2 /// @brief Entry point for DMLite.
3 /// @author Alejandro Álvarez Ayllón <aalvarez@cern.ch>
4 #ifndef DMLITE_CPP_DMLITE_H
5 #define DMLITE_CPP_DMLITE_H
6 
7 #include "dmlite/common/config.h"
8 #include "exceptions.h"
9 
10 #include <boost/any.hpp>
11 #include <list>
12 #include <map>
13 #include <string>
14 
15 /// Namespace for the dmlite C++ API
16 namespace dmlite {
17 
18  /// API Version.
19  const unsigned API_VERSION = 20121218;
20 
21  // Forward declarations.
22  class Authn;
23  class AuthnFactory;
24  class BaseFactory;
25  class Catalog;
26  class CatalogFactory;
27  class INode;
28  class INodeFactory;
29  class IODriver;
30  class IOFactory;
31  class PoolDriver;
32  class PoolDriverFactory;
33  class PoolManager;
34  class PoolManagerFactory;
35  class SecurityContext;
36  class SecurityCredentials;
37 
38  class StackInstance;
39 
40  /// CatalogInterface can only be instantiated through this class.
41  class PluginManager {
42  public:
43  /// Constructor
44  PluginManager() throw ();
45 
46  /// Destructor
48 
49  /// Load a plugin. Previously instantiated interfaces won't be affected.
50  /// @param lib The .so file. Usually, (path)/plugin_name.so.
51  /// @param id The plugin ID. Usually, plugin_name.
52  void loadPlugin(const std::string& lib,
53  const std::string& id) throw (DmException);
54 
55  /// Set a configuration parameter. It will be passed to the loaded plugins.
56  /// @param key The configuration parameter.
57  /// @param value The value for the configuration parameter.
58  void configure(const std::string& key,
59  const std::string& value) throw (DmException);
60 
61  /// Load a configuration file, with plugins and parameters.
62  /// @param file The configuration file.
63  void loadConfiguration(const std::string& file) throw (DmException);
64 
65  /// Return an entry from the loaded configuration.
66  /// @param key The configuration parameter.
67  std::string getConfiguration(const std::string& key) throw (DmException);
68 
69  /// Register a Authn factory. To be used by concrete implementations
70  /// @param factory The UserDbGroup concrete factory.
71  /// @note The same object can be passed to other register functions.
72  /// DMLite will take care of freeing it only once.
73  void registerAuthnFactory(AuthnFactory* factory) throw (DmException);
74 
75  /// Register a INode factory. To be used by concrete implementations (i.e. Plugins)
76  /// @param factory The INode concrete factory.
77  /// @note The same object can be passed to other register functions.
78  /// DMLite will take care of freeing it only once.
79  void registerINodeFactory(INodeFactory* factory) throw (DmException);
80 
81  /// Register a catalog factory. To be used by concrete implementations (i.e. Plugins)
82  /// @param factory The catalog concrete factory.
83  /// @note The same object can be passed to other register functions.
84  /// DMLite will take care of freeing it only once.
85  void registerCatalogFactory(CatalogFactory* factory) throw (DmException);
86 
87  /// Register a pool factory.
88  /// @param factory The pool concrete factory.
89  /// @note The same object can be passed to other register functions.
90  /// DMLite will take care of freeing it only once.
92 
93  /// Register a IO factory.
94  /// @param factory The IO concrete factory.
95  /// @note The same object can be passed to other register functions.
96  /// DMLite will take care of freeing it only once.
97  void registerIOFactory(IOFactory* factory) throw (DmException);
98 
99  /// Register a PoolDriver factory.
100  /// @param factory The PoolDriver factory.
101  /// @note The same object can be passed to other register functions.
102  /// DMLite will take care of freeing it only once.
104 
105  /// Register a bare BaseFactory. Only the configure method will be called.
106  /// @param factory The BaseFactory.
107  /// @note The same object can be passed to other register functions.
108  /// DMLite will take care of freeing it only once.
109  void registerConfigureFactory(BaseFactory* factory) throw (DmException);
110 
111  /// Get the AuthnFactory implementation on top of the plugin stack.
113 
114  // Get the INodeFactory implementation on top of the plugin stack.
116 
117  /// Get the CatalogFactory implementation on top of the plugin stack.
119 
120  /// Get the PoolFactory implementation on top of the plugin stack.
122 
123  /// Get the appropiate pool driver factory for the pool.
124  PoolDriverFactory* getPoolDriverFactory(const std::string& pooltype) throw (DmException);
125 
126  /// Get the IOFactory implementation on top of the plugin stack.
128 
129  private:
130  /// Configuration key/value
131  std::map<std::string, std::string> confValues_;
132 
133  /// Internal list of loaded plug-ins.
134  std::list<AuthnFactory*> authn_plugins_;
135  std::list<INodeFactory*> inode_plugins_;
136  std::list<CatalogFactory*> catalog_plugins_;
137  std::list<PoolManagerFactory*> pool_plugins_;
138  std::list<IOFactory*> io_plugins_;
139  std::list<PoolDriverFactory*> pool_driver_plugins_;
140  std::list<BaseFactory*> configure_factory_;
141 
142  /// Keep pointers returned by dlopen at hand to free on destruction
143  std::list<void*> dlHandles_;
144 
145  /// Can not be copied
147  };
148 
149  /// We need to have something that allows one plugin stack to access
150  /// another plugin stack, so this represents a instantiation
151  /// of each plugin stack.
152  /// It also keeps common state: user credentials, security context,
153  /// and run-time parameters (see set)
154  /// @note Assume a StackInstance (and every instantiated interface under it)
155  /// is NOT thread-safe. This means, a StackInstance must be used by only
156  /// one thread at the same time.
158  public:
159  /// Constructor.
161 
162  /// Destructor.
163  ~StackInstance();
164 
165  /// Set a key-value pair associated with this context.
166  /// This can be used to pass advanced parameters to and from the plugins.
167  /// @param key The key.
168  /// @param value The value.
169  void set(const std::string& key, const boost::any& value) throw (DmException);
170 
171  /// Get a value associated to a key.
172  /// This can be used to pass advanced parameters to and from the plugins.
173  /// @param key The key parameter.
174  boost::any get(const std::string& key) const throw (DmException);
175 
176  /// Erase a key,value pair from.
177  /// @param key The key of the pair to be erased.
178  void erase(const std::string& key) throw (DmException);
179 
180  /// Erase all the values set previously.
181  void eraseAll(void) throw ();
182 
183  /// Checks if the stack instance contains a value associated with
184  /// the given key.
185  bool contains(const std::string& key) throw ();
186 
187  /// Get the plugin manager.
189 
190  /// Set the security credentials.
191  void setSecurityCredentials(const SecurityCredentials& cred) throw (DmException);
192 
193  /// Set the security context.
194  void setSecurityContext(const SecurityContext& ctx) throw (DmException);
195 
196  /// Return the security context.
197  const SecurityContext* getSecurityContext(void) const throw ();
198 
199  /// Get the UsersDb interface.
200  Authn* getAuthn() throw (DmException);
201 
202  /// Get the INode.
203  INode* getINode() throw (DmException);
204 
205  /// Get the catalog.
206  Catalog* getCatalog() throw (DmException);
207 
208  // Check if there is a PoolManager available
209  bool isTherePoolManager() throw ();
210 
211  /// Get the PoolManager.
213 
214  /// Get a pool driver.
215  PoolDriver* getPoolDriver(const std::string& poolType) throw (DmException);
216 
217  /// Get the IO driver.
218  IODriver* getIODriver() throw (DmException);
219 
220  private:
222 
228 
230 
231  std::map<std::string, PoolDriver*> poolDrivers_;
232 
233  std::map<std::string, boost::any> stackMsg_;
234 
235  void setSecurityContextImpl_(void);
236  };
237 
238  /// Joint between plugins and plugin-manager
239  struct PluginIdCard {
240  /// Used to make sure API is consistent.
241  unsigned const ApiVersion;
242  /// Let the plug-in register itself and its concrete factories
244  };
245 
246  /// Macro intended to allow future expansions of the PluginIdCard header
247  /// easily.
248  #define PLUGIN_ID_HEADER dmlite::API_VERSION
249 
250 };
251 
252 #endif // DMLITE_CPP_DMLITE_H
Authn * authn_
Definition: dmlite.h:223
Plug-ins must implement a concrete factory to be instantiated.
Definition: io.h:140
void registerINodeFactory(INodeFactory *factory)
void eraseAll(void)
Erase all the values set previously.
Plug-ins must implement a concrete factory to be instantiated.
Definition: poolmanager.h:76
Plug-ins must implement a concrete factory to be instantiated.
Definition: catalog.h:216
Catalog * catalog_
Definition: dmlite.h:225
const unsigned API_VERSION
API Version.
Definition: dmlite.h:19
Definition: dmlite.h:157
void registerIOFactory(IOFactory *factory)
const SecurityContext * getSecurityContext(void) const
Return the security context.
void setSecurityContext(const SecurityContext &ctx)
Set the security context.
Security context. To be created by the Authn.
Definition: authn.h:64
CatalogFactory * getCatalogFactory()
Get the CatalogFactory implementation on top of the plugin stack.
INode * inode_
Definition: dmlite.h:224
Header generated by CMake with the build configuration used.
PoolManagerFactory * getPoolManagerFactory()
Get the PoolFactory implementation on top of the plugin stack.
Base exception class.
Definition: exceptions.h:17
void registerAuthnFactory(AuthnFactory *factory)
PluginManager * getPluginManager()
Get the plugin manager.
void registerConfigureFactory(BaseFactory *factory)
PoolManager * getPoolManager()
Get the PoolManager.
~PluginManager()
Destructor.
CatalogInterface can only be instantiated through this class.
Definition: dmlite.h:41
Interface for pool types.
Definition: poolmanager.h:33
Definition: authn.h:87
Interface for Catalog (Namespaces).
Definition: catalog.h:29
PluginManager * pluginManager_
Definition: dmlite.h:221
StackInstance(PluginManager *pm)
Constructor.
void set(const std::string &key, const boost::any &value)
std::list< AuthnFactory * > authn_plugins_
Internal list of loaded plug-ins.
Definition: dmlite.h:134
void setSecurityCredentials(const SecurityCredentials &cred)
Set the security credentials.
PoolDriver * getPoolDriver(const std::string &poolType)
Get a pool driver.
void configure(const std::string &key, const std::string &value)
IODriver * ioDriver_
Definition: dmlite.h:227
AuthnFactory.
Definition: authn.h:177
void loadPlugin(const std::string &lib, const std::string &id)
INodeFactory.
Definition: inode.h:254
void loadConfiguration(const std::string &file)
Exceptions used by the API.
unsigned const ApiVersion
Used to make sure API is consistent.
Definition: dmlite.h:241
std::map< std::string, PoolDriver * > poolDrivers_
Definition: dmlite.h:231
Authn * getAuthn()
Get the UsersDb interface.
IOFactory * getIOFactory()
Get the IOFactory implementation on top of the plugin stack.
std::list< void * > dlHandles_
Keep pointers returned by dlopen at hand to free on destruction.
Definition: dmlite.h:143
PoolDriverFactory * getPoolDriverFactory(const std::string &pooltype)
Get the appropiate pool driver factory for the pool.
Base class for factories.
Definition: base.h:48
PoolDriver factory.
Definition: pooldriver.h:117
INode * getINode()
Get the INode.
SecurityContext * secCtx_
Definition: dmlite.h:229
void registerPoolDriverFactory(PoolDriverFactory *factory)
Definition: inode.h:90
INodeFactory * getINodeFactory()
std::list< INodeFactory * > inode_plugins_
Definition: dmlite.h:135
Catalog * getCatalog()
Get the catalog.
std::list< PoolDriverFactory * > pool_driver_plugins_
Definition: dmlite.h:139
PoolManager * poolManager_
Definition: dmlite.h:226
std::list< BaseFactory * > configure_factory_
Definition: dmlite.h:140
std::string getConfiguration(const std::string &key)
Joint between plugins and plugin-manager.
Definition: dmlite.h:239
void registerCatalogFactory(CatalogFactory *factory)
PluginManager()
Constructor.
std::list< CatalogFactory * > catalog_plugins_
Definition: dmlite.h:136
void(* registerPlugin)(PluginManager *pm)
Let the plug-in register itself and its concrete factories.
Definition: dmlite.h:243
std::map< std::string, std::string > confValues_
Configuration key/value.
Definition: dmlite.h:131
Security credentials. To be filled by the front-end.
Definition: authn.h:22
AuthnFactory * getAuthnFactory()
Get the AuthnFactory implementation on top of the plugin stack.
IO Driver.
Definition: io.h:103
Interface for a pool driver.
Definition: pooldriver.h:92
std::list< IOFactory * > io_plugins_
Definition: dmlite.h:138
std::list< PoolManagerFactory * > pool_plugins_
Definition: dmlite.h:137
IODriver * getIODriver()
Get the IO driver.
void setSecurityContextImpl_(void)
~StackInstance()
Destructor.
void erase(const std::string &key)
bool contains(const std::string &key)
std::map< std::string, boost::any > stackMsg_
Definition: dmlite.h:233
void registerPoolManagerFactory(PoolManagerFactory *factory)