Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.osgi.service.cm
Interface ManagedService

public interface ManagedService

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 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.

Method Summary
`void` | `updated(java.util.Dictionary properties)` Update the configuration for a Managed Service.

Method Detail

### updated

    public void updated(java.util.Dictionary properties)
                 throws ConfigurationException

  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.

  Parameters:
    `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

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.