Tulip  4.10.0
Better Visualization Through Research
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* infos;
68 
69  PluginDescription(): factory(NULL), infos(NULL) {}
70  ~PluginDescription() {
71  delete infos;
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.infos) != 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.infos) != 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.infos);
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 Gets more detailed information about one specific plug-in.
171  * @deprecated this function should not be used anymore, please use PluginLister::pluginInformation() instead.
172  *
173  * @param name The name of the plugin to retrieve information for.
174  * @return :const Plugin& The information on the plugin.
175  **/
176  static _DEPRECATED const Plugin& pluginInformations(const std::string& name);
177 
178  /**
179  * @brief Checks if a given name is registered in this factory.
180  *
181  * @param pluginName The name of the plug-in to look for.
182  * @return bool Whether there is a plug-in with the given name registered in this factory.
183  **/
184  static bool pluginExists(const std::string& pluginName);
185 
186  /**
187  * @brief Gets the list of parameters for the given plug-in.
188  *
189  * @param name The name of the plug-in to retrieve the parameters of.
190  * @return :ParameterDescriptionList The parameters of the plug-in.
191  **/
192  static const ParameterDescriptionList& getPluginParameters(const std::string& name);
193 
194  /**
195  * @brief Gets the dependencies of a plug-in.
196  *
197  * @param name The name of the plug-in to retrieve the dependencies of.
198  * @return :list< tlp::Dependency, std::allocator< tlp::Dependency > > The list of dependencies of the plug-in.
199  **/
200  static const std::list<tlp::Dependency>& getPluginDependencies(const std::string& name);
201 
202  /**
203  * @brief Gets the library from which a plug-in has been loaded.
204  *
205  * @param name The name of the plug-in to retrieve the library of.
206  * @return std::string The library from which the plug-in was loaded.
207  **/
208  static std::string getPluginLibrary(const std::string& name);
209 
210  /**
211  * @brief Removes a plug-in from this factory.
212  * This is usefull when a plug-in has unmet dependencies, or appears more than once.
213  *
214  * @param name The name of the plug-in to remove.
215  * @return void
216  **/
217  static void removePlugin(const std::string& name);
218 
219  /**
220  * @brief Registers a plugin into Tulip
221  *
222  * @warning This method should only be called by tlp::FactoryInterface subclasses
223  * @see PLUGIN
224  */
225  static void registerPlugin(FactoryInterface* objectFactory);
226 
227 ///@cond DOXYGEN_HIDDEN
228 protected:
229 
230 
231  void sendPluginAddedEvent(const std::string &pluginName);
232  void sendPluginRemovedEvent(const std::string &pluginName);
233 
234  static PluginLister* _instance;
235 
236  /**
237  * @brief Stores the factory, dependencies, and parameters of all the plugins that register into this factory.
238  **/
239  std::map<std::string , PluginDescription> _plugins;
240 
241  /**
242  * @brief Gets the release number of the given plug-in.
243  *
244  * @param name The name of the plug-in to retrieve the version number of.
245  * @return :string The version number, ussually formatted as X[.Y], where X is the major, and Y the minor.
246  **/
247  static std::string getPluginRelease(const std::string& name);
248 ///@endcond
249 };
250 
251 ///@cond DOXYGEN_HIDDEN
252 class TLP_SCOPE PluginEvent : public Event {
253 public:
254 
255  enum PluginEventType {
256  TLP_ADD_PLUGIN = 0,
257  TLP_REMOVE_PLUGIN = 1
258  };
259 
260  // constructor for node/edge events
261  PluginEvent(PluginEventType pluginEvtType, const std::string& pluginName)
262  : Event(*(tlp::PluginLister::instance()), Event::TLP_MODIFICATION),
263  evtType(pluginEvtType), pluginName(pluginName) {}
264 
265  PluginEventType getType() const {
266  return evtType;
267  }
268 
269  std::string getPluginName() const {
270  return pluginName;
271  }
272 
273 protected:
274 
275  PluginEventType evtType;
276  std::string pluginName;
277 
278 };
279 ///@endcond
280 
281 }
282 
283 #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.