![]() |
CTK
0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
|
#include <Libs/PluginFramework/ctkPlugin.h>
Public Types | |
enum | StartOption { START_TRANSIENT = 0x00000001 , START_ACTIVATION_POLICY = 0x00000002 } |
enum | State { UNINSTALLED = 0x00000001 , INSTALLED = 0x00000002 , RESOLVED = 0x00000004 , STARTING = 0x00000008 , STOPPING = 0x00000010 , ACTIVE = 0x00000020 } |
enum | StopOption { STOP_TRANSIENT = 0x00000001 } |
Public Member Functions | |
virtual QStringList | findResources (const QString &path, const QString &filePattern, bool recurse) const |
virtual QHash< QString, QString > | getHeaders () |
QString | getLocation () const |
ctkPluginContext * | getPluginContext () const |
long | getPluginId () const |
ctkPluginLocalization | getPluginLocalization (const QLocale &locale, const QString &base=ctkPluginConstants::PLUGIN_LOCALIZATION_DEFAULT_BASENAME) 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 void | uninstall () |
void | update (const QUrl &updateLocation=QUrl()) |
virtual | ~ctkPlugin () |
Protected Member Functions | |
ctkPlugin () | |
void | init (const QWeakPointer< ctkPlugin > &self, ctkPluginFrameworkContext *fw, QSharedPointer< ctkPluginArchive > ba) |
void | init (ctkPluginPrivate *dd) |
Protected Attributes | |
ctkPluginPrivate * | d_ptr |
Friends | |
class | ctkPluginFramework |
class | ctkPluginFrameworkContext |
class | ctkPluginFrameworkLauncherPrivate |
class | ctkPluginFrameworkPrivate |
class | ctkPlugins |
class | ctkServiceReferencePrivate |
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 83 of file ctkPlugin.h.
Represents an ORed combination of plugin states.
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.
|
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. |
Definition at line 178 of file ctkPlugin.h.
enum ctkPlugin::State |
Enumerator | |
---|---|
UNINSTALLED | The plugin is uninstalled and may not be used. The |
INSTALLED | The plugin is installed but not yet resolved. A plugin is in the This state is visible if the plugin's code dependencies are not resolved. The Framework may attempt to resolve an |
RESOLVED | The plugin is resolved and is able to be started. A plugin is in the
Note that the plugin is not active yet. A plugin must be put in the |
STARTING | The plugin is in the process of starting. A plugin is in the 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 |
ACTIVE | The plugin is now running. A plugin is in the |
Definition at line 87 of file ctkPlugin.h.
Represents an ORed combination of start options.
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.
|
Definition at line 218 of file ctkPlugin.h.
|
virtual |
Represents an ORed combination of stop options.
|
protected |
|
virtual |
Returns a list of resources in this plugin.
This method is intended to be used to obtain configuration, setup, localization and other information from this plugin. This method can either return only entries in the specified path or recurse into subdirectories returning entries in the directory tree beginning at the specified path.
Examples:
path | The path name in which to look. The path is always relative to the root of this plugin and may begin with "/". A path value of "/" indicates the root of this plugin. |
filePattern | The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. Substring matching is supported, as specified in the Filter specification, using the wildcard character (""). If a null QString is specified, this is equivalent to "" and matches all files. |
recurse | If true , recurse into subdirectories. Otherwise only return entries from the specified path. |
AdminPermission[this,RESOURCE]
, and the Plugin Framework supports permissions. ctkIllegalStateException | If this plugin has been uninstalled. |
|
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.
QHash<Qstring, QString>
object containing this plugin's Manifest headers and values. Reimplemented in ctkPluginFramework.
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.
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
.
ctkPluginContext
for this plugin or 0
if this plugin has no valid ctkPluginContext
. 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:
long
. This method must continue to return this plugin's unique identifier while this plugin is in the UNINSTALLED
state.
ctkPluginLocalization ctkPlugin::getPluginLocalization | ( | const QLocale & | locale, |
const QString & | base = ctkPluginConstants::PLUGIN_LOCALIZATION_DEFAULT_BASENAME |
||
) | const |
Returns a ctkPluginLocalization
object for the specified locale
. The translations are loaded from a .qm file starting with base
.
You can use the returned ctkPluginLocalization
object to dynamically translate text without changing the current locale of the application. This can be used for example to provide localized messages to multiple users which use the application (maybe some kind of server) simultaneously but require different localizations.
locale | The locale to be used by the returned ctkPluginLocalization object. |
base | The base name of the .qm message file which contains translated messages. Defaults to ctkPluginConstants::PLUGIN_LOCALIZATION_DEFAULT_BASENAME . |
ctkPluginLocalization
instance.
|
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.
path | The path name of the resource. |
ctkIllegalStateException | If this plugin has been uninstalled. |
Reimplemented in ctkPluginFramework.
|
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 "/".
path | The path name for which to return resource paths. |
QString
objects) or an empty list if no entry could be found.ctkIllegalStateException | If this plugin has been uninstalled. |
Reimplemented in ctkPluginFramework.
State ctkPlugin::getState | ( | ) | const |
Returns this plugin's current state.
A plugin can be in only one state at any time.
UNINSTALLED
,INSTALLED
, RESOLVED
,STARTING
, STOPPING
,ACTIVE
. 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.
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 ctkVersion#emptyVersion is returned.
This method must continue to return this plugin's version while this plugin is in the UNINSTALLED
state.
|
protected |
|
protected |
|
virtual |
Starts this plugin.
If this plugin's state is UNINSTALLED
then an ctkIllegalStateException
is thrown.
The following steps are required to start this bundle:
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.
If this plugin's state is ACTIVE
then this method returns immediately.
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.
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.
STARTING
then this method returns immediately. STARTING
. This plugin's state is set to STARTING
.
A plugin event of type ctkPluginEvent::STARTING is fired.
ctkPluginActivator
, is called. If the ctkPluginActivator
throws an exception then: STOPPING
. RESOLVED
. ctkPluginException
is then thrown. If this plugin's state is UNINSTALLED
, because this plugin was uninstalled while the ctkPluginActivator::start
method was running, a ctkPluginException
is thrown.
This plugin's state is set to ACTIVE
.
Preconditions
getState()
in { INSTALLED
, RESOLVED
, STARTING
} or { INSTALLED
, RESOLVED
} if this plugin has a eager activation policy. Postconditions, no exceptions thrown
getState()
in { ACTIVE
} if the eager activation policy was used. ctkPluginActivator::start()
has been called and did not throw an exception if the eager policy was used. Postconditions, when an exception is thrown
getState()
not in { STARTING
, ACTIVE
}. options | The options for starting this plugin. See START_TRANSIENT and START_ACTIVATION_POLICY. The Framework must ignore unrecognized options. |
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. |
ctkIllegalStateException | If this plugin has been uninstalled or this plugin tries to change its own state. |
|
virtual |
Stops this plugin.
The following steps are required to stop a plugin:
If this plugin's state is UNINSTALLED
then an ctkIllegalStateException
is thrown.
ctkPluginException
is thrown to indicate this plugin was unable to be stopped. 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.
If this plugin's state is not STARTING
or ACTIVE
then this method returns immediately.
This plugin's state is set to STOPPING
.
A plugin event of type ctkPluginEvent::STOPPING is fired.
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.
Any listeners registered by this plugin must be removed.
If this plugin's state is UNINSTALLED
, because this plugin was uninstalled while the ctkPluginActivator::stop
method was running, a ctkPluginException
must be thrown.
This plugin's state is set to RESOLVED
.
Preconditions
getState()
in { ACTIVE
}. Postconditions, no exceptions thrown
getState()
not in { ACTIVE
, STOPPING
}. ctkPluginActivator::stop
has been called and did not throw an exception. Postconditions, when an exception is thrown
options | The options for stoping this bundle. See STOP_TRANSIENT. |
ctkPluginException | If this plugin's ctkPluginActivator threw an exception. |
ctkIllegalStateException | If this plugin has been uninstalled or this plugin tries to change its own state. |
Reimplemented in ctkPluginFramework.
|
virtual |
Uninstalls this plugin.
This method causes the Plugin Framework to notify other plugins that this plugin is being uninstalled, and then puts this plugin into the UNINSTALLED
state. The Framework must remove any resources related to this plugin that it is able to remove.
If this plugin is required by other plugins which are already resolved, the Framework must keep this plugin loaded until the Framework is relaunched.
The following steps are required to uninstall a plugin:
If this plugin's state is UNINSTALLED
then an ctkIllegalStateException
is thrown.
If this plugin's state is ACTIVE
, STARTING
or STOPPING
, this plugin is stopped as described in the ctkPlugin::stop
method. If ctkPlugin::stop
throws an exception, a Framework event of type ctkPluginFrameworkEvent::PLUGIN_ERROR is fired containing the exception.
This plugin's state is set to UNINSTALLED
.
A plugin event of type ctkPluginEvent::UNINSTALLED is fired.
Preconditions
getState()
not in { UNINSTALLED
}. Postconditions, no exceptions thrown
getState()
in { UNINSTALLED
}. Postconditions, when an exception is thrown
getState()
not in { UNINSTALLED
}. ctkPluginException | If the uninstall failed. This can occur if another thread is attempting to change this plugin's state and does not complete in a timely manner. |
ctkIllegalStateException | If this plugin has been uninstalled or this plugin tries to change its own state. |
Reimplemented in ctkPluginFramework.
void ctkPlugin::update | ( | const QUrl & | updateLocation = QUrl() | ) |
Updates this plugin from a QUrl
.
If the specified QURl
is empty
, the Framework creates the QUrl
from which to read the updated plugin by interpreting, in an implementation dependent manner, this plugin's Plugin-UpdateLocation Manifest header, if present, or this plugin's original location.
If this plugin's state is ACTIVE
, it must be stopped before the update and started after the update successfully completes.
If this plugin has exported any classes that are used by another plugin, these classes remain available until the Framework is relaunched.
The following steps are required to update a plugin:
If this plugin's state is UNINSTALLED
then an ctkIllegalStateException
is thrown.
If this plugin's state is ACTIVE
, STARTING
or STOPPING
, this plugin is stopped as described in the ctkPlugin::stop()
method. If ctkPlugin::stop()
throws an exception, the exception is rethrown terminating the update.
The updated version of this plugin is read from the URL and installed. If the Framework is unable to install the updated version of this plugin, the original version of this plugin is restored and a ctkPluginException
is thrown after completion of the remaining steps.
This plugin's state is set to INSTALLED
.
If the updated version of this plugin was successfully installed, a plugin event of type ctkPluginEvent#UPDATED is fired.
ACTIVE
, the updated plugin is started as described in the ctkPlugin::start()
method. If ctkPlugin::start()
throws an exception, a Framework event of type ctkPluginFrameworkEvent#PLUGIN_ERROR is fired containing the exception. Preconditions
getState()
not in { UNINSTALLED
}. Postconditions, no exceptions thrown
getState()
in { INSTALLED
, RESOLVED
, ACTIVE
}. Postconditions, when an exception is thrown
getState()
in { INSTALLED
, RESOLVED
, ACTIVE
}. updateLocation | The QUrl from which to read the new plugin or null to indicate the Framework must create the URL from this plugin's Plugin-UpdateLocation Manifest header, if present, or this plugin's original location. |
ctkPluginException | If the update location cannot be read or the update fails. |
ctkIllegalStateException | If this plugin has been uninstalled or this plugin tries to change its own state. |
|
friend |
Definition at line 798 of file ctkPlugin.h.
|
friend |
Definition at line 801 of file ctkPlugin.h.
|
friend |
Definition at line 799 of file ctkPlugin.h.
|
friend |
Definition at line 800 of file ctkPlugin.h.
|
friend |
Definition at line 802 of file ctkPlugin.h.
|
friend |
Definition at line 803 of file ctkPlugin.h.
|
protected |
Definition at line 808 of file ctkPlugin.h.