Interface ManagedService
-
@ConsumerType 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 identifier called a PID.If the Configuration Admin service has a
Configuration
object corresponding to this PID, it will callback theupdated()
method of theManagedService
object, passing the properties of thatConfiguration
object.If it has no such
Configuration
object, then it calls back with anull
properties argument. Registering a Managed Service will always result in a callback to theupdated()
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 thatConfiguration
object, theManagedService.updated()
method with the new properties is called. If thedelete()
method is called on thatConfiguration
object,ManagedService.updated()
is called with anull
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.
Normally, a single Managed Service for a given PID is given the configuration dictionary, this is the configuration that is bound to the location of the registering bundle. However, when security is on, a Managed Service can have Configuration Permission to also be updated for other locations.
If a Managed Service is registered without the
service.pid
property, it will be ignored.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
updated(java.util.Dictionary<java.lang.String,?> properties)
Update the configuration for a Managed Service.
-
-
-
Method Detail
-
updated
void updated(java.util.Dictionary<java.lang.String,?> 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 newConfigurationException
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 with the method that 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.
If the location allows multiple managed services to be called back for a single configuration then the callbacks must occur in service ranking order. Changes in the location must be reflected by deleting the configuration if the configuration is no longer visible and updating when it becomes visible.
If no configuration exists for the corresponding PID, or the bundle has no access to the configuration, then the bundle must be called back with a
null
to signal that CM is active but there is no data.- Parameters:
properties
- A copy of the Configuration properties, ornull
. This argument must not contain the "service.bundleLocation" property. The value of this property may be obtained from theConfiguration.getBundleLocation
method.- Throws:
ConfigurationException
- when the update fails
-
-