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 | Static Public Attributes | List of all members
ctkConfigurationAdmin Struct Referenceabstract

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

Public Member Functions

virtual ctkConfigurationPtr createFactoryConfiguration (const QString &factoryPid)=0
 
virtual ctkConfigurationPtr createFactoryConfiguration (const QString &factoryPid, const QString &location)=0
 
virtual ctkConfigurationPtr getConfiguration (const QString &pid)=0
 
virtual ctkConfigurationPtr getConfiguration (const QString &pid, const QString &location)=0
 
virtual QList< ctkConfigurationPtrlistConfigurations (const QString &filter=QString())=0
 

Static Public Attributes

static const QString SERVICE_FACTORYPID
 
static const QString SERVICE_PLUGINLOCATION
 

Detailed Description

Service for administering configuration data.

The main purpose of this interface is to store plugin configuration data persistently. This information is represented in ctkConfiguration objects. The actual configuration data is a ctkDictionary of properties inside a ctkConfiguration object.

There are two principally different ways to manage configurations. First there is the concept of a Managed Service, where configuration data is uniquely associated with an object registered with the service registry.

Next, there is the concept of a factory where the Configuration Admin service will maintain 0 or more ctkConfiguration objects for a Managed Service Factory that is registered with the Framework.

The first concept is intended for configuration data about "things/services" whose existence is defined externally, e.g. a specific printer. Factories are intended for "things/services" that can be created any number of times, e.g. a configuration for a DHCP server for different networks.

Plugins that require configuration should register a Managed Service or a Managed Service Factory in the service registry. A registration property named service.pid (persistent identifier or PID) must be used to identify this Managed Service or Managed Service Factory to the Configuration Admin service.

When the ConfigurationAdmin detects the registration of a Managed Service, it checks its persistent storage for a configuration object whose service.pid property matches the PID service property ( service.pid) of the Managed Service. If found, it calls ctkManagedService::updated method with the new properties. The implementation of a Configuration Admin service must run these call-backs asynchronously to allow proper synchronization.

When the Configuration Admin service detects a Managed Service Factory registration, it checks its storage for configuration objects whose service.factoryPid property matches the PID service property of the Managed Service Factory. For each such ctkConfiguration objects, it calls the ctkManagedServiceFactory::updated method asynchronously with the new properties. The calls to the updated method of a ctkManagedServiceFactory must be executed sequentially and not overlap in time.

In general, plugins having permission to use the Configuration Admin service can only access and modify their own configuration information. Accessing or modifying the configuration of another bundle requires ctkConfigurationPermission[*,CONFIGURE].

ctkConfiguration objects can be bound to a specified plugin location. In this case, if a matching Managed Service or Managed Service Factory is registered by a plugin with a different location, then the Configuration Admin service must not do the normal callback, and it should log an error. In the case where a ctkConfiguration object is not bound, its location field is null, the Configuration Admin service will bind it to the location of the plugin that registers the first Managed Service or Managed Service Factory that has a corresponding PID property. When a ctkConfiguration object is bound to a plugin location in this manner, the Configuration Admin service must detect if the plugin corresponding to the location is uninstalled. If this occurs, the ctkConfiguration object is unbound, that is its location field is set back to null.

The method descriptions of this class refer to a concept of "the calling plugin". This is a loose way of referring to the plugin which obtained the Configuration Admin service from the service registry. Implementations of ctkConfigurationAdmin must use a ctkServiceFactory to support this concept.

Definition at line 109 of file ctkConfigurationAdmin.h.

Member Function Documentation

◆ createFactoryConfiguration() [1/2]

virtual ctkConfigurationPtr ctkConfigurationAdmin::createFactoryConfiguration ( const QString &  factoryPid)
pure virtual

Create a new factory ctkConfiguration object with a new PID.

The properties of the new ctkConfiguration object are null until the first time that its ctkConfiguration#update(const ctkDictionary&) method is called.

It is not required that the factoryPid maps to a registered Managed Service Factory.

The ctkConfiguration object is bound to the location of the calling plugin.

Parameters
factoryPidPID of factory (not null).
Returns
A new ctkConfiguration object.
Exceptions
ctkIOExceptionif access to persistent storage fails.
ctkSecurityExceptionif caller does not have ctkConfigurationPermission[*,CONFIGURE] and factoryPid is bound to another plugin.

◆ createFactoryConfiguration() [2/2]

virtual ctkConfigurationPtr ctkConfigurationAdmin::createFactoryConfiguration ( const QString &  factoryPid,
const QString &  location 
)
pure virtual

Create a new factory ctkConfiguration object with a new PID.

The properties of the new ctkConfiguration object are null until the first time that its ctkConfiguration#update(const ctkDictionary&) method is called.

It is not required that the factoryPid maps to a registered Managed Service Factory.

The ctkConfiguration is bound to the location specified. If this location is null it will be bound to the location of the first plugin that registers a Managed Service Factory with a corresponding PID.

Parameters
factoryPidPID of factory (not null).
locationA plugin location string, or null.
Returns
a new ctkConfiguration object.
Exceptions
ctkIOExceptionif access to persistent storage fails.
ctkSecurityExceptionif caller does not have ctkConfigurationPermission[*,CONFIGURE].

◆ getConfiguration() [1/2]

virtual ctkConfigurationPtr ctkConfigurationAdmin::getConfiguration ( const QString &  pid)
pure virtual

Get an existing or new ctkConfiguration object from the persistent store.

If the ctkConfiguration object for this PID does not exist, create a new ctkConfiguration object for that PID, where properties are null. Bind its location to the calling plugin's location.

Otherwise, if the location of the existing ctkConfiguration object is null, set it to the calling plugin's location.

Parameters
pidpersistent identifier.
Returns
an existing or new ctkConfiguration matching the PID.
Exceptions
ctkIOExceptionif access to persistent storage fails.
ctkSecurityExceptionif the ctkConfiguration object is bound to a location different from that of the calling plugin and it has no ctkConfigurationPermission[*,CONFIGURE].

◆ getConfiguration() [2/2]

virtual ctkConfigurationPtr ctkConfigurationAdmin::getConfiguration ( const QString &  pid,
const QString &  location 
)
pure virtual

Get an existing ctkConfiguration object from the persistent store, or create a new ctkConfiguration object.

If a ctkConfiguration with this PID already exists in Configuration Admin service return it. The location parameter is ignored in this case.

Else, return a new ctkConfiguration object. This new object is bound to the location and the properties are set to null. If the location parameter is null, it will be set when a Managed Service with the corresponding PID is registered for the first time.

Parameters
pidPersistent identifier.
locationThe plugin location string, or null.
Returns
An existing or new ctkConfiguration object.
Exceptions
ctkIOExceptionif access to persistent storage fails.
ctkSecurityExceptionif the caller does not have ctkConfigurationPermission[*,CONFIGURE].

◆ listConfigurations()

virtual QList<ctkConfigurationPtr> ctkConfigurationAdmin::listConfigurations ( const QString &  filter = QString())
pure virtual

List the current ctkConfiguration objects which match the filter.

Only ctkConfiguration objects with non- null properties are considered current. That is, ctkConfiguration::getProperties() is guaranteed not to return an empty list for each of the returned ctkConfiguration objects.

Normally only ctkConfiguration objects that are bound to the location of the calling plugin are returned, or all if the caller has ctkConfigurationPermission[*,CONFIGURE].

The syntax of the filter string is as defined in the ctkLDAPSearchFilter class. The filter can test any configuration properties including the following:

  • service.pid-QString- the PID under which this is registered
  • service.factoryPid-QString- the factory if applicable
  • service.pluginLocation-QString- the plugin location

The filter can also be empty, meaning that all ctkConfiguration objects should be returned.

Parameters
filterA filter string, or an empty string to retrieve all ctkConfiguration objects.
Returns
All matching ctkConfiguration objects, or an empty list if there aren't any.
Exceptions
ctkIOExceptionif access to persistent storage fails
ctkInvalidArgumentExceptionif the filter string is invalid

Member Data Documentation

◆ SERVICE_FACTORYPID

const QString ctkConfigurationAdmin::SERVICE_FACTORYPID
static

Configuration property naming the Factory PID in the configuration dictionary. The property's value is of type QString.

Definition at line 116 of file ctkConfigurationAdmin.h.

◆ SERVICE_PLUGINLOCATION

const QString ctkConfigurationAdmin::SERVICE_PLUGINLOCATION
static

Configuration property naming the location of the plugin that is associated with a a ctkConfiguration object. This property can be searched for but must not appear in the configuration dictionary for security reason. The property's value is of type QString.

Definition at line 124 of file ctkConfigurationAdmin.h.


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