/*============================================================================= Library: CTK Copyright (c) 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 CTKCONFIGURATION_H #define CTKCONFIGURATION_H #include #include "ctkDictionary.h" /** * \ingroup ConfigAdmin * 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. * * @noimplement * @version */ struct CTK_PLUGINFW_EXPORT ctkConfiguration { virtual ~ctkConfiguration(); /** * Get the PID for this ctkConfiguration object. * * @return the PID for this ctkConfiguration object. * @throws std::logic_error if this configuration has been deleted */ virtual QString getPid() const = 0; /** * 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. * * @return 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. * @throws IllegalStateException if this configuration has been deleted */ virtual ctkDictionary getProperties() const = 0; /** * Update the properties of this ctkConfiguration object. * * Stores the properties in persistent storage after adding or overwriting * the following properties: *

* 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. * * @param properties the new set of properties for this configuration * @throws ctkIOException if update cannot be made persistent * @throws std::invalid_argument if the ctkDictionary object * contains invalid configuration types or contains case variants of * the same key name. * @throws std::logic_error if this configuration has been deleted */ virtual void update(const ctkDictionary& properties) = 0; /** * 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. * * @throws ctkIOException If delete fails * @throws std::logic_error if this configuration has been deleted */ virtual void remove() = 0; /** * For a factory configuration return the PID of the corresponding Managed * Service Factory, else return a null QString. * * @return factory PID or null * @throws std::logic_error if this configuration has been deleted */ virtual QString getFactoryPid() const = 0; /** * 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 ctkConfigurationPlugin * @throws ctkIOException if update cannot access the properties in persistent * storage * @throws std::logic_error if this configuration has been deleted */ virtual void update() = 0; /** * 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. * * @param pluginLocation a plugin location or null. * @throws std::logic_error If this configuration has been deleted. * @throws ctkSecurityException If the caller does not have * ctkConfigurationPermission[*,CONFIGURE]. */ virtual void setPluginLocation(const QString& pluginLocation) = 0; /** * 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. * * @return location to which this configuration is bound, or * null. * @throws std::logic_error If this Configuration object * has been deleted. * @throws ctkSecurityException If the caller does not have * ctkConfigurationPermission[*,CONFIGURE]. */ virtual QString getPluginLocation() const = 0; /** * Equality is defined to have equal PIDs * * Two Configuration objects are equal when their PIDs are equal. * * @param other ctkConfiguration object to compare against * @return true if equal, false if the PID's differ. */ bool operator==(const ctkConfiguration& other) const; }; /** * \ingroup ConfigAdmin * @{ */ typedef QSharedPointer ctkConfigurationPtr; /** * Hash code is based on PID. * * The hashcode for two ctkConfiguration objects must be the same when the * Configuration PID's are the same. * * @param configuration The configuration object for which to compute the hash value. * @return hash code for this ctkConfiguration object */ uint CTK_PLUGINFW_EXPORT qHash(ctkConfigurationPtr configuration); bool CTK_PLUGINFW_EXPORT operator==(const ctkConfigurationPtr& c1, const ctkConfigurationPtr c2); /** @}*/ #endif // CTKCONFIGURATION_H