/*============================================================================= Library: CTK Copyright (c) 2010 German Cancer Research Center, Division of Medical and Biological Informatics Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. =============================================================================*/ #ifndef CTKCONFIGURATIONADMIN_H #define CTKCONFIGURATIONADMIN_H #include "ctkConfiguration.h" /** * \ingroup ConfigAdmin * 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 * {@link ctkServiceFactory} to support this concept. * */ struct CTK_PLUGINFW_EXPORT ctkConfigurationAdmin { /** * Configuration property naming the Factory PID in the configuration * dictionary. The property's value is of type QString. */ static const QString SERVICE_FACTORYPID; // = "service.factoryPid"; /** * 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. */ static const QString SERVICE_PLUGINLOCATION; // = "service.pluginLocation"; /** * 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 * {@link 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. * * @param factoryPid PID of factory (not null). * @return A new ctkConfiguration object. * @throws ctkIOException if access to persistent storage fails. * @throws ctkSecurityException if caller does not have * ctkConfigurationPermission[*,CONFIGURE] and * factoryPid is bound to another plugin. */ virtual ctkConfigurationPtr createFactoryConfiguration(const QString& factoryPid) = 0; /** * 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 * {@link 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. * * @param factoryPid PID of factory (not null). * @param location A plugin location string, or null. * @return a new ctkConfiguration object. * @throws ctkIOException if access to persistent storage fails. * @throws ctkSecurityException if caller does not have ctkConfigurationPermission[*,CONFIGURE]. */ virtual ctkConfigurationPtr createFactoryConfiguration(const QString& factoryPid, const QString& location) = 0; /** * 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. * * @param pid Persistent identifier. * @param location The plugin location string, or null. * @return An existing or new ctkConfiguration object. * @throws ctkIOException if access to persistent storage fails. * @throws ctkSecurityException if the caller does not have ctkConfigurationPermission[*,CONFIGURE]. */ virtual ctkConfigurationPtr getConfiguration(const QString& pid, const QString& location) = 0; /** * 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. * * @param pid persistent identifier. * @return an existing or new ctkConfiguration matching the PID. * @throws ctkIOException if access to persistent storage fails. * @throws ctkSecurityException if the ctkConfiguration object is * bound to a location different from that of the calling plugin and it * has no ctkConfigurationPermission[*,CONFIGURE]. */ virtual ctkConfigurationPtr getConfiguration(const QString& pid) = 0; /** * 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 * {@link ctkLDAPSearchFilter} class. The filter can test any * configuration properties including the following: *

* The filter can also be empty, meaning that all * ctkConfiguration objects should be returned. * * @param filter A filter string, or an empty string to retrieve all * ctkConfiguration objects. * @return All matching ctkConfiguration objects, or * an empty list if there aren't any. * @throws ctkIOException if access to persistent storage fails * @throws std::invalid_argument if the filter string is invalid */ virtual QList listConfigurations(const QString& filter = QString()) = 0; }; Q_DECLARE_INTERFACE(ctkConfigurationAdmin, "org.commontk.service.cm.ConfigurationAdmin") #endif // CTKCONFIGURATIONADMIN_H