CTK  0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
Public Member Functions | List of all members
ctkManagedService Struct Referenceabstract

#include <Libs/PluginFramework/service/cm/ctkManagedService.h>

Public Member Functions

virtual void updated (const ctkDictionary &properties)=0
 
virtual ~ctkManagedService ()
 

Detailed Description

A service that can receive configuration data from a Configuration Admin service.

A Managed Service is a service that needs configuration data. Such an object should be registered with the Framework registry with the service.pid property set to some unique identifier called a PID.

If the Configuration Admin service has a ctkConfiguration object corresponding to this PID, it will callback the updated() method of the ctkManagedService object, passing the properties of that ctkConfiguration object.

If it has no such ctkConfiguration object, then it calls back with an empty properties argument. Registering a Managed Service will always result in a callback to the updated() method provided the Configuration Admin service is, or becomes active. This callback must always be done asynchronously.

Else, every time that either of the updated() methods is called on that ctkConfiguration object, the ctkManagedService::updated() method with the new properties is called. If the remove() method is called on that ctkConfiguration object, ctkManagedService::updated() is called with an empty map for the properties parameter. All these callbacks must be done asynchronously.

The following example shows the code of a serial port that will create a port depending on configuration information.

class SerialPort : public QObject, public ctkManagedService
{
QMutex mutex;
ctkServiceRegistration registration;
Hashtable configuration;
CommPortIdentifier id;
void open(CommPortIdentifier id, ctkPluginContext* context)
{
QMutexLocker lock(&mutex);
this->id = id;
registration = context->registerService<ctkManagedService>(
this, getDefaults());
}
ctkDictionary getDefaults()
{
ctkDictionary defaults;
defaults.insert("port", id.getName());
defaults.insert("product", "unknown");
defaults.insert("baud", 9600);
QString("com.acme.serialport.") + id.getName());
return defaults;
}
public:
void updated(const ctkDictionary& configuration)
{
QMutexLocker lock(&mutex);
if (configuration.isEmpty())
{
registration.setProperties(getDefaults());
}
else
{
setSpeed(configuration["baud"].toInt());
registration.setProperties(configuration);
}
}
...
};
ctkServiceRegistration registerService(const QStringList &clazzes, QObject *service, const ctkDictionary &properties=ctkDictionary())
void setProperties(const ctkDictionary &properties)
virtual void updated(const ctkDictionary &properties)=0
static const QString SERVICE_PID

As a convention, it is recommended that when a Managed Service is updated, it should copy all the properties it does not recognize into the service registration properties. This will allow the Configuration Admin service to set properties on services which can then be used by other applications.

Definition at line 122 of file ctkManagedService.h.

Constructor & Destructor Documentation

◆ ~ctkManagedService()

virtual ctkManagedService::~ctkManagedService ( )
inlinevirtual

Definition at line 124 of file ctkManagedService.h.

Member Function Documentation

◆ updated()

virtual void ctkManagedService::updated ( const ctkDictionary properties)
pure virtual

Update the configuration for a Managed Service.

When the implementation of updated(const ctkDictionary&) detects any kind of error in the configuration properties, it should create a new ctkConfigurationException which describes the problem. This can allow a management system to provide useful information to a human administrator.

If this method throws any other exception, the Configuration Admin service must catch it and should log it.

The Configuration Admin service must call this method asynchronously which initiated the callback. This implies that implementors of Managed Service can be assured that the callback will not take place during registration when they execute the registration in a synchronized method.

Parameters
propertiesA copy of the ctkConfiguration properties. This argument must not contain the "service.pluginLocation" property. The value of this property may be obtained from the ctkConfiguration::getPluginLocation() method.
Exceptions
ctkConfigurationExceptionwhen the update fails

The documentation for this struct was generated from the following file: