Tulip  5.0.0
Large graphs analysis and drawing
PluginLister.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef TULIP_PLUGINLISTER_H
21 #define TULIP_PLUGINLISTER_H
22 
23 #include <list>
24 #include <string>
25 #include <map>
26 
27 #include <tulip/Plugin.h>
28 #include <tulip/PluginLoader.h>
29 #include <tulip/Observable.h>
30 
31 
32 namespace tlp {
33 class PluginContext;
34 
35 ///@cond DOXYGEN_HIDDEN
36 /**
37  * @ingroup Plugins
38  * @brief The base class for plugin factories.
39  *
40  * A plugin factory handles the creation process of a tlp::Plugin subclass. This class should never be used directly. See the PLUGIN macro for additional information.
41  * @see PLUGIN
42  **/
43 class FactoryInterface {
44 public:
45  virtual tlp::Plugin* createPluginObject(tlp::PluginContext* context) = 0;
46 };
47 ///@endcond
48 
49 /**
50  * @ingroup Plugins
51  *
52  * @brief The PluginLister class is a singleton used to list plugins currently loaded into Tulip and retrieve information about them.
53  *
54  * This class holds various methods to check information about plugins currently loaded into Tulip. You can use it to list plugins, get dependencies information or create an instance of a plugin.
55  *
56  * @note Since a plugin name is unique, Plugins are mainly identified by their name (tlp::Plugin::name()) when interfaced with the plugin lister.
57  *
58  * @see tlp::Plugin
59  * @see tlp::PluginLoader
60  * @see tlp::PluginLibraryLoader
61  */
62 class TLP_SCOPE PluginLister : public Observable {
63 private:
64  struct PluginDescription {
65  FactoryInterface* factory;
66  std::string library;
67  Plugin* info;
68 
69  PluginDescription(): factory(NULL), info(NULL) {}
70  ~PluginDescription() {
71  delete info;
72  }
73  };
74 
75 public:
76  static PluginLoader *currentLoader;
77 
78  /**
79  * @brief Checks if all registered plug-ins have their dependencies met.
80  *
81  * @param loader If there are errors, the loader is informed about them so they can be displayed.
82  * @return void
83  **/
84  static void checkLoadedPluginsDependencies(tlp::PluginLoader* loader);
85 
86  /**
87  * @brief Gets the static instance of this class. If not already done, creates it beforehand.
88  *
89  * @return PluginLister< ObjectType, Context >* The only instance of this object that exists in the whole program.
90  **/
91  static tlp::PluginLister* instance();
92 
93  /**
94  * @brief Constructs a plug-in.
95  *
96  * @param name The name of the plug-in to instantiate.
97  * @param p The context to give to the plug-in.
98  * @return ObjectType* The newly constructed plug-in.
99  **/
100  static tlp::Plugin* getPluginObject(const std::string& name, tlp::PluginContext* context);
101 
102  /**
103  * @brief Checks if a plugin of a given type is loaded
104  * This method checks the plugin "pluginName" is currently loaded into Tulip and if it's of type PluginType.
105  * @param PluginType the class type of the plugin
106  * @param pluginName the name of the plugin
107  * @return true if a matching plugin is currently loaded into Tulip.
108  */
109  template<typename PluginType>
110  bool pluginExists(const std::string &pluginName) {
111  std::map<std::string, PluginDescription>::const_iterator it =
112  _plugins.find(pluginName);
113  return (it != _plugins.end() &&
114  (dynamic_cast<const PluginType*>(it->second.info) != NULL));
115  }
116 
117  /**
118  * @brief Similar to tlp::PluginLister::getPluginObject() but returns a typed instance
119  *
120  * This method instantiate a plugin from its name and returns it casted into the given type.
121  *
122  * @param name The plugin's name
123  * @param context The context to give to the plugin
124  *
125  * @return The plugin instance. If there is no such plugin or if the plugin does not match the required type, this method returns NULL
126  */
127  template<typename PluginType>
128  PluginType* getPluginObject(const std::string& name,
129  tlp::PluginContext* context) {
130  std::map<std::string, PluginDescription>::const_iterator it =
131  _plugins.find(name);
132  return (it != _plugins.end() &&
133  (dynamic_cast<const PluginType*>(it->second.info) != NULL))
134  ? static_cast<PluginType*>(it->second.factory->createPluginObject(context))
135  : NULL;
136  }
137 
138 
139  /**
140  * @brief Gets the list of plugins of a given type (template parameter).
141  * @return A std::list<std::string> containing plugin names.
142  **/
143  static std::list<std::string> availablePlugins();
144 
145 
146  template<typename PluginType>
147  std::list<std::string> availablePlugins() {
148  std::list<std::string> keys;
149 
150  for(std::map<std::string, PluginDescription>::const_iterator it = _plugins.begin(); it != _plugins.end(); ++it) {
151  PluginType* plugin = dynamic_cast<PluginType*>(it->second.info);
152 
153  if(plugin != NULL) {
154  keys.push_back(it->first);
155  }
156  }
157 
158  return keys;
159  }
160 
161  /**
162  * @brief Gets more detailed information about one specific plug-in.
163  *
164  * @param name The name of the plugin to retrieve information for.
165  * @return :const Plugin& The information on the plugin.
166  **/
167  static const Plugin& pluginInformation(const std::string& name);
168 
169  /**
170  * @brief Checks if a given name is registered in this factory.
171  *
172  * @param pluginName The name of the plug-in to look for.
173  * @return bool Whether there is a plug-in with the given name registered in this factory.
174  **/
175  static bool pluginExists(const std::string& pluginName);
176 
177  /**
178  * @brief Gets the list of parameters for the given plug-in.
179  *
180  * @param name The name of the plug-in to retrieve the parameters of.
181  * @return :ParameterDescriptionList The parameters of the plug-in.
182  **/
183  static const ParameterDescriptionList& getPluginParameters(const std::string& name);
184 
185  /**
186  * @brief Gets the dependencies of a plug-in.
187  *
188  * @param name The name of the plug-in to retrieve the dependencies of.
189  * @return :list< tlp::Dependency, std::allocator< tlp::Dependency > > The list of dependencies of the plug-in.
190  **/
191  static const std::list<tlp::Dependency>& getPluginDependencies(const std::string& name);
192 
193  /**
194  * @brief Gets the library from which a plug-in has been loaded.
195  *
196  * @param name The name of the plug-in to retrieve the library of.
197  * @return std::string The library from which the plug-in was loaded.
198  **/
199  static std::string getPluginLibrary(const std::string& name);
200 
201  /**
202  * @brief Removes a plug-in from this factory.
203  * This is usefull when a plug-in has unmet dependencies, or appears more than once.
204  *
205  * @param name The name of the plug-in to remove.
206  * @return void
207  **/
208  static void removePlugin(const std::string& name);
209 
210  /**
211  * @brief Registers a plugin into Tulip
212  *
213  * @warning This method should only be called by tlp::FactoryInterface subclasses
214  * @see PLUGIN
215  */
216  static void registerPlugin(FactoryInterface* objectFactory);
217 
218 ///@cond DOXYGEN_HIDDEN
219 protected:
220 
221 
222  void sendPluginAddedEvent(const std::string &pluginName);
223  void sendPluginRemovedEvent(const std::string &pluginName);
224 
225  static PluginLister* _instance;
226 
227  /**
228  * @brief Stores the factory, dependencies, and parameters of all the plugins that register into this factory.
229  **/
230  std::map<std::string , PluginDescription> _plugins;
231 
232  /**
233  * @brief Gets the release number of the given plug-in.
234  *
235  * @param name The name of the plug-in to retrieve the version number of.
236  * @return :string The version number, ussually formatted as X[.Y], where X is the major, and Y the minor.
237  **/
238  static std::string getPluginRelease(const std::string& name);
239 ///@endcond
240 };
241 
242 ///@cond DOXYGEN_HIDDEN
243 class TLP_SCOPE PluginEvent : public Event {
244 public:
245 
246  enum PluginEventType {
247  TLP_ADD_PLUGIN = 0,
248  TLP_REMOVE_PLUGIN = 1
249  };
250 
251  // constructor for node/edge events
252  PluginEvent(PluginEventType pluginEvtType, const std::string& pluginName)
253  : Event(*(tlp::PluginLister::instance()), Event::TLP_MODIFICATION),
254  evtType(pluginEvtType), pluginName(pluginName) {}
255 
256  PluginEventType getType() const {
257  return evtType;
258  }
259 
260  std::string getPluginName() const {
261  return pluginName;
262  }
263 
264 protected:
265 
266  PluginEventType evtType;
267  std::string pluginName;
268 
269 };
270 ///@endcond
271 
272 }
273 
274 #endif //TULIP_PLUGINLISTER_H
The PluginLister class is a singleton used to list plugins currently loaded into Tulip and retrieve i...
Definition: PluginLister.h:62
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:47
Contains runtime parameters for a plugin.
Definition: PluginContext.h:39
Top-level interface for plug-ins.
Definition: Plugin.h:79
PluginType * getPluginObject(const std::string &name, tlp::PluginContext *context)
Similar to tlp::PluginLister::getPluginObject() but returns a typed instance.
Definition: PluginLister.h:128
The Observable class is the base of Tulip&#39;s observation system.
Definition: Observable.h:123
This class describes parameters taken by a plugin.
bool pluginExists(const std::string &pluginName)
Checks if a plugin of a given type is loaded This method checks the plugin "pluginName" is currently ...
Definition: PluginLister.h:110
A callback class when loading plugins into Tulip.
Definition: PluginLoader.h:40
static tlp::PluginLister * instance()
Gets the static instance of this class. If not already done, creates it beforehand.