ground/gcs/src/libs/extensionsystem/iplugin.cpp

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       iplugin.cpp
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
   6  *             Parts by Nokia Corporation (qt-info@nokia.com) Copyright (C) 2009.
   7  * @brief
   8  * @see        The GNU Public License (GPL) Version 3
   9  * @defgroup
  10  * @{
  11  *
  12  *****************************************************************************/
  13 /*
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 3 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * This program is distributed in the hope that it will be useful, but
  20  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  22  * for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License along
  25  * with this program; if not, write to the Free Software Foundation, Inc.,
  26  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  27  */
  28
  29 #include "iplugin.h"
  30 #include "iplugin_p.h"
  31 #include "pluginmanager.h"
  32 #include "pluginspec.h"
  33
  34 /*!
  35     \class ExtensionSystem::IPlugin
  36     \mainclass
  37     \brief Base class for all plugins.
  38
  39     The IPlugin class is an abstract class that must be implemented
  40     once for each plugin.
  41     A plugin consists of two parts: A description file, and a library
  42     that at least contains the IPlugin implementation.
  43
  44     \tableofcontents
  45
  46     \section1 Plugin Specification
  47     The plugin specification file is an xml file that contains all
  48     information that are necessary for loading the plugin's library,
  49     plus some textual descriptions. The file must be located in
  50     (a subdir of) one of the plugin manager's plugin search paths,
  51     and must have the \c .xml extension.
  52
  53     \section2 Main Tag
  54     The root tag is \c plugin. It has mandatory attributes \c name
  55     and \c version, and an optional \c compatVersion.
  56     \table
  57     \header
  58         \o Tag
  59         \o Meaning
  60     \row
  61         \o plugin
  62         \o Root element in a plugin's xml file.
  63     \endtable
  64     \table
  65     \header
  66         \o Attribute
  67         \o Meaning
  68     \row
  69         \o name
  70         \o This is used as an identifier for the plugin and can e.g.
  71            be referenced in other plugin's dependencies. It is
  72            also used to construct the name of the plugin library
  73            as \c lib[name].[dll|.so|.dylib].
  74     \row
  75         \o version
  76         \o Version string in the form \c {"x.y.z_n"}, used for identifying
  77            the plugin.
  78     \row
  79         \o compatVersion
  80         \o Compatibility version. Optional. If not given, it is implicitly
  81            set to the same value as \c version. The compatibility version
  82            is used to resolve dependencies on this plugin. See
  83            \l {Dependencies}{Dependencies} for details.
  84     \endtable
  85
  86     \section2 Plugin-describing Tags
  87     These are direct children of the \c plugin tag, and are solely used
  88     for more detailed (user centric) description of the plugin. All of these
  89     are optional.
  90     \table
  91     \header
  92         \o Tag
  93         \o Meaning
  94     \row
  95         \o vendor
  96         \o String that describes the plugin creator/vendor,
  97            like \c {MyCompany}.
  98     \row
  99         \o copyright
 100         \o A short copyright notice, like \c {(C) 2007-2008 MyCompany}.
 101     \row
 102         \o license
 103         \o Possibly multi-line license information about the plugin.
 104     \row
 105         \o description
 106         \o Possibly multi-line description of what the plugin is supposed
 107            to provide.
 108     \row
 109         \o url
 110         \o Link to further information about the plugin, like
 111            \c {http://www.mycompany-online.com/products/greatplugin}.
 112     \endtable
 113
 114     \section2 Dependencies
 115     A plugin can have dependencies on other plugins. These are
 116     specified in the plugin's xml file as well, to ensure that
 117     these other plugins are loaded before this plugin.
 118     Dependency information consists of the name of the required plugin
 119     (lets denote that as \c {dependencyName}),
 120     and the required version of the plugin (\c {dependencyVersion}).
 121     A plugin with given \c name, \c version and \c compatVersion matches
 122     the dependency if
 123     \list
 124         \o its \c name matches \c dependencyName, and
 125         \o \c {compatVersion <= dependencyVersion <= version}.
 126     \endlist
 127
 128     The xml element that describes dependencies is the \c dependency tag,
 129     with required attributes \c name and \c version. It is an
 130     optional direct child of the \c plugin tag and can appear multiple times.
 131     \table
 132     \header
 133         \o Tag
 134         \o Meaning
 135     \row
 136         \o dependency
 137         \o Describes a dependency on another plugin.
 138     \endtable
 139     \table
 140     \header
 141         \o Attribute
 142         \o Meaning
 143     \row
 144         \o name
 145         \o The name of the plugin, on which this plugin relies.
 146     \row
 147         \o version
 148         \o The version to which the plugin must be compatible to
 149            fill the dependency, in the form \c {"x.y.z_n"}.
 150     \endtable
 151
 152     \section2 Example \c plugin.xml
 153     \code
 154         <plugin name="test" version="1.0.1" compatVersion="1.0.0">
 155             <vendor>MyCompany</vendor>
 156             <copyright>(C) 2007 MyCompany</copyright>
 157             <license>
 158         This is a default license bla
 159         blubbblubb
 160         end of terms
 161             </license>
 162             <description>
 163         This plugin is just a test.
 164             it demonstrates the great use of the plugin spec.
 165             </description>
 166             <url>http://www.mycompany-online.com/products/greatplugin</url>
 167             <dependencyList>
 168                 <dependency name="SomeOtherPlugin" version="2.3.0_2"/>
 169                 <dependency name="EvenOther" version="1.0.0"/>
 170             </dependencyList>
 171         </plugin>
 172     \endcode
 173     The first dependency could for example be matched by a plugin with
 174     \code
 175         <plugin name="SomeOtherPlugin" version="3.1.0" compatVersion="2.2.0">
 176         </plugin>
 177     \endcode
 178     since the name matches, and the version \c "2.3.0_2" given in the dependency tag
 179     lies in the range of \c "2.2.0" and \c "3.1.0".
 180
 181     \section2 A Note on Plugin Versions
 182     Plugin versions are in the form \c "x.y.z_n" where, x, y, z and n are
 183     non-negative integer numbers. You don't have to specify the version
 184     in this full form - any left-out part will implicitly be set to zero.
 185     So, \c "2.10_2" is equal to \c "2.10.0_2", and "1" is the same as "1.0.0_0".
 186
 187     \section1 Plugin Implementation
 188     Plugins must provide one implementation of the IPlugin class, located
 189     in a library that matches the \c name attribute given in their
 190     xml description. The IPlugin implementation must be exported and
 191     made known to Qt's plugin system via the Q_EXPORT_PLUGIN macro, see the
 192     Qt documentation for details on that.
 193
 194     After the plugins' xml files have been read, and dependencies have been
 195     found, the plugin loading is done in three phases:
 196     \list 1
 197     \o All plugin libraries are loaded in 'root-to-leaf' order of the
 198        dependency tree.
 199     \o All plugins' initialize methods are called in 'root-to-leaf' order
 200        of the dependency tree. This is a good place to put
 201        objects in the plugin manager's object pool.
 202     \o All plugins' extensionsInitialized methods are called in 'leaf-to-root'
 203        order of the dependency tree. At this point, plugins can
 204        be sure that all plugins that depend on this plugin have
 205        been initialized completely (implying that they have put
 206        objects in the object pool, if they want that during the
 207        initialization sequence).
 208     \endlist
 209     If library loading or initialization of a plugin fails, all plugins
 210     that depend on that plugin also fail.
 211
 212     Plugins have access to the plugin manager
 213     (and its object pool) via the PluginManager::instance()
 214     method.
 215  */
 216
 217 /*!
 218     \fn bool IPlugin::initialize(const QStringList &arguments, QString *errorString)
 219     Called after the plugin has been loaded and the IPlugin instance
 220     has been created. The initialize methods of plugins that depend
 221     on this plugin are called after the initialize method of this plugin
 222     has been called. Plugins should initialize their internal state in this
 223     method. Returns if initialization of successful. If it wasn't successful,
 224     the \a errorString should be set to a user-readable message
 225     describing the reason.
 226     \sa extensionsInitialized()
 227  */
 228
 229 /*!
 230     \fn void IPlugin::extensionsInitialized()
 231     Called after the IPlugin::initialize() method has been called,
 232     and after both the IPlugin::initialize() and IPlugin::extensionsInitialized()
 233     methods of plugins that depend on this plugin have been called.
 234     In this method, the plugin can assume that plugins that depend on
 235     this plugin are fully 'up and running'. It is a good place to
 236     look in the plugin manager's object pool for objects that have
 237     been provided by dependent plugins.
 238     \sa initialize()
 239  */
 240
 241 /*!
 242     \fn void IPlugin::shutdown()
 243     Called during a shutdown sequence in the same order as initialization
 244     before the plugins get deleted in reverse order.
 245     This method can be used to optimize the shutdown down, e.g. to
 246     disconnect from the PluginManager::aboutToRemoveObject() signal
 247     if getting the signal (and probably doing lots of stuff to update
 248     the internal and visible state) doesn't make sense during shutdown.
 249  */
 250
 251 using namespace ExtensionSystem;
 252
 253 /*!
 254     \fn IPlugin::IPlugin()
 255     \internal
 256  */
 257 IPlugin::IPlugin()
 258     : d(new Internal::IPluginPrivate())
 259 {}
 260
 261 /*!
 262     \fn IPlugin::~IPlugin()
 263     \internal
 264  */
 265 IPlugin::~IPlugin()
 266 {
 267     PluginManager *pm = PluginManager::instance();
 268
 269     foreach(QObject * obj, d->addedObjectsInReverseOrder)
 270     pm->removeObject(obj);
 271     qDeleteAll(d->addedObjectsInReverseOrder);
 272     d->addedObjectsInReverseOrder.clear();
 273     delete d;
 274     d = 0;
 275 }
 276
 277 /*!
 278     \fn PluginSpec *IPlugin::pluginSpec() const
 279     Returns the PluginSpec corresponding to this plugin.
 280     This is not available in the constructor.
 281  */
 282 PluginSpec *IPlugin::pluginSpec() const
 283 {
 284     return d->pluginSpec;
 285 }
 286
 287 /*!
 288     \fn void IPlugin::addObject(QObject *obj)
 289     Convenience method that registers \a obj in the plugin manager's
 290     plugin pool by just calling PluginManager::addObject().
 291  */
 292 void IPlugin::addObject(QObject *obj)
 293 {
 294     PluginManager::instance()->addObject(obj);
 295 }
 296
 297 /*!
 298     \fn void IPlugin::addAutoReleasedObject(QObject *obj)
 299     Convenience method for registering \a obj in the plugin manager's
 300     plugin pool. Usually, registered objects must be removed from
 301     the object pool and deleted by hand.
 302     Objects added to the pool via addAutoReleasedObject are automatically
 303     removed and deleted in reverse order of registration when
 304     the IPlugin instance is destroyed.
 305     \sa PluginManager::addObject()
 306  */
 307 void IPlugin::addAutoReleasedObject(QObject *obj)
 308 {
 309     d->addedObjectsInReverseOrder.prepend(obj);
 310     PluginManager::instance()->addObject(obj);
 311 }
 312
 313 /*!
 314     \fn void IPlugin::removeObject(QObject *obj)
 315     Convenience method that unregisters \a obj from the plugin manager's
 316     plugin pool by just calling PluginManager::removeObject().
 317  */
 318 void IPlugin::removeObject(QObject *obj)
 319 {
 320     PluginManager::instance()->removeObject(obj);
 321 }