KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * $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 $
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  * A service that can receive configuration data from a Configuration Admin
24  * service.
25  *
26  * <p>
27  * A Managed Service is a service that needs configuration data. Such an object
28  * should be registered with the Framework registry with the
29  * <code>service.pid</code> property set to some unique identitifier called a
30  * PID.
31  *
32  * <p>
33  * If the Configuration Admin service has a <code>Configuration</code> object
34  * corresponding to this PID, it will callback the <code>updated()</code>
35  * method of the <code>ManagedService</code> object, passing the properties of
36  * that <code>Configuration</code> object.
37  *
38  * <p>
39  * If it has no such <code>Configuration</code> object, then it calls back
40  * with a <code>null</code> properties argument. Registering a Managed Service
41  * will always result in a callback to the <code>updated()</code> method
42  * provided the Configuration Admin service is, or becomes active. This callback
43  * must always be done asynchronously.
44  *
45  * <p>
46  * Else, every time that either of the <code>updated()</code> methods is
47  * called on that <code>Configuration</code> object, the
48  * <code>ManagedService.updated()</code> method with the new properties is
49  * called. If the <code>delete()</code> method is called on that
50  * <code>Configuration</code> object, <code>ManagedService.updated()</code>
51  * is called with a <code>null</code> for the properties parameter. All these
52  * callbacks must be done asynchronously.
53  *
54  * <p>
55  * The following example shows the code of a serial port that will create a port
56  * depending on configuration information.
57  *
58  * <pre>
59  *
60  * class SerialPort implements ManagedService {
61  *
62  * ServiceRegistration registration;
63  * Hashtable configuration;
64  * CommPortIdentifier id;
65  *
66  * synchronized void open(CommPortIdentifier id,
67  * BundleContext context) {
68  * this.id = id;
69  * registration = context.registerService(
70  * ManagedService.class.getName(),
71  * this,
72  * getDefaults()
73  * );
74  * }
75  *
76  * Hashtable getDefaults() {
77  * Hashtable defaults = new Hashtable();
78  * defaults.put( &quot;port&quot;, id.getName() );
79  * defaults.put( &quot;product&quot;, &quot;unknown&quot; );
80  * defaults.put( &quot;baud&quot;, &quot;9600&quot; );
81  * defaults.put( Constants.SERVICE_PID,
82  * &quot;com.acme.serialport.&quot; + id.getName() );
83  * return defaults;
84  * }
85  *
86  * public synchronized void updated(
87  * Dictionary configuration ) {
88  * if ( configuration ==
89  * <code>
90  * null
91  * </code>
92  * )
93  * registration.setProperties( getDefaults() );
94  * else {
95  * setSpeed( configuration.get(&quot;baud&quot;) );
96  * registration.setProperties( configuration );
97  * }
98  * }
99  * ...
100  * }
101  *
102  * </pre>
103  *
104  * <p>
105  * As a convention, it is recommended that when a Managed Service is updated, it
106  * should copy all the properties it does not recognize into the service
107  * registration properties. This will allow the Configuration Admin service to
108  * set properties on services which can then be used by other applications.
109  *
110  * @version $Revision: 1.12 $
111  */
112 public interface ManagedService {
113     /**
114      * Update the configuration for a Managed Service.
115      *
116      * <p>
117      * When the implementation of <code>updated(Dictionary)</code> detects any
118      * kind of error in the configuration properties, it should create a new
119      * <code>ConfigurationException</code> which describes the problem. This
120      * can allow a management system to provide useful information to a human
121      * administrator.
122      *
123      * <p>
124      * If this method throws any other <code>Exception</code>, the
125      * Configuration Admin service must catch it and should log it.
126      * <p>
127      * The Configuration Admin service must call this method asynchronously
128      * which initiated the callback. This implies that implementors of Managed
129      * Service can be assured that the callback will not take place during
130      * registration when they execute the registration in a synchronized method.
131      *
132      * @param properties A copy of the Configuration properties, or
133      * <code>null</code>. This argument must not contain the
134      * "service.bundleLocation" property. The value of this property may
135      * be obtained from the <code>Configuration.getBundleLocation</code>
136      * method.
137      * @throws ConfigurationException when the update fails
138      */
139     public void updated(Dictionary JavaDoc properties) throws ConfigurationException;
140 }
141
Popular Tags