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 | List of all members
ctkConfiguration Struct Referenceabstract

#include <Libs/PluginFramework/service/cm/ctkConfiguration.h>

Public Member Functions

virtual QString getFactoryPid () const =0
 
virtual QString getPid () const =0
 
virtual QString getPluginLocation () const =0
 
virtual ctkDictionary getProperties () const =0
 
bool operator== (const ctkConfiguration &other) const
 
virtual void remove ()=0
 
virtual void setPluginLocation (const QString &pluginLocation)=0
 
virtual void update ()=0
 
virtual void update (const ctkDictionary &properties)=0
 
virtual ~ctkConfiguration ()
 

Detailed Description

The configuration information for a ctkManagedService or ctkManagedServiceFactory object.

The Configuration Admin service uses this interface to represent the configuration information for a ctkManagedService or for a service instance of a ctkManagedServiceFactory.

A ctkConfiguration object contains a configuration dictionary and allows the properties to be updated via this object. Plugins wishing to receive configuration dictionaries do not need to use this class - they register a ctkManagedService or ctkManagedServiceFactory. Only administrative plugins, and plugins wishing to update their own configurations need to use this class.

The properties handled in this configuration have case insensitive QString objects as keys. However, case is preserved from the last set key/value.

A configuration can be bound to a plugin location ( ctkPlugin::getLocation()). The purpose of binding a ctkConfiguration object to a location is to make it impossible for another plugin to forge a PID that would match this configuration. When a configuration is bound to a specific location, and a plugin with a different location registers a corresponding ctkManagedService object or ctkManagedServiceFactory object, then the configuration is not passed to the updated method of that object.

If a configuration's location is empty, it is not yet bound to a location. It will become bound to the location of the first plugin that registers a ctkManagedService or ctkManagedServiceFactory object with the corresponding PID.

The same ctkConfiguration object is used for configuring both a Managed Service Factory and a Managed Service. When it is important to differentiate between these two the term "factory configuration" is used.

Definition at line 72 of file ctkConfiguration.h.

Constructor & Destructor Documentation

◆ ~ctkConfiguration()

virtual ctkConfiguration::~ctkConfiguration ( )
virtual

Member Function Documentation

◆ getFactoryPid()

virtual QString ctkConfiguration::getFactoryPid ( ) const
pure virtual

For a factory configuration return the PID of the corresponding Managed Service Factory, else return a null QString.

Returns
factory PID or null
Exceptions
ctkIllegalStateExceptionif this configuration has been deleted

◆ getPid()

virtual QString ctkConfiguration::getPid ( ) const
pure virtual

Get the PID for this ctkConfiguration object.

Returns
the PID for this ctkConfiguration object.
Exceptions
ctkIllegalStateExceptionif this configuration has been deleted

◆ getPluginLocation()

virtual QString ctkConfiguration::getPluginLocation ( ) const
pure virtual

Get the plugin location.

Returns the plugin location to which this configuration is bound, or null if it is not yet bound to a plugin location.

Returns
location to which this configuration is bound, or null.
Exceptions
ctkIllegalStateExceptionIf this Configuration object has been deleted.
ctkSecurityExceptionIf the caller does not have ctkConfigurationPermission[*,CONFIGURE].

◆ getProperties()

virtual ctkDictionary ctkConfiguration::getProperties ( ) const
pure virtual

Return the properties of this ctkConfiguration object.

The Dictionary object returned is a private copy for the caller and may be changed without influencing the stored configuration. The keys in the returned dictionary are case insensitive and are always of type String.

If called just after the configuration is created and before update has been called, this method returns null.

Returns
A private copy of the properties for the caller or null. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the getBundleLocation method.
Exceptions
IllegalStateExceptionif this configuration has been deleted

◆ operator==()

bool ctkConfiguration::operator== ( const ctkConfiguration other) const

Equality is defined to have equal PIDs

Two Configuration objects are equal when their PIDs are equal.

Parameters
otherctkConfiguration object to compare against
Returns
true if equal, false if the PID's differ.

◆ remove()

virtual void ctkConfiguration::remove ( )
pure virtual

Delete this ctkConfiguration object.

Removes this configuration object from the persistent store. Notify asynchronously the corresponding Managed Service or Managed Service Factory. A ctkManagedService object is notified by a call to its updated method with a null properties argument. A ctkManagedServiceFactory object is notified by a call to its deleted method.

Also initiates an asynchronous call to all ctkConfigurationListeners with a ctkConfigurationEvent::CM_DELETED event.

Exceptions
ctkIOExceptionIf delete fails
ctkIllegalStateExceptionif this configuration has been deleted

◆ setPluginLocation()

virtual void ctkConfiguration::setPluginLocation ( const QString &  pluginLocation)
pure virtual

Bind this ctkConfiguration object to the specified plugin location.

If the pluginLocation parameter is null then the ctkConfiguration object will not be bound to a location. It will be set to the plugin's location before the first time a Managed Service/Managed Service Factory receives this ctkConfiguration object via the updated method and before any plugins are called. The plugin location will be set persistently.

Parameters
pluginLocationa plugin location or null.
Exceptions
ctkIllegalStateExceptionIf this configuration has been deleted.
ctkSecurityExceptionIf the caller does not have ctkConfigurationPermission[*,CONFIGURE].

◆ update() [1/2]

virtual void ctkConfiguration::update ( )
pure virtual

Update the ctkConfiguration object with the current properties.

Initiate the updated callback to the Managed Service or Managed Service Factory with the current properties asynchronously.

This is the only way for a plugin that uses a Configuration Plugin service to initiate a callback. For example, when that plugin detects a change that requires an update of the Managed Service or Managed Service Factory via its ctkConfigurationPlugin object.

See also
ctkConfigurationPlugin
Exceptions
ctkIOExceptionif update cannot access the properties in persistent storage
ctkIllegalStateExceptionif this configuration has been deleted

◆ update() [2/2]

virtual void ctkConfiguration::update ( const ctkDictionary properties)
pure virtual

Update the properties of this ctkConfiguration object.

Stores the properties in persistent storage after adding or overwriting the following properties:

  • "service.pid" : is set to be the PID of this configuration.
  • "service.factoryPid" : if this is a factory configuration it is set to the factory PID else it is not set.

These system properties are all of type QString.

If the corresponding Managed Service/Managed Service Factory is registered, its updated method must be called asynchronously. Else, this callback is delayed until aforementioned registration occurs.

Also initiates an asynchronous call to all ctkConfigurationListeners with a ctkConfigurationEvent::CM_UPDATED event.

Parameters
propertiesthe new set of properties for this configuration
Exceptions
ctkIOExceptionif update cannot be made persistent
ctkInvalidArgumentExceptionif the ctkDictionary object contains invalid configuration types or contains case variants of the same key name.
ctkIllegalStateExceptionif this configuration has been deleted

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