Tulip  4.6.0
Better Visualization Through Research
library/tulip-core/include/tulip/PluginLister.h
00001 /*
00002  *
00003  * This file is part of Tulip (www.tulip-software.org)
00004  *
00005  * Authors: David Auber and the Tulip development Team
00006  * from LaBRI, University of Bordeaux
00007  *
00008  * Tulip is free software; you can redistribute it and/or modify
00009  * it under the terms of the GNU Lesser General Public License
00010  * as published by the Free Software Foundation, either version 3
00011  * of the License, or (at your option) any later version.
00012  *
00013  * Tulip is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00016  * See the GNU General Public License for more details.
00017  *
00018  */
00019 
00020 #ifndef TULIP_PLUGINLISTER_H
00021 #define TULIP_PLUGINLISTER_H
00022 
00023 #include <list>
00024 #include <string>
00025 #include <map>
00026 
00027 #include <tulip/Plugin.h>
00028 #include <tulip/PluginLoader.h>
00029 #include <tulip/Observable.h>
00030 
00031 
00032 namespace tlp {
00033 class PluginContext;
00034 
00035 /**
00036  * @ingroup Plugins
00037  * @brief The base class for plugin factories.
00038  *
00039  * 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.
00040  * @see PLUGIN
00041  **/
00042 class FactoryInterface {
00043 public:
00044   virtual tlp::Plugin* createPluginObject(tlp::PluginContext* context) = 0;
00045 };
00046 
00047 /**
00048  * @ingroup Plugins
00049  *
00050  * @brief The PluginLister class is a singleton used to list plugins currently loaded into Tulip and retrieve information about them.
00051  *
00052  * 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.
00053  *
00054  * @note Since a plugin name is unique, Plugins are mainly identified by their name (tlp::Plugin::name()) when interfaced with the plugin lister.
00055  *
00056  * @see tlp::Plugin
00057  * @see tlp::PluginLoader
00058  * @see tlp::PluginLibraryLoader
00059  */
00060 class TLP_SCOPE PluginLister : public Observable {
00061 private:
00062   struct PluginDescription {
00063     FactoryInterface* factory;
00064     std::string library;
00065     Plugin* infos;
00066 
00067     PluginDescription(): factory(NULL), infos(NULL) {}
00068     ~PluginDescription() {
00069       delete infos;
00070     }
00071   };
00072 
00073 public:
00074   static PluginLoader *currentLoader;
00075 
00076   /**
00077    * @brief Checks if all registered plug-ins have their dependencies met.
00078    *
00079    * @param loader If there are errors, the loader is informed about them so they can be displayed.
00080    * @return void
00081    **/
00082   static void checkLoadedPluginsDependencies(tlp::PluginLoader* loader);
00083 
00084   /**
00085    * @brief Gets the static instance of this class. If not already done, creates it beforehand.
00086    *
00087    * @return PluginLister< ObjectType, Context >* The only instance of this object that exists in the whole program.
00088    **/
00089   static tlp::PluginLister* instance();
00090 
00091   /**
00092    * @brief Constructs a plug-in.
00093    *
00094    * @param name The name of the plug-in to instantiate.
00095    * @param p The context to give to the plug-in.
00096    * @return ObjectType* The newly constructed plug-in.
00097    **/
00098   static tlp::Plugin* getPluginObject(const std::string& name, tlp::PluginContext* context);
00099 
00100   /**
00101    * @brief Checks if a plugin of a given type is loaded
00102    * This method checks the plugin "pluginName" is currently loaded into Tulip and if it's of type PluginType.
00103    * @param PluginType the class type of the plugin
00104    * @param pluginName the name of the plugin
00105    * @return true if a matching plugin is currently loaded into Tulip.
00106    */
00107   template<typename PluginType>
00108   bool pluginExists(const std::string &pluginName) {
00109     std::map<std::string, PluginDescription>::const_iterator it =
00110       _plugins.find(pluginName);
00111     return (it != _plugins.end() &&
00112             (dynamic_cast<const PluginType*>(it->second.infos) != NULL));
00113   }
00114 
00115   /**
00116    * @brief Similar to tlp::PluginLister::getPluginObject() but returns a typed instance
00117    *
00118    * This method instantiate a plugin from its name and returns it casted into the given type.
00119    *
00120    * @param name The plugin's name
00121    * @param context The context to give to the plugin
00122    *
00123    * @return The plugin instance. If there is no such plugin or if the plugin does not match the required type, this method returns NULL
00124    */
00125   template<typename PluginType>
00126   PluginType* getPluginObject(const std::string& name,
00127                               tlp::PluginContext* context) {
00128     std::map<std::string, PluginDescription>::const_iterator it =
00129       _plugins.find(name);
00130     return (it != _plugins.end() &&
00131             (dynamic_cast<const PluginType*>(it->second.infos) != NULL))
00132            ? static_cast<PluginType*>(it->second.factory->createPluginObject(context))
00133            : NULL;
00134   }
00135 
00136 
00137   /**
00138    * @brief Gets the list of plugins of a given type (template parameter).   *
00139    * @return A std::list<std::string> containing the names of the plugins.
00140    **/
00141   static std::list<std::string> availablePlugins();
00142 
00143 
00144   template<typename PluginType>
00145   std::list<std::string> availablePlugins() {
00146     std::list<std::string> keys;
00147 
00148     for(std::map<std::string, PluginDescription>::const_iterator it = _plugins.begin(); it != _plugins.end(); ++it) {
00149       PluginType* plugin = dynamic_cast<PluginType*>(it->second.infos);
00150 
00151       if(plugin != NULL) {
00152         keys.push_back(it->first);
00153       }
00154     }
00155 
00156     return keys;
00157   }
00158 
00159   /**
00160    * @brief Gets more detailed information about one specific plug-in.
00161    *
00162    * @param name The name of the plugin to retrieve information for.
00163    * @return :const Plugin& The information on the plugin.
00164    **/
00165   static const Plugin& pluginInformation(const std::string& name);
00166 
00167   /**
00168    * @brief Gets more detailed information about one specific plug-in.
00169    * @deprecated this function should not be used anymore, please use PluginLister::pluginInformation() instead.
00170    *
00171    * @param name The name of the plugin to retrieve information for.
00172    * @return :const Plugin& The information on the plugin.
00173    **/
00174   static _DEPRECATED const Plugin& pluginInformations(const std::string& name);
00175 
00176   /**
00177    * @brief Checks if a given name is registered in this factory.
00178    *
00179    * @param pluginName The name of the plug-in to look for.
00180    * @return bool Whether there is a plug-in with the given name registered in this factory.
00181    **/
00182   static bool pluginExists(const std::string& pluginName);
00183 
00184   /**
00185    * @brief Gets the list of parameters for the given plug-in.
00186    *
00187    * @param name The name of the plug-in to retrieve the parameters of.
00188    * @return :ParameterDescriptionList The parameters of the plug-in.
00189    **/
00190   static const ParameterDescriptionList& getPluginParameters(const std::string& name);
00191 
00192   /**
00193    * @brief Gets the dependencies of a plug-in.
00194    *
00195    * @param name The name of the plug-in to retrieve the dependencies of.
00196    * @return :list< tlp::Dependency, std::allocator< tlp::Dependency > > The list of dependencies of the plug-in.
00197    **/
00198   static const std::list<tlp::Dependency>& getPluginDependencies(const std::string& name);
00199 
00200   /**
00201    * @brief Gets the library from which a plug-in has been loaded.
00202    *
00203    * @param name The name of the plug-in to retrieve the library of.
00204    * @return std::string The library from which the plug-in was loaded.
00205    **/
00206   static std::string getPluginLibrary(const std::string& name);
00207 
00208   /**
00209    * @brief Removes a plug-in from this factory.
00210    * This is usefull when a plug-in has unmet dependencies, or appears more than once.
00211    *
00212    * @param name The name of the plug-in to remove.
00213    * @return void
00214    **/
00215   static void removePlugin(const std::string& name);
00216 
00217   /**
00218    * @brief Registers a plugin into Tulip
00219    *
00220    * @warning This method should only be called by tlp::FactoryInterface subclasses
00221    * @see PLUGIN
00222    */
00223   static void registerPlugin(FactoryInterface* objectFactory);
00224 
00225 protected:
00226 
00227 
00228   void sendPluginAddedEvent(const std::string &pluginName);
00229   void sendPluginRemovedEvent(const std::string &pluginName);
00230 
00231   static PluginLister* _instance;
00232 
00233   /**
00234    * @brief Stores the factory, dependencies, and parameters of all the plugins that register into this factory.
00235    **/
00236   std::map<std::string , PluginDescription> _plugins;
00237 
00238   /**
00239    * @brief Gets the release number of the given plug-in.
00240    *
00241    * @param name The name of the plug-in to retrieve the version number of.
00242    * @return :string The version number, ussually formatted as X[.Y], where X is the major, and Y the minor.
00243    **/
00244   static std::string getPluginRelease(const std::string& name);
00245 };
00246 
00247 class TLP_SCOPE PluginEvent : public Event {
00248 public:
00249 
00250   enum PluginEventType {
00251     TLP_ADD_PLUGIN = 0,
00252     TLP_REMOVE_PLUGIN = 1
00253   };
00254 
00255   // constructor for node/edge events
00256   PluginEvent(PluginEventType pluginEvtType, const std::string& pluginName)
00257     : Event(*(tlp::PluginLister::instance()), Event::TLP_MODIFICATION),
00258       evtType(pluginEvtType), pluginName(pluginName) {}
00259 
00260   PluginEventType getType() const {
00261     return evtType;
00262   }
00263 
00264   std::string getPluginName() const {
00265     return pluginName;
00266   }
00267 
00268 protected:
00269 
00270   PluginEventType evtType;
00271   std::string pluginName;
00272 
00273 };
00274 
00275 }
00276 
00277 #endif //TULIP_PLUGINLISTER_H
 All Classes Files Functions Variables Enumerations Enumerator Properties