dmlite  0.4
p/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 <boost/any.hpp>
8 #include <list>
9 #include <map>
10 #include <string>
11 #include "exceptions.h"
12 
13 /// Namespace for the libdm C++ API
14 namespace dmlite {
15 
16  /// API Version.
17  const unsigned API_VERSION = 20120817;
18 
19  // Forward declarations.
20  class Authn;
21  class AuthnFactory;
22  class Catalog;
23  class CatalogFactory;
24  class INode;
25  class INodeFactory;
26  class IODriver;
27  class IOFactory;
28  class PoolDriver;
29  class PoolDriverFactory;
30  class PoolManager;
31  class PoolManagerFactory;
32  class SecurityContext;
33  class SecurityCredentials;
34 
35  class StackInstance;
36 
37  /// CatalogInterface can only be instantiated through this class.
38  class PluginManager {
39  public:
40  /// Constructor
41  PluginManager() throw ();
42 
43  /// Destructor
45 
46  /// Load a plugin. Previously instantiated interfaces won't be affected.
47  /// @param lib The .so file. Usually, (path)/plugin_name.so.
48  /// @param id The plugin ID. Usually, plugin_name.
49  void loadPlugin(const std::string& lib,
50  const std::string& id) throw (DmException);
51 
52  /// Set a configuration parameter. It will be passed to the loaded plugins.
53  /// @param key The configuration parameter.
54  /// @param value The value for the configuration parameter.
55  void configure(const std::string& key,
56  const std::string& value) throw (DmException);
57 
58  /// Load a configuration file, with plugins and parameters.
59  /// @param file The configuration file.
60  void loadConfiguration(const std::string& file) throw (DmException);
61 
62  /// Register a Authn factory. To be used by concrete implementations
63  /// @param factory The UserDbGroup concrete factory.
64  /// @note The same object can be passed to other register functions.
65  /// DMLite will take care of freeing it only once.
66  void registerAuthnFactory(AuthnFactory* factory) throw (DmException);
67 
68  /// Register a INode factory. To be used by concrete implementations (i.e. Plugins)
69  /// @param factory The INode concrete factory.
70  /// @note The same object can be passed to other register functions.
71  /// DMLite will take care of freeing it only once.
72  void registerINodeFactory(INodeFactory* factory) throw (DmException);
73 
74  /// Register a catalog factory. To be used by concrete implementations (i.e. Plugins)
75  /// @param factory The catalog concrete factory.
76  /// @note The same object can be passed to other register functions.
77  /// DMLite will take care of freeing it only once.
78  void registerCatalogFactory(CatalogFactory* factory) throw (DmException);
79 
80  /// Register a pool factory.
81  /// @param factory The pool concrete factory.
82  /// @note The same object can be passed to other register functions.
83  /// DMLite will take care of freeing it only once.
85 
86  /// Register a IO factory.
87  /// @param factory The IO concrete factory.
88  /// @note The same object can be passed to other register functions.
89  /// DMLite will take care of freeing it only once.
90  void registerIOFactory(IOFactory* factory) throw (DmException);
91 
92  /// Register a PoolDriver factory.
93  /// @param factory The PoolDriver factory.
94  /// @note The same object can be passed to other register functions.
95  /// DMLite will take care of freeing it only once.
97 
98  /// Get the AuthnFactory implementation on top of the plugin stack.
100 
101  // Get the INodeFactory implementation on top of the plugin stack.
103 
104  /// Get the CatalogFactory implementation on top of the plugin stack.
106 
107  /// Get the PoolFactory implementation on top of the plugin stack.
109 
110  /// Get the appropiate pool driver factory for the pool.
111  PoolDriverFactory* getPoolDriverFactory(const std::string& pooltype) throw (DmException);
112 
113  /// Get the IOFactory implementation on top of the plugin stack.
115 
116  private:
117  /// Internal list of loaded plug-ins.
118  std::list<AuthnFactory*> authn_plugins_;
119  std::list<INodeFactory*> inode_plugins_;
120  std::list<CatalogFactory*> catalog_plugins_;
121  std::list<PoolManagerFactory*> pool_plugins_;
122  std::list<IOFactory*> io_plugins_;
123  std::list<PoolDriverFactory*> pool_driver_plugins_;
124 
125  /// Keep pointers returned by dlopen at hand to free on destruction
126  std::list<void*> dlHandles_;
127 
128  /// Can not be copied
130  };
131 
132  /// We need to have something that allows one plugin stack to access
133  /// another plugin stack, so this represents a instantiation
134  /// of each plugin stack.
135  /// It also keeps common state: user credentials, security context,
136  /// and run-time parameters (see set)
137  /// @note Assume a StackInstance (and every instantiated interface under it)
138  /// is NOT thread-safe. This means, a StackInstance must be used by only
139  /// one thread at the same time.
141  public:
142  /// Constructor.
144 
145  /// Destructor.
146  ~StackInstance();
147 
148  /// Set a key-value pair associated with this context.
149  /// This can be used to pass advanced parameters to and from the plugins.
150  /// @param key The key.
151  /// @param value The value.
152  void set(const std::string& key, const boost::any& value) throw (DmException);
153 
154  /// Get a value associated to a key.
155  /// This can be used to pass advanced parameters to and from the plugins.
156  /// @param key The key parameter.
157  boost::any get(const std::string& key) const throw (DmException);
158 
159  /// Erase a key,value pair from.
160  /// @param key The key of the pair to be erased.
161  void erase(const std::string& key) throw (DmException);
162 
163  /// Get the plugin manager.
165 
166  /// Set the security credentials.
167  void setSecurityCredentials(const SecurityCredentials& cred) throw (DmException);
168 
169  /// Set the security context.
170  void setSecurityContext(const SecurityContext& ctx) throw (DmException);
171 
172  /// Return the security context.
173  const SecurityContext* getSecurityContext(void) const throw ();
174 
175  /// Get the UsersDb interface.
176  Authn* getAuthn() throw (DmException);
177 
178  /// Get the INode.
179  INode* getINode() throw (DmException);
180 
181  /// Get the catalog.
182  Catalog* getCatalog() throw (DmException);
183 
184  // Check if there is a PoolManager available
185  bool isTherePoolManager() throw ();
186 
187  /// Get the PoolManager.
189 
190  /// Get a pool driver.
191  PoolDriver* getPoolDriver(const std::string& poolType) throw (DmException);
192 
193  /// Get the IO driver.
194  IODriver* getIODriver() throw (DmException);
195 
196  private:
198 
204 
206 
207  std::map<std::string, PoolDriver*> poolDrivers_;
208 
209  std::map<std::string, boost::any> stackMsg_;
210  };
211 
212  /// Joint between plugins and plugin-manager
213  struct PluginIdCard {
214  /// Used to make sure API is consistent.
215  unsigned const ApiVersion;
216  /// Let the plug-in register itself and its concrete factories
218  };
219 
220  /// Macro intended to allow future expansions of the PluginIdCard header
221  /// easily.
222  #define PLUGIN_ID_HEADER API_VERSION
223 
224 };
225 
226 #endif // DMLITE_CPP_DMLITE_H