* 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,
* getDefaults()
* );
* }
*
* 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.12 $ */ 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
*/
public void updated(Dictionary properties) throws ConfigurationException;
}