ConfigurationAdmin


1   /*
2    * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.16 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.io.IOException  ;
21  import java.util.Dictionary  ;
22  
23  import org.osgi.framework.InvalidSyntaxException;
24  
25  /**
26   * Service for administering configuration data.
27   * 
28   * <p>
29   * The main purpose of this interface is to store bundle configuration data
30   * persistently. This information is represented in <code>Configuration</code>
31   * objects. The actual configuration data is a <code>Dictionary</code> of
32   * properties inside a <code>Configuration</code> object.
33   * 
34   * <p>
35   * There are two principally different ways to manage configurations. First
36   * there is the concept of a Managed Service, where configuration data is
37   * uniquely associated with an object registered with the service registry.
38   * 
39   * <p>
40   * Next, there is the concept of a factory where the Configuration Admin service
41   * will maintain 0 or more <code>Configuration</code> objects for a Managed
42   * Service Factory that is registered with the Framework.
43   * 
44   * <p>
45   * The first concept is intended for configuration data about "things/services"
46   * whose existence is defined externally, e.g. a specific printer. Factories are
47   * intended for "things/services" that can be created any number of times, e.g.
48   * a configuration for a DHCP server for different networks.
49   * 
50   * <p>
51   * Bundles that require configuration should register a Managed Service or a
52   * Managed Service Factory in the service registry. A registration property
53   * named <code>service.pid</code> (persistent identifier or PID) must be used
54   * to identify this Managed Service or Managed Service Factory to the
55   * Configuration Admin service.
56   * 
57   * <p>
58   * When the ConfigurationAdmin detects the registration of a Managed Service, it
59   * checks its persistent storage for a configuration object whose PID matches
60   * the PID registration property (<code>service.pid</code>) of the Managed
61   * Service. If found, it calls {@link ManagedService#updated} method with the
62   * new properties. The implementation of a Configuration Admin service must run
63   * these call-backs asynchronously to allow proper synchronization.
64   * 
65   * <p>
66   * When the Configuration Admin service detects a Managed Service Factory
67   * registration, it checks its storage for configuration objects whose
68   * <code>factoryPid</code> matches the PID of the Managed Service Factory. For
69   * each such <code>Configuration</code> objects, it calls the
70   * <code>ManagedServiceFactory.updated</code> method asynchronously with the
71   * new properties. The calls to the <code>updated</code> method of a
72   * <code>ManagedServiceFactory</code> must be executed sequentially and not
73   * overlap in time.
74   * 
75   * <p>
76   * In general, bundles having permission to use the Configuration Admin service
77   * can only access and modify their own configuration information. Accessing or
78   * modifying the configuration of another bundle requires
79   * <code>ConfigurationPermission[*,CONFIGURE]</code>.
80   * 
81   * <p>
82   * <code>Configuration</code> objects can be <i>bound </i> to a specified
83   * bundle location. In this case, if a matching Managed Service or Managed
84   * Service Factory is registered by a bundle with a different location, then the
85   * Configuration Admin service must not do the normal callback, and it should
86   * log an error. In the case where a <code>Configuration</code> object is not
87   * bound, its location field is <code>null</code>, the Configuration Admin
88   * service will bind it to the location of the bundle that registers the first
89   * Managed Service or Managed Service Factory that has a corresponding PID
90   * property. When a <code>Configuration</code> object is bound to a bundle
91   * location in this manner, the Confguration Admin service must detect if the
92   * bundle corresponding to the location is uninstalled. If this occurs, the
93   * <code>Configuration</code> object is unbound, that is its location field is
94   * set back to <code>null</code>.
95   * 
96   * <p>
97   * The method descriptions of this class refer to a concept of "the calling
98   * bundle". This is a loose way of referring to the bundle which obtained the
99   * Configuration Admin service from the service registry. Implementations of
100  * <code>ConfigurationAdmin</code> must use a
101  * {@link org.osgi.framework.ServiceFactory} to support this concept.
102  * 
103  * @version $Revision: 1.16 $
104  */
105 public interface ConfigurationAdmin {
106     /**
107      * Service property naming the Factory PID in the configuration dictionary.
108      * The property's value is of type <code>String</code>.
109      * 
110      * @since 1.1
111      */
112     public final static String    SERVICE_FACTORYPID      = "service.factoryPid";
113     /**
114      * Service property naming the location of the bundle that is associated
115      * with a a <code>Configuration</code> object. This property can be
116      * searched for but must not appear in the configuration dictionary for
117      * security reason. The property's value is of type <code>String</code>.
118      * 
119      * @since 1.1
120      */
121     public final static String    SERVICE_BUNDLELOCATION  = "service.bundleLocation";
122 
123     /**
124      * Create a new factory <code>Configuration</code> object with a new PID.
125      * 
126      * The properties of the new <code>Configuration</code> object are
127      * <code>null</code> until the first time that its
128      * {@link Configuration#update(Dictionary)} method is called.
129      * 
130      * <p>
131      * It is not required that the <code>factoryPid</code> maps to a
132      * registered Managed Service Factory.
133      * <p>
134      * The <code>Configuration</code> object is bound to the location of the
135      * calling bundle.
136      * 
137      * @param factoryPid PID of factory (not <code>null</code>).
138      * @return A new <code>Configuration</code> object.
139      * @throws IOException if access to persistent storage fails.
140      * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code> and <code>factoryPid</code> is bound to another bundle.
141      */
142     public Configuration createFactoryConfiguration(String   factoryPid)
143             throws IOException  ;
144 
145     /**
146      * Create a new factory <code>Configuration</code> object with a new PID.
147      * 
148      * The properties of the new <code>Configuration</code> object are
149      * <code>null</code> until the first time that its
150      * {@link Configuration#update(Dictionary)} method is called.
151      * 
152      * <p>
153      * It is not required that the <code>factoryPid</code> maps to a
154      * registered Managed Service Factory.
155      * 
156      * <p>
157      * The <code>Configuration</code> is bound to the location specified. If
158      * this location is <code>null</code> it will be bound to the location of
159      * the first bundle that registers a Managed Service Factory with a
160      * corresponding PID.
161      * 
162      * @param factoryPid PID of factory (not <code>null</code>).
163      * @param location A bundle location string, or <code>null</code>.
164      * @return a new <code>Configuration</code> object.
165      * @throws IOException if access to persistent storage fails.
166      * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
167      */
168     public Configuration createFactoryConfiguration(String   factoryPid, String   location)
169             throws IOException  ;
170 
171     /**
172      * Get an existing <code>Configuration</code> object from the persistent
173      * store, or create a new <code>Configuration</code> object.
174      * 
175      * <p>
176      * If a <code>Configuration</code> with this PID already exists in
177      * Configuration Admin service return it. The location parameter is ignored
178      * in this case.
179      * 
180      * <p>
181      * Else, return a new <code>Configuration</code> object. This new object
182      * is bound to the location and the properties are set to <code>null</code>.
183      * If the location parameter is <code>null</code>, it will be set when a
184      * Managed Service with the corresponding PID is registered for the first
185      * time.
186      * 
187      * @param pid Persistent identifier.
188      * @param location The bundle location string, or <code>null</code>.
189      * @return An existing or new <code>Configuration</code> object.
190      * @throws IOException if access to persistent storage fails.
191      * @throws SecurityException if the caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
192      */
193     public Configuration getConfiguration(String   pid, String   location)
194             throws IOException  ;
195 
196     /**
197      * Get an existing or new <code>Configuration</code> object from the
198      * persistent store.
199      * 
200      * If the <code>Configuration</code> object for this PID does not exist,
201      * create a new <code>Configuration</code> object for that PID, where
202      * properties are <code>null</code>. Bind its location to the calling
203      * bundle's location.
204      * 
205      * <p>
206      * Otherwise, if the location of the existing <code>Configuration</code> object
207      * is <code>null</code>, set it to the calling bundle's location.
208      * 
209      * @param pid persistent identifier.
210      * @return an existing or new <code>Configuration</code> matching the PID.
211      * @throws IOException if access to persistent storage fails.
212      * @throws SecurityException if the <code>Configuration</code> object is bound to a location different from that of the calling bundle and it has no <code>ConfigurationPermission[*,CONFIGURE]</code>.
213      */
214     public Configuration getConfiguration(String   pid) throws IOException  ;
215 
216     /**
217      * List the current <code>Configuration</code> objects which match the
218      * filter.
219      * 
220      * <p>
221      * Only <code>Configuration</code> objects with non- <code>null</code>
222      * properties are considered current. That is,
223      * <code>Configuration.getProperties()</code> is guaranteed not to return
224      * <code>null</code> for each of the returned <code>Configuration</code>
225      * objects.
226      * 
227      * <p>
228      * Normally only <code>Configuration</code> objects that are bound to the
229      * location of the calling bundle are returned, or all if the caller has 
230      * <code>ConfigurationPermission[*,CONFIGURE]</code>.
231      * 
232      * <p>
233      * The syntax of the filter string is as defined in the <code>Filter</code>
234      * class. The filter can test any configuration parameters including the
235      * following system properties:
236      * <ul>
237      * <li><code>service.pid</code>-<code>String</code>- the PID under
238      * which this is registered</li>
239      * <li><code>service.factoryPid</code>-<code>String</code>- the
240      * factory if applicable</li>
241      * <li><code>service.bundleLocation</code>-<code>String</code>- the
242      * bundle location</li>
243      * </ul>
244      * The filter can also be <code>null</code>, meaning that all
245      * <code>Configuration</code> objects should be returned.
246      * 
247      * @param filter a <code>Filter</code> object, or <code>null</code> to
248      *        retrieve all <code>Configuration</code> objects.
249      * @return all matching <code>Configuration</code> objects, or
250      *         <code>null</code> if there aren't any
251      * @throws IOException if access to persistent storage fails
252      * @throws InvalidSyntaxException if the filter string is invalid
253      */
254     public Configuration[] listConfigurations(String   filter) throws IOException  ,
255             InvalidSyntaxException;
256 }
257
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags