cppmicroservices-configadmin - Man Page

class Configuration

#include <cppmicroservices/cm/Configuration.hpp>

The Configuration object (normally obtained as a std::shared_ptr<Configuration>) is the principal means for clients of ConfigurationAdmin to inspect or update the Configuration of a given service or service factory.

Public Functions

virtual ~Configuration() noexcept = default

virtual std::string GetPid() const = 0

Get the PID of this Configuration.

Throws

std::runtime_error -- if this Configuration object has been Removed

Returns

the PID of this Configuration

virtual std::string GetFactoryPid() const = 0

Get the Factory PID which is responsible for this Configuration.

If this Configuration does not belong to any Factory, returns an empty string.

Throws

std::runtime_error -- if this Configuration object has been Removed

Returns

the Factory PID associated with this Configuration, if applicable

virtual AnyMap GetProperties() const = 0

Get the properties of this Configuration.

Returns a copy.

Throws

std::runtime_error -- if this Configuration object has been Removed

Returns

the properties of this Configuration

virtual unsigned long GetChangeCount() const = 0

Get the change count.

Each Configuration must maintain a change counter that is incremented with a positive value every time the configuration is updated and its properties are stored. The counter must be incremented before the targets are updated and events are sent out.

Throws

std::runtime_error -- if this Configuration object has been Removed

Returns

A monotonically increasing value reflecting changes in this Configuration.

virtual std::shared_ptr<ThreadpoolSafeFuture> SafeUpdate(AnyMap properties = AnyMap{AnyMap::UNORDERED_MAP_CASEINSENSITIVE_KEYS}) = 0

Update the properties of this Configuration.

Invoking this method will trigger the ConfigurationAdmin impl to push the updated properties to any ManagedService / ManagedServiceFactory / ConfigurationListener which has a matching PID / Factory PID.

If the properties are empty, the Configuration will not be removed, but instead updated with an empty properties map.

Remark

The shared_ptr<ThreadpoolSafeFuture> returned can contain a cppmicroservices::SecurityException if the Configuration caused a bundle's shared library to be loaded and the bundle failed a security check.

Throws

std::runtime_error -- if this Configuration object has been Removed

Parameters

properties -- The properties to update this Configuration with.

Returns

a shared_ptr<ThreadpoolSafeFuture> which can be used to wait for the asynchronous operation that pushed the update to a ManagedService, ManagedServiceFactory or ConfigurationListener to complete. This can be safely done from the same asyncWorkService on which the update is done. If an exception occurs during the execution of the service component's Modified method, this exception is intercepted and logged by Declarative Services. This exception is not returned in the shared_ptr<ThreadpoolSafeFuture>.

virtual std::shared_future<void> Update(AnyMap properties = AnyMap{AnyMap::UNORDERED_MAP_CASEINSENSITIVE_KEYS}) = 0

Same as SafeUpdate() except:

Returns

a std::shared_future<void> that is unsafe to wait on from within a thread allocated to the AsyncWorkService

virtual std::pair<bool, std::shared_ptr<ThreadpoolSafeFuture>> SafeUpdateIfDifferent(AnyMap properties = AnyMap{AnyMap::UNORDERED_MAP_CASEINSENSITIVE_KEYS}) = 0

Update the properties of this Configuration if they differ from the current properties.

Invoking this method will trigger the ConfigurationAdmin impl to push the updated properties to any ManagedService / ManagedServiceFactory / ConfigurationListener which has a matching PID / Factory PID, but only if the properties differ from the current properties. It will return true in this case, and false otherwise.

If the properties are empty, the Configuration will not be removed, but instead updated with an empty properties map, unless it already had empty properties.

Remark

The shared_ptr<ThreadpoolSafeFuture> returned can contain a cppmicroservices::SecurityException if the Configuration caused a bundle's shared library to be loaded and the bundle failed a security check.

Throws

std::runtime_error -- if this Configuration object has been Removed

Parameters

properties -- The properties to update this Configuration with (if they differ)

Returns

std::pair<boolean, std::shared_ptr<ThreadpoolSafeFuture>> The boolean indicates whether the properties were updated or not. The shared_ptr<ThreadpoolSafeFuture> allows access to the result of the asynchronous operation that pushed the update operation to a ManagedService, ManagedServiceFactory or ConfigurationListener. This can be safely done from the same asyncWorkService on which the update is done. If an exception occurs during the execution of the service component's Modified method, this exception is intercepted and logged by Declarative Services. This exception is not returned in the shared_ptr<ThreadpoolSafeFuture>.

virtual std::pair<bool, std::shared_future<void>> UpdateIfDifferent(AnyMap properties = AnyMap{AnyMap::UNORDERED_MAP_CASEINSENSITIVE_KEYS}) = 0

Same as SafeUpdateIfDifferent() except:

Returns

a std::shared_future<void> that is unsafe to wait on from within a thread allocated to the AsyncWorkService

virtual std::shared_ptr<ThreadpoolSafeFuture> SafeRemove() = 0

Remove this Configuration from ConfigurationAdmin.

This will trigger a push to any ConfigurationListener. This will also trigger the ConfigurationAdmin implementation to update any corresponding ManagedService with an empty AnyMap. Any corresponding ManagedServiceFactory will have its Removed method invoked with the corresponding PID.

Throws

std::runtime_error -- if this Configuration object has been Removed already

Returns

a shared_ptr<ThreadpoolSafeFuture> to access the result of the asynchronous operation that pushed the remove operation to a ManagedService, ManagedServiceFactory or ConfigurationListener. This can be safely done from the same asyncWorkService on which the update is done. If an exception occurs during the execution of the service component's Modified method, this exception is intercepted and logged by Declarative Services. This exception is not returned in the shared_ptr<ThreadpoolSafeFuture>.

virtual std::shared_future<void> Remove() = 0

Same as SafeRemove() except:

Returns

a std::shared_future<void> that is unsafe to wait on from within a thread allocated to the AsyncWorkService

class ConfigurationAdmin

#include <cppmicroservices/cm/ConfigurationAdmin.hpp>

The ConfigurationAdmin interface is the means by which applications and services can interract with the Configuration objects at runtime.

It can be used to create or obtain Configuration objects, which can in turn be queried for their properties or be used to update the properties of a given service or service factory.

Public Functions

virtual ~ConfigurationAdmin() noexcept = default

virtual std::shared_ptr<Configuration> GetConfiguration(std::string const &pid) = 0

Get an existing or new Configuration object.

If the Configuration object for this PID does not exist, create a new Configuration object for that PID with empty properties.

Parameters

pid -- The PID to get the Configuration for

Returns

the Configuration object for this PID

virtual std::shared_ptr<Configuration> CreateFactoryConfiguration(std::string const &factoryPid) = 0

Create a new Configuration object for a ManagedServiceFactory.

The factoryPid is the PID of the ManagedServiceFactory (which must be different from the PIDs of any services it manages) and the instanceName will be a randomly-generated, unique name. The Configuration object's properties are empty. The returned Configuration will have a PID of the form $factoryPid~$instanceName.

Parameters

factoryPid -- The Factory PID to create a new Configuration for

Returns

a new Configuration object for this Factory PID with a randomly-generated unique name

virtual std::shared_ptr<Configuration> GetFactoryConfiguration(std::string const &factoryPid, std::string const &instanceName) = 0

Get an existing or new Configuration object for a ManagedServiceFactory.

The factoryPid is the PID of the ManagedServiceFactory (which must be different from the PIDs of any services it manages) and the instanceName is the unique name of one of those managed services. If the Configuration object for this combination of factoryPid and instanceName does not exist, create a new Configuration object for that combination, where properties are empty. The returned Configuration will have a PID of the form $factoryPid~$instanceName.

Parameters

• factoryPid -- The Factory PID to use to get an existing Configuration or create a new Configuration for
• instanceName -- The unique name of an instance of a serivce managed by the ManagedServiceFactory

Returns

the Configuration object for this combination of Factory PID and instance name

virtual std::vector<std::shared_ptr<Configuration>> ListConfigurations(std::string const &filter = {}) = 0

Used to list all of the available configurations.

An LDAP filter expression can be used to filter based on any property of the configuration, including service.pid and service.factoryPid

Parameters

filter -- An optional filter expression to limit the Configurations which are returned, or empty for all.

Returns

a vector of Configurations matching the filter.

class ConfigurationException : public std::runtime_error

#include <cppmicroservices/cm/ConfigurationException.hpp>

Exception which may be thrown by ManagedService or ManagedServiceFactory subclasses to indicate to the ConfigurationAdmin implementation that the Configuration they have been given is invalid.

The ConfigurationAdmin implementation will log the exception with as much detail as it can. The ConfigurationException class is not final to ensure it can be used with std::throw_with_nested - the ConfigurationAdmin implementation will attempt to print the details of any nested exceptions as well.

Public Functions

inline ConfigurationException(std::string rsn, std::string prop = "")

Construct a new ConfigurationException with the specified reason and optionally specify which property caused the error.

Parameters

• rsn -- The reason for the exception.
• prop -- The property which caused the excpetion, if applicable.

inline std::string GetReason() const

Returns the reason for this exception.

Returns

The reason for this exception.

inline std::string GetProperty() const

Returns the property which was resonsible for this exception being throws, if applicable.

Could be empty.

Returns

The property which caused this exception.

inline virtual ~ConfigurationException() noexcept

enum class ConfigurationEventType

Values:

enumerator CM_UPDATED

The ConfigurationEvent type for when a Configuration object has been updated.

enumerator CM_DELETED

The ConfigurationEvent type for when a Configuration object has been removed.

class ConfigurationEvent

#include <cppmicroservices/cm/ConfigurationListener.hpp>

The ConfigurationEvent object is passed to the ConfigurationListener when the configuration object for any service is updated or removed by ConfigurationAdmin.

Public Functions

inline ConfigurationEvent(ServiceReference<ConfigurationAdmin> configAdmin, const ConfigurationEventType type, std::string factoryPid, std::string pid)

inline ServiceReference<ConfigurationAdmin> const &getReference() const noexcept

Get the ServiceReference object of the Configuration Admin Service that created this event.

Returns

the service reference of this ConfigurationEvent

inline std::string const &getPid() const noexcept

Get the PID of this ConfigurationEvent.

Returns

the PID of this ConfigurationEvent

inline std::string const &getFactoryPid() const noexcept

Get the Factory PID which is responsible for this Configuration.

Returns

the FactoryPID of this ConfigurationEvent

inline ConfigurationEventType getType() const noexcept

Get the type of this Configuration.

Returns

the ConfigurationEventType of this ConfigurationEvent

class ConfigurationListener

#include <cppmicroservices/cm/ConfigurationListener.hpp>

Listener for Configuration Events.

When a ConfigurationEvent is fired, it is asynchronously delivered to all ConfigurationListeners.

ConfigurationListener objects are registered with the Framework service registry and are notified with a ConfigurationEvent object when an event is fired.

ConfigurationListener objects can inspect the received ConfigurationEvent object to determine its type, the pid of the Configuration object with which it is associated, and the Configuration Admin service that fired the event.

ConfigurationAdmin sends updates for all configuration object updates.

Public Functions

virtual void configurationEvent(ConfigurationEvent const &event) = 0

Called whenever the Configuration for any service is updated or removed from ConfigurationAdmin.

Remark

This class is threadsafe

Parameters

ConfigurationEvent -- object containing the ConfigurationAdmin service reference of the ConfigurationAdmin service that updated the configuration object, the PID or FactoryPid for the configuration object and the type of the update operation (update or remove)

virtual ~ConfigurationListener() noexcept = default

class ManagedService

#include <cppmicroservices/cm/ManagedService.hpp>

The ManagedService interface is the interface that services should implement to receive updates from the ConfigurationAdmin implementation with their Configuration.

The Configuration will be provided based on the service.pid ServiceProperty of the Service being registered with the CppMicroServices Framework. If this isn't provided, the component.name property injected by DeclarativeServices will be used instead. If no Configuration is available for either of these, an empty AnyMap will be used to call Updated. Per the OSGi Spec, ManagedService is intended to be used for services which have singleton scope, where there will only be one implementation of a given interface.

Public Functions

virtual ~ManagedService() noexcept = default

virtual void Updated(AnyMap const &properties) = 0

Called whenever the Configuration for this service is updated or removed from ConfigurationAdmin, and when the ManagedService is first registered with the Framework, to provide the initial Configuration.

Can throw a ConfigurationException if there's a problem with the properties. This exception will be logged by the ConfigurationAdminImpl to aid the application author's investigation into the incorrect configuration.

Will be called asynchronously from the Service's registration or an update to the Configuration.

Throws

ConfigurationException -- if something is wrong with the properties provided.

Parameters

properties -- The properties from the new/initial Configuration for this ManagedService

class ManagedServiceFactory

#include <cppmicroservices/cm/ManagedServiceFactory.hpp>

The ManagedServiceFactory interface is the interface that service factories should implement to receive updates from the ConfigurationAdmin implementation with the Configurations for the services that the Factory will provide.

The service.factoryPid ServiceProperty of the ManagedServiceFactory (or the component.name which is injected by DeclarativeServices if no service.factoryPid is provided) will be used to select all Configurations applicable to this factory. Per the OSGi Spec, the ManagedServiceFactory is intended to be used when multiple instances of a given Service will exist in the Framework, but each with different Configurations. For this reason, ManagedServiceFactory implementations are encouraged to mirror any properties (excluding security critical properties) into the ServiceProperty map when publishing the service with the Framework (if it is going to be published). Clients of the service can then filter on the properties they require.

The Updated method will be invoked once for each initial Configuration for this factory and then again whenever any of those Configurations change or whenever any new Configurations for this factory are added.

The Removed method will be invoked whenever any Configuration which this factory has previously been configured with is removed from the ConfigurationAdmin implementation.

Public Functions

virtual ~ManagedServiceFactory() noexcept = default

virtual void Updated(std::string const &pid, AnyMap const &properties) = 0

Called whenever any Configuration for this service factory is updated with ConfigurationAdmin, and (possibly multiple times) when the ManagedServiceFactory is first registered with the Framework.

Can throw a ConfigurationException if there's a problem with the properties. This exception will be logged by the ConfigurationAdminImpl to aid the application author's investigation into the incorrect configuration.

Will be called asynchronously from the Service registration or an update to the Configuration.

The ManagedServiceFactory should update the corresponding service instance with the properties provided, and potentially update the properties of that service's registration with the Framework (if it is registered).

If a corresponding service instance does not exist for this pid, the ManagedServiceFactory should create one with the properties provided. It should also register that new service with the Framework, if applicable.

Throws

ConfigurationException -- if something is wrong with the properties provided.

Parameters

• pid -- The unique pid for this Configuration, of the form "$FACTORY_PID~$INSTANCE_NAME"
• properties -- The properties for this Configuration

virtual void Removed(std::string const &pid) = 0

Called whenever one of the Configurations for this service is removed from ConfigurationAdmin.

Will be called asynchronously from the removal of the Configuration.

The ManagedServiceFactory should remove the corresponding service instance, and if it is registered with the Framework, it should be unregistered.

Parameters

pid -- The unique pid for the Configuration to remove, of the form "$FACTORY_PID~$INSTANCE_NAME"

CppMicroServices Team

2017-2023, CppMicroServices Contributors