Each of these service instances is represented, in the persistent * storage of the Configuration Admin service, by a factory Configuration object that * has a PID. When such a Configuration is updated, the Configuration Admin service * calls the ManagedServiceFactory updated method with the new * properties. When updated is called with a new PID, the Managed Service Factory * should create a new factory instance based on these * configuration properties. When called with a * PID that it has seen before, it should update that existing service * instance with the new configuration information. * *
In general it is expected that the implementation of this * interface will maintain a data structure that maps PIDs to the * factory instances that it has created. The semantics of a * factory instance are defined by the Managed Service Factory. * However, if the factory instance is registered as a service object with the * service registry, its PID should match the PID of the corresponding * Configuration object (but it should not be registered * as a Managed Service!). * *
An example that demonstrates the use of a factory. It will * create serial ports under command of the Configuration Admin service. *
* class SerialPortFactory
* implements ManagedServiceFactory {
* ServiceRegistration registration;
* Hashtable ports;
* void start(BundleContext context) {
* Hashtable properties = new Hashtable();
* properties.put( Constants.SERVICE_PID,
* "com.acme.serialportfactory" );
* registration = context.registerService(
* ManagedServiceFactory.class.getName(),
* this,
* properties
* );
* }
* public void updated( String pid,
* Dictionary properties ) {
* String portName = (String) properties.get("port");
* SerialPortService port =
* (SerialPort) ports.get( pid );
* if ( port == null ) {
* port = new SerialPortService();
* ports.put( pid, port );
* port.open();
* }
* if ( port.getPortName().equals(portName) )
* return;
* port.setPortName( portName );
* }
* public void deleted( String pid ) {
* SerialPortService port =
* (SerialPort) ports.get( pid );
* port.close();
* ports.remove( pid );
* }
* ...
* }
*
*
* @version $Revision: 1.1.1.1 $
* @author Open Services Gateway Initiative
*/
public interface ManagedServiceFactory {
/**
* Return a descriptive name of this factory.
*
* @return the name for the factory, which might be localized
*/
String getName();
/**
* Create a new instance, or update the configuration of an
* existing instance.
*
* If the PID of the Configuration object is new for the Managed Service Factory,
* then create a new factory instance, using the configuration
* properties provided. Else, update the service instance with the
* provided properties.
*
* If the factory instance is registered with the Framework, then * the configuration properties should be copied to its registry * properties. This is not mandatory and * security sensitive properties should obviously not be copied. * *
If this method throws any Exception, the * Configuration Admin service must catch it and should log it. * *
When the implementation of updated detects any kind of * error in the configuration properties, it should create a * new {@link ConfigurationException} which describes the problem. * *
The Configuration Admin service must call this method asynchronously. This implies that * implementors of the ManagedServiceFactory class can be assured that the * callback will not take place during registration when they * execute the registration in a synchronized method. * * @param pid The PID for this configuration. * @param properties A copy of the configuration properties. * 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 configuration properties are invalid. */ void updated( String pid, Dictionary properties ) throws ConfigurationException; /** * Remove a factory instance. * * Remove the factory instance associated with the PID. If the instance was * registered with the service registry, it should be unregistered. *
If this method throws any Exception, the Configuration Admin * service must catch it and should log it. *
The Configuration Admin service must call this method asynchronously. * * @param pid the PID of the service to be removed */ void deleted( String pid ); }