CTK/Libs/PluginFramework/ctkPlugin.h

/*=============================================================================

  Library: CTK

  Copyright (c) 2010 German Cancer Research Center,
    Division of Medical and Biological Informatics

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

=============================================================================*/

#ifndef CTKPLUGIN_H
#define CTKPLUGIN_H

#include "ctkPluginContext.h"

#include "ctkVersion.h"

namespace ctk {

  class PluginArchive;
  class PluginFrameworkContext;
  class PluginPrivate;

  /**
   * An installed plugin in the Framework.
   *
   * <p>
   * A <code>%Plugin</code> object is the access point to define the lifecycle of
   * an installed plugin. Each plugin installed in the plugin environment must have
   * an associated <code>%Plugin</code> object.
   *
   * <p>
   * A plugin must have a unique identity, a <code>long</code>, chosen by the
   * Framework. This identity must not change during the lifecycle of a plugin,
   * even when the plugin is updated. Uninstalling and then reinstalling the
   * plugin must create a new unique identity.
   *
   * <p>
   * A plugin can be in one of six states:
   * <ul>
   * <li>{@link #UNINSTALLED}
   * <li>{@link #INSTALLED}
   * <li>{@link #RESOLVED}
   * <li>{@link #STARTING}
   * <li>{@link #STOPPING}
   * <li>{@link #ACTIVE}
   * </ul>
   * <p>
   * They can be ORed together using the <code>States</code> type to
   * determine if a plugin is in one of the valid states.
   *
   * <p>
   * A plugin should only execute code when its state is one of
   * <code>STARTING</code>, <code>ACTIVE</code>, or <code>STOPPING</code>.
   * An <code>UNINSTALLED</code> plugin can not be set to another state; it is a
   * zombie and can only be reached because references are kept somewhere.
   *
   * <p>
   * The Framework is the only entity that is allowed to create
   * <code>%Plugin</code> objects, and these objects are only valid within the
   * Framework that created them.
   *
   * @threadsafe
   */
  class CTK_PLUGINFW_EXPORT Plugin {

    Q_DECLARE_PRIVATE(Plugin)

  public:

    enum State {
      /**
       * The plugin is uninstalled and may not be used.
       *
       * <p>
       * The <code>UNINSTALLED</code> state is only visible after a plugin is
       * uninstalled; the plugin is in an unusable state but references to the
       * <code>%Plugin</code> object may still be available and used for
       * introspection.
       */
      UNINSTALLED,

      /**
       * The plugin is installed but not yet resolved.
       *
       * <p>
       * A plugin is in the <code>INSTALLED</code> state when it has been
       * installed in the Framework but is not or cannot be resolved.
       * <p>
       * This state is visible if the plugin's code dependencies are not resolved.
       * The Framework may attempt to resolve an <code>INSTALLED</code> plugin's
       * code dependencies and move the plugin to the <code>RESOLVED</code>
       * state.
       */
      INSTALLED,

      /**
       * The plugin is resolved and is able to be started.
       *
       * <p>
       * A plugin is in the <code>RESOLVED</code> state when the Framework has
       * successfully resolved the plugin's code dependencies. These dependencies
       * include:
       * <ul>
       * <li>The plugin's required plugin dependencies from its
       * {@link PluginConstants::REQUIRE_PLUGIN} Manifest header.
       * </ul>
       * <p>
       * Note that the plugin is not active yet. A plugin must be put in the
       * <code>RESOLVED</code> state before it can be started. The Framework may
       * attempt to resolve a plugin at any time.
       */
      RESOLVED,

      /**
       * The plugin is in the process of starting.
       *
       * <p>
       * A plugin is in the <code>STARTING</code> state when its
       * {@link #start(const Options&) start} method is active. A plugin must be in this
       * state when the plugin's {@link PluginActivator::start} method is called. If the
       * <code>PluginActivator::start</code> method completes without exception,
       * then the plugin has successfully started and must move to the
       * <code>ACTIVE</code> state.
       * <p>
       * If the plugin does not have a
       * {@link PluginConstants#ACTIVATION_EAGER eager activation policy}, then the
       * plugin may remain in this state for some time until the activation is
       * triggered.
       */
      STARTING,

      /**
       * The plugin is in the process of stopping.
       *
       * <p>
       * A plugin is in the <code>STOPPING</code> state when its
       * {@link #stop(const Option&) stop} method is active. A plugin must be in this state
       * when the plugin's {@link PluginActivator::stop} method is called. When the
       * <code>PluginActivator::stop</code> method completes the plugin is
       * stopped and must move to the <code>RESOLVED</code> state.
       */
      STOPPING,

      /**
       * The plugin is now running.
       *
       * <p>
       * A plugin is in the <code>ACTIVE</code> state when it has been
       * successfully started and activated.
       */
      ACTIVE
    };

    /**
     * Represents an ORed combination of plugin states.
     *
     * @see #State
     */
    Q_DECLARE_FLAGS(States, State)

    enum StartOption {

      /**
       * The plugin start operation is transient and the persistent autostart
       * setting of the plugin is not modified.
       *
       * <p>
       * This option may be set when calling {@link #start(const StartOptions&)} to notify the
       * framework that the autostart setting of the plugin must not be modified.
       * If this option is not set, then the autostart setting of the plugin is
       * modified.
       *
       * @see #start(const StartOptions&)
       */
      START_TRANSIENT,

      /**
       * The plugin start operation must activate the plugin according to the
       * plugin's declared
       * {@link PluginConstants#PLUGIN_ACTIVATIONPOLICY activation policy}.
       *
       * <p>
       * This bit may be set when calling {@link #start(const StartOptions&)} to notify the
       * framework that the plugin must be activated using the plugin's declared
       * activation policy.
       *
       * @see PluginConstants#PLUGIN_ACTIVATIONPOLICY
       * @see #start(const StartOptions&)
       */
      START_ACTIVATION_POLICY

    };

    /**
     * Represents an ORed combination of start options.
     *
     * @see #StartOption
     */
    Q_DECLARE_FLAGS(StartOptions, StartOption)

    enum StopOption {
      /**
       * The plugin stop is transient and the persistent autostart setting of the
       * plugin is not modified.
       *
       * <p>
       * This option may be set when calling {@link #stop(const StopOptions&)} to notify the
       * framework that the autostart setting of the plugin must not be modified.
       * If this option is not set, then the autostart setting of the plugin is
       * modified.
       *
       * @see #stop(const StopOptions&)
       */
      STOP_TRANSIENT
    };

    /**
     * Represents an ORed combination of stop options.
     *
     * @see #StopOption
     */
    Q_DECLARE_FLAGS(StopOptions, StopOption)

    virtual ~Plugin();

    /**
     * Returns this plugin's current state.
     *
     * <p>
     * A plugin can be in only one state at any time.
     *
     * @return An element of <code>UNINSTALLED</code>,<code>INSTALLED</code>,
     *         <code>RESOLVED</code>,<code>STARTING</code>,
     *         <code>STOPPING</code>,<code>ACTIVE</code>.
     */
    State getState() const;

    /**
     * Starts this plugin.
     *
     * <p>
     * If this plugin's state is <code>UNINSTALLED</code> then an
     * <code>std::logic_error</code> is thrown.
     * <p>
     * The following steps are required to start this bundle:
     * <ol>
     * <li>If this plugin is in the process of being activated or deactivated
     * then this method must wait for activation or deactivation to complete
     * before continuing. If this does not occur in a reasonable time, a
     * <code>PluginException</code> is thrown to indicate this plugin was unable
     * to be started.
     *
     * <li>If this plugin's state is <code>ACTIVE</code> then this method
     * returns immediately.
     *
     * <li>If the {@link #START_TRANSIENT} option is not set then set this
     * plugin's autostart setting to <em>Started with declared activation</em>
     * if the {@link #START_ACTIVATION_POLICY} option is set or
     * <em>Started with lazy activation</em> if not set. When the Framework is
     * restarted and this plugin's autostart setting is not <em>Stopped</em>,
     * this plugin must be automatically started.
     *
     * <li>If this plugin's state is not <code>RESOLVED</code>, an attempt is
     * made to resolve this plugin. If the Framework cannot resolve this plugin,
     * a <code>PluginException</code> is thrown.
     *
     * <li>If the {@link #START_ACTIVATION_POLICY} option is not set then:
     * <ul>
     * <li>If this plugin's state is <code>STARTING</code> then this method
     * returns immediately.
     * <li>This plugin's state is set to <code>STARTING</code>.
     * <li>A plugin event of type {@link PluginEvent::LAZY_ACTIVATION} is fired.
     * <li>This method returns immediately and the remaining steps will be
     * followed when this plugin's activation is later triggered.
     * </ul>
     * If the {@link #START_ACTIVATION_POLICY} option is set and this
     * plugin's declared activation policy is {@link PluginConstants#ACTIVATION_EAGER
     * eager} then:
     * <i></i>
     * <li>This plugin's state is set to <code>STARTING</code>.
     *
     * <li>A plugin event of type {@link PluginEvent::STARTING} is fired.
     *
     * <li>The {@link PluginActivator::start} method of this plugin's
     * <code>PluginActivator</code>, is called. If the
     * <code>PluginActivator</code> throws an exception then:
     * <ul>
     * <li>This plugin's state is set to <code>STOPPING</code>.
     * <li>A plugin event of type {@link PluginEvent::STOPPING} is fired.
     * <li>Any services registered by this plugin must be unregistered.
     * <li>Any services used by this plugin must be released.
     * <li>Any listeners registered by this plugin must be removed.
     * <li>This plugin's state is set to <code>RESOLVED</code>.
     * <li>A plugin event of type {@link PluginEvent::STOPPED} is fired.
     * <li>A <code>PluginException</code> is then thrown.
     * </ul>
     * <i></i>
     * <li>If this plugin's state is <code>UNINSTALLED</code>, because this
     * plugin was uninstalled while the <code>PluginActivator::start</code>
     * method was running, a <code>PluginException</code> is thrown.
     *
     * <li>This plugin's state is set to <code>ACTIVE</code>.
     *
     * <li>A plugin event of type {@link PluginEvent::STARTED} is fired.
     * </ol>
     *
     * <b>Preconditions </b>
     * <ul>
     * <li><code>getState()</code> in { <code>INSTALLED</code>,
     * <code>RESOLVED</code>, <code>STARTING</code> }
     * or { <code>INSTALLED</code>, <code>RESOLVED</code> }
     * if this plugin has a eager activation policy.
     * </ul>
     * <b>Postconditions, no exceptions thrown </b>
     * <ul>
     * <li>%Plugin autostart setting is modified unless the
     * {@link #START_TRANSIENT} option was set.
     * <li><code>getState()</code> in { <code>ACTIVE</code> }
     * if the eager activation policy was used.
     * <li><code>PluginActivator::start()</code> has been called and did not
     * throw an exception if the eager policy was used.
     * </ul>
     * <b>Postconditions, when an exception is thrown </b>
     * <ul>
     * <li>Depending on when the exception occurred, plugin autostart setting is
     * modified unless the {@link #START_TRANSIENT} option was set.
     * <li><code>getState()</code> not in { <code>STARTING</code>,
     * <code>ACTIVE</code> }.
     * </ul>
     *
     * @param options The options for starting this plugin. See
     *        {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}. The
     *        Framework must ignore unrecognized options.
     * @throws PluginException If this plugin could not be started. This could
     *         be because a code dependency could not be resolved or the
     *         <code>PluginActivator</code> could not be loaded or
     *         threw an exception.
     * @throws std::logic_error If this plugin has been uninstalled or this
     *         plugin tries to change its own state.
     */
    virtual void start(const StartOptions& options = 0);

    /**
     * Stops this plugin.
     *
     * <p>
     * The following steps are required to stop a plugin:
     * <ol>
     * <li>If this plugin's state is <code>UNINSTALLED</code> then an
     * <code>std::logic_error</code> is thrown.
     *
     * <li>If this plugin is in the process of being activated or deactivated
     * then this method must wait for activation or deactivation to complete
     * before continuing. If this does not occur in a reasonable time, a
     * <code>PluginException</code> is thrown to indicate this plugin was unable
     * to be stopped.
     * <li>If the {@link #STOP_TRANSIENT} option is not set then then set this
     * plugin's persistent autostart setting to <em>Stopped</em>. When the
     * Framework is restarted and this plugin's autostart setting is
     * <em>Stopped</em>, this bundle must not be automatically started.
     *
     * <li>If this plugin's state is not <code>STARTING</code> or
     * <code>ACTIVE</code> then this method returns immediately.
     *
     * <li>This plugin's state is set to <code>STOPPING</code>.
     *
     * <li>A plugin event of type {@link PluginEvent::STOPPING} is fired.
     *
     * <li>If this plugin's state was <code>ACTIVE</code> prior to setting the
     * state to <code>STOPPING</code>, the {@link PluginActivator#stop} method
     * of this plugin's <code>PluginActivator</code> is
     * called. If that method throws an exception, this method must continue to
     * stop this plugin and a <code>PluginException</code> must be thrown after
     * completion of the remaining steps.
     *
     * <li>Any services registered by this plugin must be unregistered.
     * <li>Any services used by this plugin must be released.
     * <li>Any listeners registered by this plugin must be removed.
     *
     * <li>If this plugin's state is <code>UNINSTALLED</code>, because this
     * plugin was uninstalled while the <code>PluginActivator::stop</code> method
     * was running, a <code>PluginException</code> must be thrown.
     *
     * <li>This plugin's state is set to <code>RESOLVED</code>.
     *
     * <li>A plugin event of type {@link PluginEvent::STOPPED} is fired.
     * </ol>
     *
     * <b>Preconditions </b>
     * <ul>
     * <li><code>getState()</code> in { <code>ACTIVE</code> }.
     * </ul>
     * <b>Postconditions, no exceptions thrown </b>
     * <ul>
     * <li>Plugin autostart setting is modified unless the
     * {@link #STOP_TRANSIENT} option was set.
     * <li><code>getState()</code> not in &#x007B; <code>ACTIVE</code>,
     * <code>STOPPING</code> &#x007D;.
     * <li><code>PluginActivator::stop</code> has been called and did not throw
     * an exception.
     * </ul>
     * <b>Postconditions, when an exception is thrown </b>
     * <ul>
     * <li>Plugin autostart setting is modified unless the
     * {@link #STOP_TRANSIENT} option was set.
     * </ul>
     *
     * @param options The options for stoping this bundle. See
     *        {@link #STOP_TRANSIENT}.
     * @throws PluginException If this plugin's <code>PluginActivator</code>
     *         threw an exception.
     * @throws std::logic_error If this plugin has been uninstalled or this
     *         plugin tries to change its own state.
     */
    virtual void stop(const StopOptions& options = 0);

    /**
     * Returns this plugin's {@link PluginContext}. The returned
     * <code>PluginContext</code> can be used by the caller to act on behalf
     * of this plugin.
     *
     * <p>
     * If this plugin is not in the {@link #STARTING}, {@link #ACTIVE}, or
     * {@link #STOPPING} states, then this
     * plugin has no valid <code>PluginContext</code>. This method will
     * return <code>0</code> if this plugin has no valid
     * <code>PluginContext</code>.
     *
     * @return A <code>PluginContext</code> for this plugin or
     *         <code>0</code> if this plugin has no valid
     *         <code>PluginContext</code>.
     */
    PluginContext* getPluginContext() const;

    /**
     * Returns this plugin's unique identifier. This plugin is assigned a unique
     * identifier by the Framework when it was installed in the plugin
     * environment.
     *
     * <p>
     * A plugin's unique identifier has the following attributes:
     * <ul>
     * <li>Is unique and persistent.
     * <li>Is a <code>long</code>.
     * <li>Its value is not reused for another plugin, even after a plugin is
     * uninstalled.
     * <li>Does not change while a plugin remains installed.
     * <li>Does not change when a plugin is updated.
     * </ul>
     *
     * <p>
     * This method must continue to return this plugin's unique identifier while
     * this plugin is in the <code>UNINSTALLED</code> state.
     *
     * @return The unique identifier of this plugin.
     */
    long getPluginId() const;

    /**
     * Returns this plugin's location identifier.
     *
     * <p>
     * The location identifier is the location passed to
     * <code>PluginContext::installPlugin</code> when a plugin is installed.
     * The location identifier does not change while this plugin remains
     * installed, even if this plugin is updated.
     *
     * <p>
     * This method must continue to return this plugin's location identifier
     * while this plugin is in the <code>UNINSTALLED</code> state.
     *
     * @return The string representation of this plugin's location identifier.
     */
    QString getLocation() const;

    /**
     * Returns this plugin's Manifest headers and values. This method returns
     * all the Manifest headers and values from the main section of this
     * bundle's Manifest file; that is, all lines prior to the first named section.
     *
     * TODO: documentation about manifest value internationalization
     *
     * <p>
     * For example, the following Manifest headers and values are included if
     * they are present in the Manifest file:
     *
     * <pre>
     *     Plugin-Name
     *     Plugin-Vendor
     *     Plugin-Version
     *     Plugin-Description
     *     Plugin-DocURL
     *     Plugin-ContactAddress
     * </pre>
     *
     * <p>
     * This method must continue to return Manifest header information while
     * this plugin is in the <code>UNINSTALLED</code> state.
     *
     * @return A <code>QHash<Qstring, QString></code> object containing this plugin's
     *         Manifest headers and values.
     */
    virtual QHash<QString, QString> getHeaders();

    /**
     * Returns the symbolic name of this plugin as specified by its
     * <code>Plugin-SymbolicName</code> manifest header. The plugin symbolic
     * name together with a version must identify a unique plugin. The plugin
     * symbolic name should be based on the reverse domain name naming
     * convention like that used for java packages.
     *
     * <p>
     * This method must continue to return this plugin's symbolic name while
     * this plugin is in the <code>UNINSTALLED</code> state.
     *
     * @return The symbolic name of this plugin or a null QString if this
     *         plugin does not have a symbolic name.
     */
    QString getSymbolicName() const;

    /**
     * Returns a list of all the files and directories
     * within this plugin whose longest sub-path matches the
     * specified path.
     * <p>
     * The specified path is always relative to the root of this plugin
     * (the plugins symbolic name) and may begin with a &quot;/&quot;.
     * A path value of &quot;/&quot; indicates the root of this plugin.
     * <p>
     * Returned paths indicating subdirectory paths end with a &quot;/&quot;.
     * The returned paths are all relative to the root of this plugin and must
     * not begin with &quot;/&quot;.
     * <p>
     *
     * @param path The path name for which to return resource paths.
     * @return A list of the resource paths (<code>QString</code>
     *         objects) or an empty list if no entry could be found.

     * @throws std::logic_error If this plugin has been
     *         uninstalled.
     */
    virtual QStringList getResourceList(const QString& path) const;

    /**
     * Returns a QByteArray containing a Qt resource located at the
     * specified path in this plugin.
     * <p>
     * The specified path is always relative to the root of this plugin
     * (the plugins symbolic name) and may
     * begin with &quot;/&quot;. A path value of &quot;/&quot; indicates the
     * root of this plugin.
     * <p>
     *
     * @param path The path name of the resource.
     * @return A QString to the resource, or a null QString if no resource could be
     *         found.
     * @throws std::logic_error If this plugin has been
     *         uninstalled.
     */
    virtual QByteArray getResource(const QString& path) const;

    /**
     * Returns the version of this plugin as specified by its
     * <code>Plugin-Version</code> manifest header. If this plugin does not have a
     * specified version then {@link Version#emptyVersion} is returned.
     *
     * <p>
     * This method must continue to return this plugin's version while
     * this plugin is in the <code>UNINSTALLED</code> state.
     *
     * @return The version of this plugin.
     */
    Version getVersion() const;

  protected:

    friend class PluginFramework;
    friend class PluginFrameworkContext;
    friend class Plugins;

    PluginPrivate * const d_ptr;

    Plugin(PluginFrameworkContext* fw, PluginArchive* ba);
    Plugin(PluginPrivate& dd);
  };

}

Q_DECLARE_OPERATORS_FOR_FLAGS(ctk::Plugin::States)

#endif // CTKPLUGIN_H