/* * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ManagedService.java,v 1.12 2006/06/16 16:31:28 hargrave Exp $ * * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.osgi.service.cm; import java.util.Dictionary; /** * 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,
* 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;
}