Configuration


1   /*
2    * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/Configuration.java,v 1.17 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.io.IOException  ;
21  import java.util.Dictionary  ;
22  
23  /**
24   * The configuration information for a <code>ManagedService</code> or
25   * <code>ManagedServiceFactory</code> object.
26   * 
27   * The Configuration Admin service uses this interface to represent the
28   * configuration information for a <code>ManagedService</code> or for a
29   * service instance of a <code>ManagedServiceFactory</code>.
30   * 
31   * <p>
32   * A <code>Configuration</code> object contains a configuration dictionary and
33   * allows the properties to be updated via this object. Bundles wishing to
34   * receive configuration dictionaries do not need to use this class - they
35   * register a <code>ManagedService</code> or
36   * <code>ManagedServiceFactory</code>. Only administrative bundles, and
37   * bundles wishing to update their own configurations need to use this class.
38   * 
39   * <p>
40   * The properties handled in this configuration have case insensitive
41   * <code>String</code> objects as keys. However, case is preserved from the
42   * last set key/value.
43   * <p>
44   * A configuration can be <i>bound </i> to a bundle location (
45   * <code>Bundle.getLocation()</code>). The purpose of binding a
46   * <code>Configuration</code> object to a location is to make it impossible
47   * for another bundle to forge a PID that would match this configuration. When a
48   * configuration is bound to a specific location, and a bundle with a different
49   * location registers a corresponding <code>ManagedService</code> object or
50   * <code>ManagedServiceFactory</code> object, then the configuration is not
51   * passed to the updated method of that object.
52   * 
53   * <p>
54   * If a configuration's location is <code>null</code>, it is not yet bound to
55   * a location. It will become bound to the location of the first bundle that
56   * registers a <code>ManagedService</code> or
57   * <code>ManagedServiceFactory</code> object with the corresponding PID.
58   * <p>
59   * The same <code>Configuration</code> object is used for configuring both a
60   * Managed Service Factory and a Managed Service. When it is important to
61   * differentiate between these two the term "factory configuration" is used.
62   * 
63   * @version $Revision: 1.17 $
64   */
65  public interface Configuration {
66      /**
67       * Get the PID for this <code>Configuration</code> object.
68       * 
69       * @return the PID for this <code>Configuration</code> object.
70       * @throws IllegalStateException if this configuration has been deleted
71       */
72      public String   getPid();
73  
74      /**
75       * Return the properties of this <code>Configuration</code> object.
76       * 
77       * The <code>Dictionary</code> object returned is a private copy for the
78       * caller and may be changed without influencing the stored configuration.
79       * The keys in the returned dictionary are case insensitive and are always
80       * of type <code>String</code>.
81       * 
82       * <p>
83       * If called just after the configuration is created and before update has
84       * been called, this method returns <code>null</code>.
85       * 
86       * @return A private copy of the properties for the caller or
87       *         <code>null</code>. These properties must not contain the
88       *         "service.bundleLocation" property. The value of this property may
89       *         be obtained from the <code>getBundleLocation</code> method.
90       * @throws IllegalStateException if this configuration has been deleted
91       */
92      public Dictionary   getProperties();
93  
94      /**
95       * Update the properties of this <code>Configuration</code> object.
96       * 
97       * Stores the properties in persistent storage after adding or overwriting
98       * the following properties:
99       * <ul>
100      * <li>"service.pid" : is set to be the PID of this configuration.</li>
101      * <li>"service.factoryPid" : if this is a factory configuration it is set
102      * to the factory PID else it is not set.</li>
103      * </ul>
104      * These system properties are all of type <code>String</code>.
105      * 
106      * <p>
107      * If the corresponding Managed Service/Managed Service Factory is
108      * registered, its updated method must be called asynchronously. Else, this
109      * callback is delayed until aforementioned registration occurs.
110      * 
111      * <p>
112      * Also intiates an asynchronous call to all
113      * <code>ConfigurationListener</code>s with a
114      * <code>ConfigurationEvent.CM_UPDATED</code> event.
115      * 
116      * @param properties the new set of properties for this configuration
117      * @throws IOException if update cannot be made persistent
118      * @throws IllegalArgumentException if the <code>Dictionary</code> object
119      *         contains invalid configuration types or contains case variants of
120      *         the same key name.
121      * @throws IllegalStateException if this configuration has been deleted
122      */
123     public void update(Dictionary   properties) throws IOException  ;
124 
125     /**
126      * Delete this <code>Configuration</code> object.
127      * 
128      * Removes this configuration object from the persistent store. Notify
129      * asynchronously the corresponding Managed Service or Managed Service
130      * Factory. A <code>ManagedService</code> object is notified by a call to
131      * its <code>updated</code> method with a <code>null</code> properties
132      * argument. A <code>ManagedServiceFactory</code> object is notified by a
133      * call to its <code>deleted</code> method.
134      * 
135      * <p>
136      * Also intiates an asynchronous call to all
137      * <code>ConfigurationListener</code>s with a
138      * <code>ConfigurationEvent.CM_DELETED</code> event.
139      * 
140      * @throws IOException If delete fails
141      * @throws IllegalStateException if this configuration has been deleted
142      */
143     public void delete() throws IOException  ;
144 
145     /**
146      * For a factory configuration return the PID of the corresponding Managed
147      * Service Factory, else return <code>null</code>.
148      * 
149      * @return factory PID or <code>null</code>
150      * @throws IllegalStateException if this configuration has been deleted
151      */
152     public String   getFactoryPid();
153 
154     /**
155      * Update the <code>Configuration</code> object with the current
156      * properties.
157      * 
158      * Initiate the <code>updated</code> callback to the Managed Service or
159      * Managed Service Factory with the current properties asynchronously.
160      * 
161      * <p>
162      * This is the only way for a bundle that uses a Configuration Plugin
163      * service to initate a callback. For example, when that bundle detects a
164      * change that requires an update of the Managed Service or Managed Service
165      * Factory via its <code>ConfigurationPlugin</code> object.
166      * 
167      * @see ConfigurationPlugin
168      * @throws IOException if update cannot access the properties in persistent
169      *         storage
170      * @throws IllegalStateException if this configuration has been deleted
171      */
172     public void update() throws IOException  ;
173 
174     /**
175      * Bind this <code>Configuration</code> object to the specified bundle
176      * location.
177      * 
178      * If the bundleLocation parameter is <code>null</code> then the
179      * <code>Configuration</code> object will not be bound to a location. It
180      * will be set to the bundle's location before the first time a Managed
181      * Service/Managed Service Factory receives this <code>Configuration</code>
182      * object via the updated method and before any plugins are called. The
183      * bundle location will be set persistently.
184      * 
185      * @param bundleLocation a bundle location or <code>null</code>
186      * @throws IllegalStateException If this configuration has been deleted.
187      * @throws SecurityException If the caller does not have
188      *         <code>ConfigurationPermission[*,CONFIGURE]</code>.
189      */
190     public void setBundleLocation(String   bundleLocation);
191 
192     /**
193      * Get the bundle location.
194      * 
195      * Returns the bundle location to which this configuration is bound, or
196      * <code>null</code> if it is not yet bound to a bundle location.
197      * 
198      * @return location to which this configuration is bound, or
199      *         <code>null</code>.
200      * @throws IllegalStateException If this <code>Configuration</code> object
201      *         has been deleted.
202      * @throws SecurityException If the caller does not have
203      *         <code>ConfigurationPermission[*,CONFIGURE]</code>.
204      */
205     public String   getBundleLocation();
206 
207     /**
208      * Equality is defined to have equal PIDs
209      * 
210      * Two Configuration objects are equal when their PIDs are equal.
211      * 
212      * @param other <code>Configuration</code> object to compare against
213      * @return <code>true</code> if equal, <code>false</code> if not a
214      *         <code>Configuration</code> object or one with a different PID.
215      */
216     public boolean equals(Object   other);
217 
218     /**
219      * Hash code is based on PID.
220      * 
221      * The hashcode for two Configuration objects must be the same when the
222      * Configuration PID's are the same.
223      * 
224      * @return hash code for this Configuration object
225      */
226     public int hashCode();
227 }
228
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags