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 "../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