Tulip  4.1.0
Better Visualization Through Research
 All Classes Files Functions Variables Enumerations Enumerator Properties Groups Pages
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 1 and Inria Bordeaux - Sud Ouest
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 <set>
26 
27 #include <tulip/Plugin.h>
28 #include <tulip/TlpTools.h>
29 #include <tulip/PluginLibraryLoader.h>
30 
31 namespace tlp {
32 class PluginContext;
33 
34 /**
35  * @ingroup Plugins
36  * @brief The base class for plugin factories.
37  *
38  * 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 informations.
39  * @see PLUGIN
40  **/
42 public:
43  virtual tlp::Plugin* createPluginObject(tlp::PluginContext* context) = 0;
44 };
45 
46 /**
47  * @ingroup Plugins
48  *
49  * @brief The PluginLister class is a singleton used to list plugins currently loaded into Tulip and retrieve informations about them.
50  *
51  * This class holds various methods to check informations about plugins currently loaded into Tulip. You can use it to list plugins, get dependencies informations or create an instance of a plugin.
52  *
53  * @note Since a plugin name is unique, Plugins are mainly identified by their name (tlp::Plugin::name()) when interfaced with the plugin lister.
54  *
55  * @see tlp::Plugin
56  * @see tlp::PluginLoader
57  * @see tlp::PluginLibraryLoader
58  */
59 class TLP_SCOPE PluginLister {
60 private:
61  struct PluginDescription {
62  FactoryInterface* factory;
63  std::string library;
64  };
65 
66 public:
67  static PluginLoader *currentLoader;
68 
69  /**
70  * @brief Checks if all registered plug-ins have their dependencies met.
71  *
72  * @param loader If there are errors, the loader is informed about them so they can be displayed.
73  * @return void
74  **/
75  static void checkLoadedPluginsDependencies(tlp::PluginLoader* loader);
76 
77  /**
78  * @brief Gets the static instance of this class. If not already done, creates it beforehand.
79  *
80  * @return PluginLister< ObjectType, Context >* The only instance of this object that exists in the whole program.
81  **/
82  static tlp::PluginLister* instance();
83 
84  /**
85  * @brief Constructs a plug-in.
86  *
87  * @param name The name of the plug-in to instantiate.
88  * @param p The context to give to the plug-in.
89  * @return ObjectType* The newly constructed plug-in.
90  **/
91  static tlp::Plugin* getPluginObject(const std::string& name, tlp::PluginContext* context);
92 
93  /**
94  * @brief Checks if a plugin of a given type is loaded
95  * This method checks the plugin "pluginName" is currently loaded into Tulip and if it's of type PluginType.
96  * @param PluginType the class type of the plugin
97  * @param pluginName the name of the plugin
98  * @return true if a matching plugin is currently loaded into Tulip.
99  */
100  template<typename PluginType>
101  bool pluginExists(const std::string &pluginName) {
102  const Plugin* p = getPluginObject(pluginName,NULL);
103 
104  if (p == NULL)
105  return false;
106 
107  bool result = dynamic_cast<const PluginType*>(p) != NULL;
108  delete p;
109  return result;
110  }
111 
112  /**
113  * @brief Similar to tlp::PluginLister::getPluginObject() but returns a typed instance
114  *
115  * This method instantiate a plugin from its name and returns it casted into the given type.
116  *
117  * @param name The plugin's name
118  * @param context The context to give to the plugin
119  *
120  * @return The plugin instance. If there is no such plugin or if the plugin does not match the required type, this method returns NULL
121  */
122  template<typename PluginType>
123  PluginType* getPluginObject(const std::string& name, tlp::PluginContext* context) {
124  Plugin* p = getPluginObject(name,context);
125  PluginType* result = dynamic_cast<PluginType*>(getPluginObject(name, context));
126 
127  if (result == NULL && p != NULL)
128  delete p;
129 
130  return result;
131  }
132 
133 
134  /**
135  * @brief Gets the list of plug-ins that registered themselves in this factory.
136  *
137  * @return :Iterator< std::string >* An iterator over the names of the plug-ins registered in this factory.
138  **/
139  static std::list<std::string> availablePlugins();
140 
141  template<typename PluginType>
142  std::list<std::string> availablePlugins() {
143  std::list<std::string> keys;
144 
145  for(std::map<std::string , PluginDescription>::const_iterator it = _plugins.begin(); it != _plugins.end(); ++it) {
146  PluginType* plugin = dynamic_cast<PluginType*>(it->second.factory->createPluginObject(NULL));
147 
148  if(plugin != NULL) {
149  keys.push_back(it->first);
150  }
151 
152  delete plugin;
153  }
154 
155  return keys;
156  }
157 
158  /**
159  * @brief Gets more detailed informations about one specific plug-in.
160  *
161  * @param name The name of the plugin to retrieve informations for.
162  * @return :Plugin* The informations on the plugin.
163  **/
164  static const Plugin* pluginInformations(const std::string& name);
165 
166  /**
167  * @brief Checks if a given name is registered in this factory.
168  *
169  * @param pluginName The name of the plug-in to look for.
170  * @return bool Whether there is a plug-in with the given name registered in this factory.
171  **/
172  static bool pluginExists(const std::string& pluginName);
173 
174  /**
175  * @brief Gets the list of parameters for the given plug-in.
176  *
177  * @param name The name of the plug-in to retrieve the parameters of.
178  * @return :ParameterDescriptionList The parameters of the plug-in.
179  **/
180  static const ParameterDescriptionList getPluginParameters(std::string name);
181 
182  /**
183  * @brief Gets the dependencies of a plug-in.
184  *
185  * @param name The name of the plug-in to retrieve the dependencies of.
186  * @return :list< tlp::Dependency, std::allocator< tlp::Dependency > > The list of dependencies of the plug-in.
187  **/
188  static std::list<tlp::Dependency> getPluginDependencies(std::string name);
189 
190  /**
191  * @brief Gets the library from which a plug-in has been loaded.
192  *
193  * @param name The name of the plug-in to retrieve the library of.
194  * @return std::string The library from which the plug-in was loaded.
195  **/
196  static std::string getPluginLibrary(const std::string& name);
197 
198  /**
199  * @brief Removes a plug-in from this factory.
200  * This is usefull when a plug-in has unmet dependencies, or appears more than once.
201  *
202  * @param name The name of the plug-in to remove.
203  * @return void
204  **/
205  static void removePlugin(const std::string &name);
206 
207  /**
208  * @brief Registers a plugin into Tulip
209  *
210  * @warning This method should only be called by tlp::FactoryInterface subclasses
211  * @see PLUGIN
212  */
213  static void registerPlugin(FactoryInterface* objectFactory);
214 
215 protected:
216  static PluginLister* _instance;
217 
218  /**
219  * @brief Stores the factory, dependencies, and parameters of all the plugins that register into this factory.
220  **/
221  std::map<std::string , PluginDescription> _plugins;
222 
223  /**
224  * @brief Gets the release number of the given plug-in.
225  *
226  * @param name The name of the plug-in to retrieve the version number of.
227  * @return :string The version number, ussually formatted as X[.Y], where X is the major, and Y the minor.
228  **/
229  static std::string getPluginRelease(std::string name);
230 };
231 
232 }
233 
234 #endif //TULIP_PLUGINLISTER_H