![]() |
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/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< ctkConfigurationPtr > | listConfigurations (const QString &filter=QString())=0 |
Static Public Attributes | |
static const QString | SERVICE_FACTORYPID |
static const QString | SERVICE_PLUGINLOCATION |
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.
|
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.
factoryPid | PID of factory (not null ). |
ctkConfiguration
object. ctkIOException | if access to persistent storage fails. |
ctkSecurityException | if caller does not have ctkConfigurationPermission[*,CONFIGURE] and factoryPid is bound to another plugin. |
|
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.
factoryPid | PID of factory (not null ). |
location | A plugin location string, or null . |
ctkConfiguration
object. ctkIOException | if access to persistent storage fails. |
ctkSecurityException | if caller does not have ctkConfigurationPermission[*,CONFIGURE] . |
|
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.
pid | persistent identifier. |
ctkConfiguration
matching the PID. ctkIOException | if access to persistent storage fails. |
ctkSecurityException | if the ctkConfiguration object is bound to a location different from that of the calling plugin and it has no ctkConfigurationPermission[*,CONFIGURE] . |
|
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.
pid | Persistent identifier. |
location | The plugin location string, or null . |
ctkConfiguration
object. ctkIOException | if access to persistent storage fails. |
ctkSecurityException | if the caller does not have ctkConfigurationPermission[*,CONFIGURE] . |
|
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.
filter | A filter string, or an empty string to retrieve all ctkConfiguration objects. |
ctkConfiguration
objects, or an empty list if there aren't any. ctkIOException | if access to persistent storage fails |
ctkInvalidArgumentException | if the filter string is invalid |
|
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.
|
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.