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 identitifier called a PID. * *
If the Configuration Admin service has a Configuration object corresponding * to this PID, it will callback the updated() method of the ManagedService object, * passing the properties of that Configuration object. * *
If it has no such Configuration object, then it calls * back with a null 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 Configuration object, the ManagedService.updated() method with the * new properties is called. If the delete() method is * called on that Configuration object, ManagedService.updated() is called with * a null 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 implements ManagedService {
*
* ServiceRegistration registration;
* Hashtable configuration;
* CommPortIdentifier id;
*
* synchronized void open(CommPortIdentifier id,
* BundleContext context) {
* this.id = id;
* registration = context.registerService(
* ManagedService.class.getName(),
* this,
* null // Properties will come from CM in updated
* );
* }
*
* Hashtable getDefaults() {
* Hashtable defaults = new Hashtable();
* defaults.put( "port", id.getName() );
* defaults.put( "product", "unknown" );
* defaults.put( "baud", "9600" );
* defaults.put( Constants.SERVICE_PID,
* "com.acme.serialport." + id.getName() );
* return defaults;
* }
*
* public synchronized void updated(
* Dictionary configuration ) {
* if ( configuration == null )
* registration.setProperties( getDefaults() );
* else {
* setSpeed( configuration.get("baud") );
* registration.setProperties( configuration );
* }
* }
* ...
* }
*
* 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. * * @version $Revision: 1.1.1.1 $ * @author Open Services Gateway Initiative */ public interface ManagedService { /** * Update the configuration for a Managed Service. * *
When the implementation of updated(Dictionary) detects any kind of * error in the configuration properties, it should create a * new ConfigurationException 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. * * @param properties A copy of the Configuration properties, or null. * This argument must not contain the * "service.bundleLocation" property. The value of this property * may be obtained from the Configuration.getBundleLocation method. * @throws ConfigurationException when the update fails */ void updated( Dictionary properties ) throws ConfigurationException; }