 |
CTK
0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
|
|
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.
1.9.1