org.osgi.service.cm.ManagedService Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2001, 2008). 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 identifier 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: 5673 $
*/
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;
}