KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > cm > ManagedServiceFactory


1 /*
2  * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ManagedServiceFactory.java,v 1.12 2006/07/11 00:54:03 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.cm;
19
20 import java.util.Dictionary JavaDoc;
21
22 /**
23  * Manage multiple service instances.
24  *
25  * Bundles registering this interface are giving the Configuration Admin service
26  * the ability to create and configure a number of instances of a service that
27  * the implementing bundle can provide. For example, a bundle implementing a
28  * DHCP server could be instantiated multiple times for different interfaces
29  * using a factory.
30  *
31  * <p>
32  * Each of these <i>service instances </i> is represented, in the persistent
33  * storage of the Configuration Admin service, by a factory
34  * <code>Configuration</code> object that has a PID. When such a
35  * <code>Configuration</code> is updated, the Configuration Admin service
36  * calls the <code>ManagedServiceFactory</code> updated method with the new
37  * properties. When <code>updated</code> is called with a new PID, the Managed
38  * Service Factory should create a new factory instance based on these
39  * configuration properties. When called with a PID that it has seen before, it
40  * should update that existing service instance with the new configuration
41  * information.
42  *
43  * <p>
44  * In general it is expected that the implementation of this interface will
45  * maintain a data structure that maps PIDs to the factory instances that it has
46  * created. The semantics of a factory instance are defined by the Managed
47  * Service Factory. However, if the factory instance is registered as a service
48  * object with the service registry, its PID should match the PID of the
49  * corresponding <code>Configuration</code> object (but it should <b>not </b>
50  * be registered as a Managed Service!).
51  *
52  * <p>
53  * An example that demonstrates the use of a factory. It will create serial
54  * ports under command of the Configuration Admin service.
55  *
56  * <pre>
57  *
58  * class SerialPortFactory
59  * implements ManagedServiceFactory {
60  * ServiceRegistration registration;
61  * Hashtable ports;
62  * void start(BundleContext context) {
63  * Hashtable properties = new Hashtable();
64  * properties.put( Constants.SERVICE_PID,
65  * &quot;com.acme.serialportfactory&quot; );
66  * registration = context.registerService(
67  * ManagedServiceFactory.class.getName(),
68  * this,
69  * properties
70  * );
71  * }
72  * public void updated( String pid,
73  * Dictionary properties ) {
74  * String portName = (String) properties.get(&quot;port&quot;);
75  * SerialPortService port =
76  * (SerialPort) ports.get( pid );
77  * if ( port == null ) {
78  * port = new SerialPortService();
79  * ports.put( pid, port );
80  * port.open();
81  * }
82  * if ( port.getPortName().equals(portName) )
83  * return;
84  * port.setPortName( portName );
85  * }
86  * public void deleted( String pid ) {
87  * SerialPortService port =
88  * (SerialPort) ports.get( pid );
89  * port.close();
90  * ports.remove( pid );
91  * }
92  * ...
93  * }
94  *
95  * </pre>
96  *
97  * @version $Revision: 1.12 $
98  */
99 public interface ManagedServiceFactory {
100     /**
101      * Return a descriptive name of this factory.
102      *
103      * @return the name for the factory, which might be localized
104      */
105     public String JavaDoc getName();
106
107     /**
108      * Create a new instance, or update the configuration of an existing
109      * instance.
110      *
111      * If the PID of the <code>Configuration</code> object is new for the
112      * Managed Service Factory, then create a new factory instance, using the
113      * configuration <code>properties</code> provided. Else, update the
114      * service instance with the provided <code>properties</code>.
115      *
116      * <p>
117      * If the factory instance is registered with the Framework, then the
118      * configuration <code>properties</code> should be copied to its registry
119      * properties. This is not mandatory and security sensitive properties
120      * should obviously not be copied.
121      *
122      * <p>
123      * If this method throws any <code>Exception</code>, the Configuration
124      * Admin service must catch it and should log it.
125      *
126      * <p>
127      * When the implementation of updated detects any kind of error in the
128      * configuration properties, it should create a new
129      * {@link ConfigurationException} which describes the problem.
130      *
131      * <p>
132      * The Configuration Admin service must call this method asynchronously.
133      * This implies that implementors of the <code>ManagedServiceFactory</code>
134      * class can be assured that the callback will not take place during
135      * registration when they execute the registration in a synchronized method.
136      *
137      * @param pid The PID for this configuration.
138      * @param properties A copy of the configuration properties. This argument
139      * must not contain the service.bundleLocation" property. The value
140      * of this property may be obtained from the
141      * <code>Configuration.getBundleLocation</code> method.
142      * @throws ConfigurationException when the configuration properties are
143      * invalid.
144      */
145     public void updated(String JavaDoc pid, Dictionary JavaDoc properties)
146             throws ConfigurationException;
147
148     /**
149      * Remove a factory instance.
150      *
151      * Remove the factory instance associated with the PID. If the instance was
152      * registered with the service registry, it should be unregistered.
153      * <p>
154      * If this method throws any <code>Exception</code>, the Configuration
155      * Admin service must catch it and should log it.
156      * <p>
157      * The Configuration Admin service must call this method asynchronously.
158      *
159      * @param pid the PID of the service to be removed
160      */
161     public void deleted(String JavaDoc pid);
162 }
163
Popular Tags