ctkPlugin Class Reference

#include <Libs/PluginFramework/ctkPlugin.h>

Inheritance diagram for ctkPlugin:
Inheritance graph
[legend]

List of all members.

Public Types

enum  StartOption { START_TRANSIENT, START_ACTIVATION_POLICY }
enum  State {
  UNINSTALLED, INSTALLED, RESOLVED, STARTING,
  STOPPING, ACTIVE
}
enum  StopOption { STOP_TRANSIENT }

Public Member Functions

virtual QHash< QString, QString > getHeaders ()
QString getLocation () const
ctkPluginContextgetPluginContext () const
long getPluginId () const
virtual QByteArray getResource (const QString &path) const
virtual QStringList getResourceList (const QString &path) const
State getState () const
QString getSymbolicName () const
ctkVersion getVersion () const
virtual void start (const StartOptions &options=START_ACTIVATION_POLICY)
virtual void stop (const StopOptions &options=0)
virtual ~ctkPlugin ()

Protected Member Functions

 ctkPlugin (ctkPluginPrivate &dd)
 ctkPlugin (ctkPluginFrameworkContext *fw, ctkPluginArchive *ba)

Protected Attributes

ctkPluginPrivate *const d_ptr

Friends

class ctkPluginFramework
class ctkPluginFrameworkContext
class ctkPlugins
class ctkServiceReferencePrivate

Detailed Description

An installed plugin in the Framework.

A ctkPlugin object is the access point to define the lifecycle of an installed plugin. Each plugin installed in the plugin environment must have an associated ctkPlugin object.

A plugin must have a unique identity, a long, 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.

A plugin can be in one of six states:

They can be ORed together using the States type to determine if a plugin is in one of the valid states.

A plugin should only execute code when its state is one of STARTING, ACTIVE, or STOPPING. An UNINSTALLED plugin can not be set to another state; it is a zombie and can only be reached because references are kept somewhere.

The Framework is the only entity that is allowed to create ctkPlugin objects, and these objects are only valid within the Framework that created them.

Definition at line 74 of file ctkPlugin.h.


Member Enumeration Documentation

Represents an ORed combination of plugin states.

See also:
State
Enumerator:
START_TRANSIENT 

The plugin start operation is transient and the persistent autostart setting of the plugin is not modified.

This option may be set when calling 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 also:
start(const StartOptions&)
START_ACTIVATION_POLICY 

The plugin start operation must activate the plugin according to the plugin's declared activation policy.

This bit may be set when calling start(const StartOptions&) to notify the framework that the plugin must be activated using the plugin's declared activation policy.

See also:
PluginConstants::PLUGIN_ACTIVATIONPOLICY
start(const StartOptions&)

Definition at line 171 of file ctkPlugin.h.

Enumerator:
UNINSTALLED 

The plugin is uninstalled and may not be used.

The UNINSTALLED state is only visible after a plugin is uninstalled; the plugin is in an unusable state but references to the ctkPlugin object may still be available and used for introspection.

INSTALLED 

The plugin is installed but not yet resolved.

A plugin is in the INSTALLED state when it has been installed in the Framework but is not or cannot be resolved.

This state is visible if the plugin's code dependencies are not resolved. The Framework may attempt to resolve an INSTALLED plugin's code dependencies and move the plugin to the RESOLVED state.

RESOLVED 

The plugin is resolved and is able to be started.

A plugin is in the RESOLVED state when the Framework has successfully resolved the plugin's code dependencies. These dependencies include:

Note that the plugin is not active yet. A plugin must be put in the RESOLVED state before it can be started. The Framework may attempt to resolve a plugin at any time.

STARTING 

The plugin is in the process of starting.

A plugin is in the STARTING state when its start method is active. A plugin must be in this state when the plugin's ctkPluginActivator::start method is called. If the ctkPluginActivator::start method completes without exception, then the plugin has successfully started and must move to the ACTIVE state.

If the plugin does not have a eager activation policy, then the plugin may remain in this state for some time until the activation is triggered.

STOPPING 

The plugin is in the process of stopping.

A plugin is in the STOPPING state when its stop method is active. A plugin must be in this state when the plugin's ctkPluginActivator::stop method is called. When the ctkPluginActivator::stop method completes the plugin is stopped and must move to the RESOLVED state.

ACTIVE 

The plugin is now running.

A plugin is in the ACTIVE state when it has been successfully started and activated.

Definition at line 80 of file ctkPlugin.h.

Represents an ORed combination of start options.

See also:
StartOption
Enumerator:
STOP_TRANSIENT 

The plugin stop is transient and the persistent autostart setting of the plugin is not modified.

This option may be set when calling 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 also:
stop(const StopOptions&)

Definition at line 211 of file ctkPlugin.h.


Constructor & Destructor Documentation

ctkPlugin::~ctkPlugin (  )  [virtual]

Represents an ORed combination of stop options.

See also:
StopOption

Definition at line 44 of file ctkPlugin.cpp.

ctkPlugin::ctkPlugin ( ctkPluginFrameworkContext *  fw,
ctkPluginArchive *  ba 
) [protected]

Definition at line 31 of file ctkPlugin.cpp.

ctkPlugin::ctkPlugin ( ctkPluginPrivate &  dd  )  [protected]

Definition at line 38 of file ctkPlugin.cpp.


Member Function Documentation

QHash< QString, QString > ctkPlugin::getHeaders (  )  [virtual]

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

For example, the following Manifest headers and values are included if they are present in the Manifest file:

     Plugin-Name
     Plugin-Vendor
     Plugin-ctkVersion
     Plugin-Description
     Plugin-DocURL
     Plugin-ContactAddress
 

This method must continue to return Manifest header information while this plugin is in the UNINSTALLED state.

Returns:
A QHash<Qstring, QString> object containing this plugin's Manifest headers and values.

Reimplemented in ctkPluginFramework.

Definition at line 137 of file ctkPlugin.cpp.

QString ctkPlugin::getLocation (  )  const

Returns this plugin's location identifier.

The location identifier is the location passed to ctkPluginContext::installPlugin when a plugin is installed. The location identifier does not change while this plugin remains installed, even if this plugin is updated.

This method must continue to return this plugin's location identifier while this plugin is in the UNINSTALLED state.

Returns:
The string representation of this plugin's location identifier.

Definition at line 130 of file ctkPlugin.cpp.

ctkPluginContext * ctkPlugin::getPluginContext (  )  const

Returns this plugin's ctkPluginContext. The returned ctkPluginContext can be used by the caller to act on behalf of this plugin.

If this plugin is not in the STARTING, ACTIVE, or STOPPING states, then this plugin has no valid ctkPluginContext. This method will return 0 if this plugin has no valid ctkPluginContext.

Returns:
A ctkPluginContext for this plugin or 0 if this plugin has no valid ctkPluginContext.

Definition at line 117 of file ctkPlugin.cpp.

long ctkPlugin::getPluginId (  )  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.

A plugin's unique identifier has the following attributes:

  • Is unique and persistent.
  • Is a long.
  • Its value is not reused for another plugin, even after a plugin is uninstalled.
  • Does not change while a plugin remains installed.
  • Does not change when a plugin is updated.

This method must continue to return this plugin's unique identifier while this plugin is in the UNINSTALLED state.

Returns:
The unique identifier of this plugin.

Definition at line 124 of file ctkPlugin.cpp.

QByteArray ctkPlugin::getResource ( const QString &  path  )  const [virtual]

Returns a QByteArray containing a Qt resource located at the specified path in this plugin.

The specified path is always relative to the root of this plugin (the plugins symbolic name) and may begin with "/". A path value of "/" indicates the root of this plugin.

Parameters:
path The path name of the resource.
Returns:
A QString to the resource, or a null QString if no resource could be found.
Exceptions:
std::logic_error If this plugin has been uninstalled.

Reimplemented in ctkPluginFramework.

Definition at line 167 of file ctkPlugin.cpp.

QStringList ctkPlugin::getResourceList ( const QString &  path  )  const [virtual]

Returns a list of all the files and directories within this plugin whose longest sub-path matches the specified path.

The specified path is always relative to the root of this plugin (the plugins symbolic name) and may begin with a "/". A path value of "/" indicates the root of this plugin.

Returned paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of this plugin and must not begin with "/".

Parameters:
path The path name for which to return resource paths.
Returns:
A list of the resource paths (QString objects) or an empty list if no entry could be found.
Exceptions:
std::logic_error If this plugin has been uninstalled.

Reimplemented in ctkPluginFramework.

Definition at line 161 of file ctkPlugin.cpp.

ctkPlugin::State ctkPlugin::getState (  )  const

Returns this plugin's current state.

A plugin can be in only one state at any time.

Returns:
An element of UNINSTALLED,INSTALLED, RESOLVED,STARTING, STOPPING,ACTIVE.

Definition at line 49 of file ctkPlugin.cpp.

QString ctkPlugin::getSymbolicName (  )  const

Returns the symbolic name of this plugin as specified by its Plugin-SymbolicName 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.

This method must continue to return this plugin's symbolic name while this plugin is in the UNINSTALLED state.

Returns:
The symbolic name of this plugin or a null QString if this plugin does not have a symbolic name.

Definition at line 155 of file ctkPlugin.cpp.

ctkVersion ctkPlugin::getVersion (  )  const

Returns the version of this plugin as specified by its Plugin-Version manifest header. If this plugin does not have a specified version then Version#emptyVersion is returned.

This method must continue to return this plugin's version while this plugin is in the UNINSTALLED state.

Returns:
The version of this plugin.

Definition at line 173 of file ctkPlugin.cpp.

void ctkPlugin::start ( const StartOptions &  options = START_ACTIVATION_POLICY  )  [virtual]

Starts this plugin.

If this plugin's state is UNINSTALLED then an std::logic_error is thrown.

The following steps are required to start this bundle:

  1. 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 ctkPluginException is thrown to indicate this plugin was unable to be started.

  2. If this plugin's state is ACTIVE then this method returns immediately.

  3. If the START_TRANSIENT option is not set then set this plugin's autostart setting to Started with declared activation if the START_ACTIVATION_POLICY option is set or Started with lazy activation if not set. When the Framework is restarted and this plugin's autostart setting is not Stopped, this plugin must be automatically started.

  4. If this plugin's state is not RESOLVED, an attempt is made to resolve this plugin. If the Framework cannot resolve this plugin, a ctkPluginException is thrown.

  5. If the START_ACTIVATION_POLICY option is not set then:
    • If this plugin's state is STARTING then this method returns immediately.
    • This plugin's state is set to STARTING.
    • A plugin event of type ctkPluginEvent::LAZY_ACTIVATION is fired.
    • This method returns immediately and the remaining steps will be followed when this plugin's activation is later triggered.
    If the START_ACTIVATION_POLICY option is set and this plugin's declared activation policy is eager then:
  6. This plugin's state is set to STARTING.

  7. A plugin event of type ctkPluginEvent::STARTING is fired.

  8. The ctkPluginActivator::start method of this plugin's ctkPluginActivator, is called. If the ctkPluginActivator throws an exception then:
    • This plugin's state is set to STOPPING.
    • A plugin event of type ctkPluginEvent::STOPPING is fired.
    • Any services registered by this plugin must be unregistered.
    • Any services used by this plugin must be released.
    • Any listeners registered by this plugin must be removed.
    • This plugin's state is set to RESOLVED.
    • A plugin event of type ctkPluginEvent::STOPPED is fired.
    • A ctkPluginException is then thrown.
  9. If this plugin's state is UNINSTALLED, because this plugin was uninstalled while the ctkPluginActivator::start method was running, a ctkPluginException is thrown.

  10. This plugin's state is set to ACTIVE.

  11. A plugin event of type ctkPluginEvent::STARTED is fired.

Preconditions

  • getState() in { INSTALLED, RESOLVED, STARTING } or { INSTALLED, RESOLVED } if this plugin has a eager activation policy.

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

  • Depending on when the exception occurred, plugin autostart setting is modified unless the START_TRANSIENT option was set.
  • getState() not in { STARTING, ACTIVE }.
Parameters:
options The options for starting this plugin. See START_TRANSIENT and START_ACTIVATION_POLICY. The Framework must ignore unrecognized options.
Exceptions:
ctkPluginException If this plugin could not be started. This could be because a code dependency could not be resolved or the ctkPluginActivator could not be loaded or threw an exception.
std::logic_error If this plugin has been uninstalled or this plugin tries to change its own state.

Definition at line 55 of file ctkPlugin.cpp.

void ctkPlugin::stop ( const StopOptions &  options = 0  )  [virtual]

Stops this plugin.

The following steps are required to stop a plugin:

  1. If this plugin's state is UNINSTALLED then an std::logic_error is thrown.

  2. 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 ctkPluginException is thrown to indicate this plugin was unable to be stopped.
  3. If the STOP_TRANSIENT option is not set then then set this plugin's persistent autostart setting to Stopped. When the Framework is restarted and this plugin's autostart setting is Stopped, this bundle must not be automatically started.

  4. If this plugin's state is not STARTING or ACTIVE then this method returns immediately.

  5. This plugin's state is set to STOPPING.

  6. A plugin event of type ctkPluginEvent::STOPPING is fired.

  7. If this plugin's state was ACTIVE prior to setting the state to STOPPING, the ctkPluginActivator#stop method of this plugin's ctkPluginActivator is called. If that method throws an exception, this method must continue to stop this plugin and a ctkPluginException must be thrown after completion of the remaining steps.

  8. Any services registered by this plugin must be unregistered.
  9. Any services used by this plugin must be released.
  10. Any listeners registered by this plugin must be removed.

  11. If this plugin's state is UNINSTALLED, because this plugin was uninstalled while the ctkPluginActivator::stop method was running, a ctkPluginException must be thrown.

  12. This plugin's state is set to RESOLVED.

  13. A plugin event of type ctkPluginEvent::STOPPED is fired.

Preconditions

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

  • Plugin autostart setting is modified unless the STOP_TRANSIENT option was set.
Parameters:
options The options for stoping this bundle. See STOP_TRANSIENT.
Exceptions:
ctkPluginException If this plugin's ctkPluginActivator threw an exception.
std::logic_error If this plugin has been uninstalled or this plugin tries to change its own state.

Definition at line 112 of file ctkPlugin.cpp.


Friends And Related Function Documentation

friend class ctkPluginFramework [friend]

Definition at line 587 of file ctkPlugin.h.

friend class ctkPluginFrameworkContext [friend]

Reimplemented in ctkPluginFramework.

Definition at line 588 of file ctkPlugin.h.

friend class ctkPlugins [friend]

Definition at line 589 of file ctkPlugin.h.

friend class ctkServiceReferencePrivate [friend]

Definition at line 590 of file ctkPlugin.h.


Member Data Documentation

ctkPluginPrivate* const ctkPlugin::d_ptr [protected]

Definition at line 592 of file ctkPlugin.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Defines

Generated on 21 May 2010 for CTK by  doxygen 1.6.1