CTK  0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
ctkPluginContext Class Reference

#include <Libs/PluginFramework/ctkPluginContext.h>

Public Member Functions

bool connectFrameworkListener (const QObject *receiver, const char *slot, Qt::ConnectionType type=Qt::QueuedConnection)
 
bool connectPluginListener (const QObject *receiver, const char *slot, Qt::ConnectionType type=Qt::QueuedConnection)
 
void connectServiceListener (QObject *receiver, const char *slot, const QString &filter=QString())
 
void disconnectFrameworkListener (const QObject *receiver, const char *slot=0)
 
void disconnectPluginListener (const QObject *receiver, const char *slot=0)
 
void disconnectServiceListener (QObject *receiver, const char *slot)
 
QFileInfo getDataFile (const QString &filename)
 
QSharedPointer< ctkPlugingetPlugin () const
 
QSharedPointer< ctkPlugingetPlugin (long id) const
 
QList< QSharedPointer< ctkPlugin > > getPlugins () const
 
QVariant getProperty (const QString &key) const
 
QObject * getService (const ctkServiceReference &reference)
 
template<class S >
S * getService (const ctkServiceReference &reference)
 
template<class S >
ctkServiceReference getServiceReference ()
 
ctkServiceReference getServiceReference (const QString &clazz)
 
QList< ctkServiceReferencegetServiceReferences (const QString &clazz, const QString &filter=QString())
 
template<class S >
QList< ctkServiceReferencegetServiceReferences (const QString &filter=QString())
 
QSharedPointer< ctkPlugininstallPlugin (const QUrl &location, QIODevice *input=0)
 
ctkServiceRegistration registerService (const char *clazz, QObject *service, const ctkDictionary &properties=ctkDictionary())
 
ctkServiceRegistration registerService (const QStringList &clazzes, QObject *service, const ctkDictionary &properties=ctkDictionary())
 
template<class S >
ctkServiceRegistration registerService (QObject *service, const ctkDictionary &properties=ctkDictionary())
 
bool ungetService (const ctkServiceReference &reference)
 
 ~ctkPluginContext ()
 

Protected Member Functions

 ctkPluginContext (ctkPluginPrivate *plugin)
 

Protected Attributes

ctkPluginContextPrivate *const d_ptr
 

Friends

class ctkPlugin
 
class ctkPluginFrameworkPrivate
 
class ctkPluginPrivate
 

Detailed Description

A plugin's execution context within the Framework. The context is used to grant access to other methods so that this plugin can interact with the Framework.

ctkPluginContext methods allow a plugin to:

A ctkPluginContext object will be created and provided to the plugin associated with this context when it is started using the ctkPluginActivator::start method. The same ctkPluginContext object will be passed to the plugin associated with this context when it is stopped using the ctkPluginActivator::stop method. A ctkPluginContext object is generally for the private use of its associated plugin and is not meant to be shared with other plugins in the plugin environment.

The ctkPlugin object associated with a ctkPluginContext object is called the context plugin.

The ctkPluginContext object is only valid during the execution of its context plugin; that is, during the period from when the context plugin is in the STARTING, STOPPING, and ACTIVE plugin states. If the ctkPluginContext object is used subsequently, a ctkIllegalStateException must be thrown. The ctkPluginContext object must never be reused after its context plugin is stopped.

The Framework is the only entity that can create ctkPluginContext objects and they are only valid within the Framework that created them.

Remarks
This class is thread safe.

Definition at line 98 of file ctkPluginContext.h.

Constructor & Destructor Documentation

◆ ~ctkPluginContext()

ctkPluginContext::~ctkPluginContext ( )

◆ ctkPluginContext()

ctkPluginContext::ctkPluginContext ( ctkPluginPrivate plugin)
protected

Member Function Documentation

◆ connectFrameworkListener()

bool ctkPluginContext::connectFrameworkListener ( const QObject *  receiver,
const char *  slot,
Qt::ConnectionType  type = Qt::QueuedConnection 
)

Connects the specified slot to the context plugin's signal which emits general Framework events. The signature of the slot must be "slotName(ctkPluginFrameworkEvent)".

Parameters
receiverThe object to connect to.
slotThe slot to be connected.
typeThe Qt connection type.
Returns
true if the connection was successfull; false otherwise.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
ctkPluginFrameworkEvent
ctkEventBus

◆ connectPluginListener()

bool ctkPluginContext::connectPluginListener ( const QObject *  receiver,
const char *  slot,
Qt::ConnectionType  type = Qt::QueuedConnection 
)

Connects the specified slot to the context plugins's signal which is emitted when a plugin has a lifecycle state change. The signature of the slot must be "slotName(ctkPluginEvent)".

Parameters
receiverThe object to connect to.
slotThe slot to be connected.
typeThe Qt connection type. Only Qt::DirectConnection, Qt::QueuedConnection, or Qt::BlockingQueuedConnection is allowed.
Returns
true if the connection was successfull; false otherwise.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
ctkPluginEvent
ctkEventBus

◆ connectServiceListener()

void ctkPluginContext::connectServiceListener ( QObject *  receiver,
const char *  slot,
const QString &  filter = QString() 
)

Connects the specified slot with the specified filter to the context plugins's signal emitting service events when a service has a lifecycle state change. The signature of the slot must be "slotName(const ctkServiceEvent&)", but only the name of the slot must be provided as the argument. See ctkLDAPSearchFilter for a description of the filter syntax.

If the object to connect to is destroyed, the slot is automatically disconnected. To explicitly disconnect the slot, use disconnectServiceListener().

If the context plugin's list of listeners already contains the same slot for the given receiver, then this method replaces that slot's filter (which may be null) with the specified one (which may be null).

The slot is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the ctkPluginConstants#OBJECTCLASS property. If filter is null, all services are considered to match the filter.

When using a filter, it is possible that the ctkServiceEvents for the complete lifecycle of a service will not be delivered to the slot. For example, if the filter only matches when the property x has the value 1, the listener will not be called if the service is registered with the property x not set to the value 1. Subsequently, when the service is modified setting property x to the value 1, the filter will match and the slot will be called with a ServiceEvent of type MODIFIED. Thus, the slot will not be called with a ServiceEvent of type REGISTERED.

Parameters
receiverThe object to connect to.
slotThe name of the slot to be connected.
filterThe filter criteria.
Exceptions
ctkInvalidArgumentExceptionIf filter contains an invalid filter string that cannot be parsed.
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
ctkServiceEvent
disconnectServiceListener()
ctkEventBus

◆ disconnectFrameworkListener()

void ctkPluginContext::disconnectFrameworkListener ( const QObject *  receiver,
const char *  slot = 0 
)

Disconnects the specified slot from the context plugin.

If slot is not connected to the context plugin, this method does nothing.

Parameters
receiverThe object which has previously connected slot.
slotThe Qt slot to be disconnected. If NULL, all slots previously connected via connectFrameworkListener are disconnected.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ disconnectPluginListener()

void ctkPluginContext::disconnectPluginListener ( const QObject *  receiver,
const char *  slot = 0 
)

Disconnects the specified slot from the context plugin.

If slot is not connected to the context plugin, this method does nothing.

Parameters
receiverThe object which has previously connected slot.
slotThe Qt slot to be disconnected. If NULL, all slots previously connected via connectPluginListener are disconnected.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ disconnectServiceListener()

void ctkPluginContext::disconnectServiceListener ( QObject *  receiver,
const char *  slot 
)

Disconnects a slot which has been previously connected with a call to connectServiceListener().

Parameters
receiverThe object containing the slot.
slotThe slot to be disconnected.
See also
connectServiceListener()

◆ getDataFile()

QFileInfo ctkPluginContext::getDataFile ( const QString &  filename)

Creates a QFileInfo object for a file or directoryin the persistent storage area provided for the plugin by the Framework.

A QFileInfo object for the base directory of the persistent storage area provided for the context plugin by the Framework can be obtained by calling this method with an empty string as filename.

If the permissions are enabled, the Framework will ensure that the plugin has the ctkFilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for the context plugin.

Parameters
filenameA relative name to the file or directory to be accessed.
Returns
A QFileInfo object that represents the requested file or directory.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ getPlugin() [1/2]

QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin ( ) const

Returns the ctkPlugin object associated with this ctkPluginContext. This plugin is called the context plugin.

Returns
The ctkPlugin object associated with this ctkPluginContext.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ getPlugin() [2/2]

QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin ( long  id) const

Returns the plugin with the specified identifier.

Parameters
idThe identifier of the plugin to retrieve.
Returns
A ctkPlugin object or 0 if the identifier does not match any installed plugin.

◆ getPlugins()

QList<QSharedPointer<ctkPlugin> > ctkPluginContext::getPlugins ( ) const

Returns a list of all installed plugins.

This method returns a list of all plugins installed in the plugin environment at the time of the call to this method. However, since the Framework is a very dynamic environment, plugins can be installed or uninstalled at anytime.

Returns
A QList of ctkPlugin objects, one object per installed plugin.

◆ getProperty()

QVariant ctkPluginContext::getProperty ( const QString &  key) const

Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns an invalid QVariant if the property is not found.

Parameters
keyThe name of the requested property.
Returns
The value of the requested property, or an invalid QVariant if the property is undefined.

◆ getService() [1/2]

QObject* ctkPluginContext::getService ( const ctkServiceReference reference)

Returns the service object referenced by the specified ctkServiceReference object.

A plugin's use of a service is tracked by the plugin's use count of that service. Each time a service's service object is returned by getService(const ctkServiceReference&) the context plugin's use count for that service is incremented by one. Each time the service is released by ungetService(const ctkServiceReference&) the context plugin's use count for that service is decremented by one.

When a plugin's use count for a service drops to zero, the plugin should no longer use that service.

This method will always return 0 when the service associated with this reference has been unregistered.

The following steps are required to get the service object:

  1. If the service has been unregistered, 0 is returned.
  2. The context plugin's use count for this service is incremented by one.
  3. If the context plugin's use count for the service is currently one and the service was registered with an object implementing the ctkServiceFactory interface, the ctkServiceFactory::getService method is called to create a service object for the context plugin. This service object is cached by the Framework. While the context plugin's use count for the service is greater than zero, subsequent calls to get the services's service object for the context plugin will return the cached service object.
    If the service object returned by the ctkServiceFactory object is not an instance of all the classes named when the service was registered or the ctkServiceFactory object throws an exception, 0 is returned and a Framework event of type ctkPluginFrameworkEvent::PLUGIN_ERROR containing a ctkServiceException describing the error is fired.
  4. The service object for the service is returned.
Parameters
referenceA reference to the service.
Returns
A service object for the service associated with reference or 0 if the service is not registered, the service object returned by a ctkServiceFactory does not implement the classes under which it was registered or the ctkServiceFactory threw an exception.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
ctkInvalidArgumentExceptionIf the specified ctkServiceReference was not created by the same framework instance as this ctkPluginContext or if it is invalid (default constructed).
See also
ungetService(const ctkServiceReference&)
ctkServiceFactory

◆ getService() [2/2]

template<class S >
S* ctkPluginContext::getService ( const ctkServiceReference reference)
inline

Returns the service object referenced by the specified ctkServiceReference object.

This is a convenience method which is identical to QObject* getService(ctkServiceReference) except that it casts the service object to the supplied template argument type

Returns
A service object for the service associated with reference or 0 if the service is not registered, the service object returned by a ctkServiceFactory does not implement the classes under which it was registered, the ctkServiceFactory threw an exception or the service could not be casted to the desired type.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
ctkInvalidArgumentExceptionIf the specified ctkServiceReference was not created by the same framework instance as this ctkPluginContext or if it is invalid (default constructed).
See also
getService(const ctkServiceReference&)
ungetService(const ctkServiceReference&)
ctkServiceFactory

Definition at line 466 of file ctkPluginContext.h.

◆ getServiceReference() [1/2]

template<class S >
ctkServiceReference ctkPluginContext::getServiceReference ( )
inline

Returns a ctkServiceReference object for a service that implements and was registered under the specified template class argument.

This method is identical to getServiceReference(const QString&) except that the class name for the service object is automatically deduced from the template argument.

Returns
A ctkServiceReference object, or 0 if no services are registered which implement the named class.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
ctkServiceExceptionIt no service was registered under the given class name.
See also
getServiceReference(const QString&)
getServiceReferences(const QString&)

Definition at line 375 of file ctkPluginContext.h.

◆ getServiceReference() [2/2]

ctkServiceReference ctkPluginContext::getServiceReference ( const QString &  clazz)

Returns a ctkServiceReference object for a service that implements and was registered under the specified class.

The returned ctkServiceReference object is valid at the time of the call to this method. However as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling ctkPluginContext::getServiceReferences(const QString&, const QString&) with an empty filter expression. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service with the highest ranking (as specified in its ctkPluginConstants::SERVICE_RANKING property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its ctkPluginConstants::SERVICE_ID property); that is, the service that was registered first is returned.

Parameters
clazzThe class name with which the service was registered.
Returns
A ctkServiceReference object, or 0 if no services are registered which implement the named class.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
ctkServiceExceptionIt no service was registered under the given class name.
See also
getServiceReferences(const QString&, const QString&)

◆ getServiceReferences() [1/2]

QList<ctkServiceReference> ctkPluginContext::getServiceReferences ( const QString &  clazz,
const QString &  filter = QString() 
)

Returns a list of ctkServiceReference objects. The returned list contains services that were registered under the specified class and match the specified filter expression.

The list is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See ctkLDAPSearchFilter for a description of the filter syntax. If the specified filter is empty, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an ctkInvalidArgumentException will be thrown with a human readable message where the filter became unparsable.

The result is a list of ctkServiceReference objects for all services that meet all of the following conditions:

  • If the specified class name, clazz, is not empty, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.
  • If the specified filter is not empty, the filter expression must match the service.
Parameters
clazzThe class name with which the service was registered or an empty string for all services.
filterThe filter expression or empty for all services.
Returns
A list of ctkServiceReference objects or an empty list if no services are registered which satisfy the search.
Exceptions
ctkInvalidArgumentExceptionIf the specified filter contains an invalid filter expression that cannot be parsed.
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ getServiceReferences() [2/2]

template<class S >
QList<ctkServiceReference> ctkPluginContext::getServiceReferences ( const QString &  filter = QString())
inline

Returns a list of ctkServiceReference objects. The returned list contains services that were registered under the Qt interface id of the template argument S and match the specified filter expression.

This method is identical to getServiceReferences(const QString&, const QString&) except that the class name for the service object is automatically deduced from the template argument.

Parameters
filterThe filter expression or empty for all services.
Returns
A list of ctkServiceReference objects or an empty list if no services are registered which satisfy the search.
Exceptions
ctkInvalidArgumentExceptionIf the specified filter contains an invalid filter expression that cannot be parsed.
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
getServiceReferences(const QString&, const QString&)

Definition at line 320 of file ctkPluginContext.h.

◆ installPlugin()

QSharedPointer<ctkPlugin> ctkPluginContext::installPlugin ( const QUrl &  location,
QIODevice *  input = 0 
)

Installs a plugin from the specified QIODevice object.

If the specified QIODevice is null, the Framework must create the QIODevice from which to read the plugin by interpreting, in an implementation dependent manner, the specified location.

The specified location identifier will be used as the identity of the plugin. Every installed plugin is uniquely identified by its location identifier which is typically in the form of a URL.

The following steps are required to install a plugin:

  1. If a plugin containing the same location identifier is already installed, the ctkPlugin object for that plugin is returned.

  2. The plugin's content is read from the input stream. If this fails, a ctkPluginException is thrown.

  3. The plugin's associated resources are allocated. The associated resources minimally consist of a unique identifier and a persistent storage area. If this step fails, a ctkPluginException is thrown.

  4. The plugin's state is set to INSTALLED.

  5. A plugin event of type ctkPluginEvent#INSTALLED is fired.

  6. The ctkPlugin object for the newly or previously installed plugin is returned.

Postconditions, no exceptions thrown

  • getState() in &#123; INSTALLED, RESOLVED &#125;.
  • Plugin has a unique ID.

Postconditions, when an exception is thrown

  • Plugin is not installed and no trace of the plugin exists.
Parameters
locationThe location identifier of the plugin to install.
inputThe QIODevice object from which this plugin will be read or null to indicate the Framework must create the I/O device from the specified location identifier. The I/O device must always be closed when this method completes, even if an exception is thrown.
Returns
The ctkPlugin object of the installed plugin.
Exceptions
ctkPluginExceptionIf the I/O device cannot be read or the installation failed.
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.

◆ registerService() [1/3]

ctkServiceRegistration ctkPluginContext::registerService ( const char *  clazz,
QObject *  service,
const ctkDictionary properties = ctkDictionary() 
)

Registers the specified service object with the specified properties under the specified class name with the Framework.

This method is otherwise identical to registerService(const QStringList&, QObject*, const ctkDictionary&) and is provided as a convenience when service will only be registered under a single class name. Note that even in this case the value of the service's ctkPluginConstants::OBJECTCLASS property will be a QStringList, rather than just a single string.

Parameters
clazzThe class name under which the service can be located.
serviceThe service object or a ctkServiceFactory object.
propertiesThe properties for this service.
Returns
A ctkServiceRegistration object for use by the plugin registering the service to update the service's properties or to unregister the service.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
registerService(const QStringList&, QObject*, const ctkDictionary&)

◆ registerService() [2/3]

ctkServiceRegistration ctkPluginContext::registerService ( const QStringList &  clazzes,
QObject *  service,
const ctkDictionary properties = ctkDictionary() 
)

Registers the specified service object with the specified properties under the specified class names into the Framework. A ctkServiceRegistration object is returned. The ctkServiceRegistration object is for the private use of the plugin registering the service and should not be shared with other plugins. The registering plugin is defined to be the context plugin. Other plugins can locate the service by using either the getServiceReferences or getServiceReference method.

A plugin can register a service object that implements the ctkServiceFactory interface to have more flexibility in providing service objects to other plugins.

The following steps are required to register a service:

  1. If service is not a ctkServiceFactory, an ctkInvalidArgumentException is thrown if service is not an instance of all the specified class names.
  2. The Framework adds the following service properties to the service properties from the specified ctkDictionary (which may be omitted):
    A property named ctkPluginConstants#SERVICE_ID identifying the registration number of the service
    A property named ctkPluginConstants#OBJECTCLASS containing all the specified classes.
    Properties with these names in the specified ctkDictionary will be ignored.
  3. The service is added to the Framework service registry and may now be used by other plugins.
  4. A service event of type ctkServiceEvent#REGISTERED is fired.
  5. A ctkServiceRegistration object for this registration is returned.
Parameters
clazzesThe class names under which the service can be located. The class names will be stored in the service's properties under the key ctkPluginConstants#OBJECTCLASS.
serviceThe service object or a ctkServiceFactory object.
propertiesThe properties for this service. The keys in the properties object must all be QString objects. See ctkPluginConstants for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties the ctkServiceRegistration::setProperties method must be called. The set of properties may be omitted if the service has no properties.
Returns
A ctkServiceRegistration object for use by the plugin registering the service to update the service's properties or to unregister the service.
Exceptions
ctkInvalidArgumentExceptionIf one of the following is true:
  • service is 0.
  • service is not a ctkServiceFactory object and is not an instance of all the named classes in clazzes.
  • properties contains case variants of the same key name.
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
See also
ctkServiceRegistration
ctkServiceFactory

◆ registerService() [3/3]

template<class S >
ctkServiceRegistration ctkPluginContext::registerService ( QObject *  service,
const ctkDictionary properties = ctkDictionary() 
)
inline

Definition at line 241 of file ctkPluginContext.h.

◆ ungetService()

bool ctkPluginContext::ungetService ( const ctkServiceReference reference)

Releases the service object referenced by the specified ctkServiceReference object. If the context plugin's use count for the service is zero, this method returns false. Otherwise, the context plugins's use count for the service is decremented by one.

The service's service object should no longer be used and all references to it should be destroyed when a bundle's use count for the service drops to zero.

The following steps are required to unget the service object:

  1. If the context plugin's use count for the service is zero or the service has been unregistered, false is returned.
  2. The context plugin's use count for this service is decremented by one.
  3. If the context plugin's use count for the service is currently zero and the service was registered with a ctkServiceFactory object, the ctkServiceFactory#ungetService method is called to release the service object for the context plugin.
  4. true is returned.
Parameters
referenceA reference to the service to be released.
Returns
false if the context plugin's use count for the service is zero or if the service has been unregistered; true otherwise.
Exceptions
ctkIllegalStateExceptionIf this ctkPluginContext is no longer valid.
ctkInvalidArgumentExceptionIf the specified ctkServiceReference was not created by the same framework instance as this ctkPluginContext.
See also
getService
ctkServiceFactory

Friends And Related Function Documentation

◆ ctkPlugin

friend class ctkPlugin
friend

Definition at line 729 of file ctkPluginContext.h.

◆ ctkPluginFrameworkPrivate

friend class ctkPluginFrameworkPrivate
friend

Definition at line 728 of file ctkPluginContext.h.

◆ ctkPluginPrivate

friend class ctkPluginPrivate
friend

Definition at line 730 of file ctkPluginContext.h.

Member Data Documentation

◆ d_ptr

ctkPluginContextPrivate* const ctkPluginContext::d_ptr
protected

Definition at line 734 of file ctkPluginContext.h.


The documentation for this class was generated from the following file: