|
86
|
1 /*
|
|
|
2 * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.22 2007/02/21 16:49:05 hargrave Exp $
|
|
105
|
3 *
|
|
86
|
4 * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
|
|
105
|
5 *
|
|
86
|
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
|
|
105
|
19 // Port to the D programming language:
|
|
|
20 // Frank Benoit <benoit@tionex.de>
|
|
86
|
21 module org.osgi.framework.BundleContext;
|
|
|
22
|
|
|
23 import java.lang.all;
|
|
105
|
24
|
|
|
25 import org.osgi.framework.BundleListener; // packageimport
|
|
|
26 import org.osgi.framework.BundleException; // packageimport
|
|
|
27 import org.osgi.framework.ServiceListener; // packageimport
|
|
|
28 import org.osgi.framework.InvalidSyntaxException; // packageimport
|
|
|
29 import org.osgi.framework.ServiceRegistration; // packageimport
|
|
|
30 import org.osgi.framework.ServiceReference; // packageimport
|
|
|
31 import org.osgi.framework.Bundle; // packageimport
|
|
|
32 import org.osgi.framework.Filter; // packageimport
|
|
|
33 import org.osgi.framework.FrameworkListener; // packageimport
|
|
|
34
|
|
86
|
35 import java.io.File;
|
|
|
36 import java.io.InputStream;
|
|
|
37 import java.util.Dictionary;
|
|
|
38
|
|
|
39 /**
|
|
|
40 * A bundle's execution context within the Framework. The context is used to
|
|
|
41 * grant access to other methods so that this bundle can interact with the
|
|
|
42 * Framework.
|
|
105
|
43 *
|
|
86
|
44 * <p>
|
|
|
45 * <code>BundleContext</code> methods allow a bundle to:
|
|
|
46 * <ul>
|
|
|
47 * <li>Subscribe to events published by the Framework.
|
|
|
48 * <li>Register service objects with the Framework service registry.
|
|
|
49 * <li>Retrieve <code>ServiceReferences</code> from the Framework service
|
|
|
50 * registry.
|
|
|
51 * <li>Get and release service objects for a referenced service.
|
|
|
52 * <li>Install new bundles in the Framework.
|
|
|
53 * <li>Get the list of bundles installed in the Framework.
|
|
|
54 * <li>Get the {@link Bundle} object for a bundle.
|
|
|
55 * <li>Create <code>File</code> objects for files in a persistent storage
|
|
|
56 * area provided for the bundle by the Framework.
|
|
|
57 * </ul>
|
|
105
|
58 *
|
|
86
|
59 * <p>
|
|
|
60 * A <code>BundleContext</code> object will be created and provided to the
|
|
|
61 * bundle associated with this context when it is started using the
|
|
|
62 * {@link BundleActivator#start} method. The same <code>BundleContext</code>
|
|
|
63 * object will be passed to the bundle associated with this context when it is
|
|
|
64 * stopped using the {@link BundleActivator#stop} method. A
|
|
|
65 * <code>BundleContext</code> object is generally for the private use of its
|
|
|
66 * associated bundle and is not meant to be shared with other bundles in the
|
|
|
67 * OSGi environment.
|
|
105
|
68 *
|
|
86
|
69 * <p>
|
|
|
70 * The <code>Bundle</code> object associated with a <code>BundleContext</code>
|
|
|
71 * object is called the <em>context bundle</em>.
|
|
105
|
72 *
|
|
86
|
73 * <p>
|
|
|
74 * The <code>BundleContext</code> object is only valid during the execution of
|
|
|
75 * its context bundle; that is, during the period from when the context bundle
|
|
|
76 * is in the <code>STARTING</code>, <code>STOPPING</code>, and
|
|
|
77 * <code>ACTIVE</code> bundle states. If the <code>BundleContext</code>
|
|
|
78 * object is used subsequently, an <code>IllegalStateException</code> must be
|
|
|
79 * thrown. The <code>BundleContext</code> object must never be reused after
|
|
|
80 * its context bundle is stopped.
|
|
105
|
81 *
|
|
86
|
82 * <p>
|
|
|
83 * The Framework is the only entity that can create <code>BundleContext</code>
|
|
|
84 * objects and they are only valid within the Framework that created them.
|
|
105
|
85 *
|
|
86
|
86 * @ThreadSafe
|
|
|
87 * @version $Revision: 1.22 $
|
|
|
88 */
|
|
|
89
|
|
|
90 public interface BundleContext {
|
|
|
91 /**
|
|
|
92 * Returns the value of the specified property. If the key is not found in
|
|
|
93 * the Framework properties, the system properties are then searched. The
|
|
|
94 * method returns <code>null</code> if the property is not found.
|
|
105
|
95 *
|
|
86
|
96 * <p>
|
|
|
97 * The Framework defines the following standard property keys:
|
|
|
98 * </p>
|
|
|
99 * <ul>
|
|
|
100 * <li>{@link Constants#FRAMEWORK_VERSION} - The OSGi Framework version.
|
|
|
101 * </li>
|
|
|
102 * <li>{@link Constants#FRAMEWORK_VENDOR} - The Framework implementation
|
|
|
103 * vendor.</li>
|
|
|
104 * <li>{@link Constants#FRAMEWORK_LANGUAGE} - The language being used. See
|
|
|
105 * ISO 639 for possible values.</li>
|
|
|
106 * <li>{@link Constants#FRAMEWORK_OS_NAME} - The host computer operating
|
|
|
107 * system.</li>
|
|
|
108 * <li>{@link Constants#FRAMEWORK_OS_VERSION} - The host computer
|
|
|
109 * operating system version number.</li>
|
|
|
110 * <li>{@link Constants#FRAMEWORK_PROCESSOR} - The host computer processor
|
|
|
111 * name.</li>
|
|
|
112 * </ul>
|
|
|
113 * <p>
|
|
|
114 * All bundles must have permission to read these properties.
|
|
105
|
115 *
|
|
86
|
116 * <p>
|
|
|
117 * Note: The last four standard properties are used by the
|
|
|
118 * {@link Constants#BUNDLE_NATIVECODE} <code>Manifest</code> header's
|
|
|
119 * matching algorithm for selecting native language code.
|
|
105
|
120 *
|
|
86
|
121 * @param key The name of the requested property.
|
|
|
122 * @return The value of the requested property, or <code>null</code> if
|
|
|
123 * the property is undefined.
|
|
|
124 * @throws java.lang.SecurityException If the caller does not have the
|
|
|
125 * appropriate <code>PropertyPermission</code> to read the
|
|
|
126 * property, and the Java Runtime Environment supports permissions.
|
|
|
127 */
|
|
|
128 public String getProperty(String key);
|
|
|
129
|
|
|
130 /**
|
|
|
131 * Returns the <code>Bundle</code> object associated with this
|
|
|
132 * <code>BundleContext</code>. This bundle is called the context bundle.
|
|
105
|
133 *
|
|
86
|
134 * @return The <code>Bundle</code> object associated with this
|
|
|
135 * <code>BundleContext</code>.
|
|
|
136 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
137 * longer valid.
|
|
|
138 */
|
|
|
139 public Bundle getBundle();
|
|
|
140
|
|
|
141 /**
|
|
|
142 * Installs a bundle from the specified location string. A bundle is
|
|
|
143 * obtained from <code>location</code> as interpreted by the Framework in
|
|
|
144 * an implementation dependent manner.
|
|
|
145 * <p>
|
|
|
146 * Every installed bundle is uniquely identified by its location string,
|
|
|
147 * typically in the form of a URL.
|
|
105
|
148 *
|
|
86
|
149 * <p>
|
|
|
150 * The following steps are required to install a bundle:
|
|
|
151 * <ol>
|
|
|
152 * <li>If a bundle containing the same location string is already
|
|
|
153 * installed, the <code>Bundle</code> object for that bundle is returned.
|
|
105
|
154 *
|
|
86
|
155 * <li>The bundle's content is read from the location string. If this
|
|
|
156 * fails, a {@link BundleException} is thrown.
|
|
105
|
157 *
|
|
86
|
158 * <li>The bundle's <code>Bundle-NativeCode</code> dependencies are
|
|
|
159 * resolved. If this fails, a <code>BundleException</code> is thrown.
|
|
105
|
160 *
|
|
86
|
161 * <li>The bundle's associated resources are allocated. The associated
|
|
|
162 * resources minimally consist of a unique identifier and a persistent
|
|
|
163 * storage area if the platform has file system support. If this step fails,
|
|
|
164 * a <code>BundleException</code> is thrown.
|
|
105
|
165 *
|
|
86
|
166 * <li>If the bundle has declared an Bundle-RequiredExecutionEnvironment
|
|
|
167 * header, then the listed execution environments must be verified against
|
|
105
|
168 * the installed execution environments. If none of the listed execution
|
|
86
|
169 * environments match an installed execution environment, a
|
|
|
170 * <code>BundleException</code> must be thrown.
|
|
105
|
171 *
|
|
86
|
172 * <li>The bundle's state is set to <code>INSTALLED</code>.
|
|
105
|
173 *
|
|
86
|
174 * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.
|
|
105
|
175 *
|
|
86
|
176 * <li>The <code>Bundle</code> object for the newly or previously
|
|
|
177 * installed bundle is returned.
|
|
|
178 * </ol>
|
|
105
|
179 *
|
|
86
|
180 * <b>Postconditions, no exceptions thrown </b>
|
|
|
181 * <ul>
|
|
|
182 * <li><code>getState()</code> in {<code>INSTALLED</code>,<code>RESOLVED</code>}.
|
|
|
183 * <li>Bundle has a unique ID.
|
|
|
184 * </ul>
|
|
|
185 * <b>Postconditions, when an exception is thrown </b>
|
|
|
186 * <ul>
|
|
|
187 * <li>Bundle is not installed and no trace of the bundle exists.
|
|
|
188 * </ul>
|
|
105
|
189 *
|
|
86
|
190 * @param location The location identifier of the bundle to install.
|
|
|
191 * @return The <code>Bundle</code> object of the installed bundle.
|
|
|
192 * @throws BundleException If the installation failed.
|
|
|
193 * @throws java.lang.SecurityException If the caller does not have the
|
|
|
194 * appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
|
|
|
195 * Java Runtime Environment supports permissions.
|
|
|
196 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
197 * longer valid.
|
|
|
198 */
|
|
105
|
199 public Bundle installBundle(String location) ;
|
|
86
|
200
|
|
|
201 /**
|
|
|
202 * Installs a bundle from the specified <code>InputStream</code> object.
|
|
105
|
203 *
|
|
86
|
204 * <p>
|
|
|
205 * This method performs all of the steps listed in
|
|
|
206 * <code>BundleContext.installBundle(String location)</code>, except that
|
|
|
207 * the bundle's content will be read from the <code>InputStream</code>
|
|
|
208 * object. The location identifier string specified will be used as the
|
|
|
209 * identity of the bundle.
|
|
105
|
210 *
|
|
86
|
211 * <p>
|
|
|
212 * This method must always close the <code>InputStream</code> object, even
|
|
|
213 * if an exception is thrown.
|
|
105
|
214 *
|
|
86
|
215 * @param location The location identifier of the bundle to install.
|
|
|
216 * @param input The <code>InputStream</code> object from which this bundle
|
|
|
217 * will be read.
|
|
|
218 * @return The <code>Bundle</code> object of the installed bundle.
|
|
|
219 * @throws BundleException If the provided stream cannot be read or the
|
|
|
220 * installation failed.
|
|
|
221 * @throws java.lang.SecurityException If the caller does not have the
|
|
|
222 * appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
|
|
|
223 * Java Runtime Environment supports permissions.
|
|
|
224 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
225 * longer valid.
|
|
|
226 * @see #installBundle(java.lang.String)
|
|
|
227 */
|
|
105
|
228 public Bundle installBundle(String location, InputStream input) ;
|
|
86
|
229
|
|
|
230 /**
|
|
|
231 * Returns the bundle with the specified identifier.
|
|
105
|
232 *
|
|
86
|
233 * @param id The identifier of the bundle to retrieve.
|
|
|
234 * @return A <code>Bundle</code> object or <code>null</code> if the
|
|
|
235 * identifier does not match any installed bundle.
|
|
|
236 */
|
|
|
237 public Bundle getBundle(long id);
|
|
|
238
|
|
|
239 /**
|
|
|
240 * Returns a list of all installed bundles.
|
|
|
241 * <p>
|
|
|
242 * This method returns a list of all bundles installed in the OSGi
|
|
|
243 * environment at the time of the call to this method. However, since the
|
|
|
244 * Framework is a very dynamic environment, bundles can be installed or
|
|
|
245 * uninstalled at anytime.
|
|
105
|
246 *
|
|
86
|
247 * @return An array of <code>Bundle</code> objects, one object per
|
|
|
248 * installed bundle.
|
|
|
249 */
|
|
|
250 public Bundle[] getBundles();
|
|
|
251
|
|
|
252 /**
|
|
|
253 * Adds the specified <code>ServiceListener</code> object with the
|
|
|
254 * specified <code>filter</code> to the context bundle's list of
|
|
|
255 * listeners. See {@link Filter} for a description of the filter syntax.
|
|
|
256 * <code>ServiceListener</code> objects are notified when a service has a
|
|
|
257 * lifecycle state change.
|
|
105
|
258 *
|
|
86
|
259 * <p>
|
|
|
260 * If the context bundle's list of listeners already contains a listener
|
|
|
261 * <code>l</code> such that <code>(l==listener)</code>, then this
|
|
|
262 * method replaces that listener's filter (which may be <code>null</code>)
|
|
|
263 * with the specified one (which may be <code>null</code>).
|
|
105
|
264 *
|
|
86
|
265 * <p>
|
|
|
266 * The listener is called if the filter criteria is met. To filter based
|
|
|
267 * upon the class of the service, the filter should reference the
|
|
|
268 * {@link Constants#OBJECTCLASS} property. If <code>filter</code> is
|
|
|
269 * <code>null</code>, all services are considered to match the filter.
|
|
105
|
270 *
|
|
86
|
271 * <p>
|
|
|
272 * When using a <code>filter</code>, it is possible that the
|
|
|
273 * <code>ServiceEvent</code>s for the complete lifecycle of a service
|
|
|
274 * will not be delivered to the listener. For example, if the
|
|
|
275 * <code>filter</code> only matches when the property <code>x</code> has
|
|
|
276 * the value <code>1</code>, the listener will not be called if the
|
|
|
277 * service is registered with the property <code>x</code> not set to the
|
|
|
278 * value <code>1</code>. Subsequently, when the service is modified
|
|
|
279 * setting property <code>x</code> to the value <code>1</code>, the
|
|
|
280 * filter will match and the listener will be called with a
|
|
|
281 * <code>ServiceEvent</code> of type <code>MODIFIED</code>. Thus, the
|
|
|
282 * listener will not be called with a <code>ServiceEvent</code> of type
|
|
|
283 * <code>REGISTERED</code>.
|
|
105
|
284 *
|
|
86
|
285 * <p>
|
|
|
286 * If the Java Runtime Environment supports permissions, the
|
|
|
287 * <code>ServiceListener</code> object will be notified of a service event
|
|
|
288 * only if the bundle that is registering it has the
|
|
|
289 * <code>ServicePermission</code> to get the service using at least one of
|
|
|
290 * the named classes the service was registered under.
|
|
105
|
291 *
|
|
86
|
292 * @param listener The <code>ServiceListener</code> object to be added.
|
|
|
293 * @param filter The filter criteria.
|
|
105
|
294 *
|
|
86
|
295 * @throws InvalidSyntaxException If <code>filter</code> contains an
|
|
|
296 * invalid filter string that cannot be parsed.
|
|
|
297 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
298 * longer valid.
|
|
105
|
299 *
|
|
86
|
300 * @see ServiceEvent
|
|
|
301 * @see ServiceListener
|
|
|
302 * @see ServicePermission
|
|
|
303 */
|
|
|
304 public void addServiceListener(ServiceListener listener,
|
|
105
|
305 String filter) ;
|
|
86
|
306
|
|
|
307 /**
|
|
|
308 * Adds the specified <code>ServiceListener</code> object to the context
|
|
|
309 * bundle's list of listeners.
|
|
105
|
310 *
|
|
86
|
311 * <p>
|
|
|
312 * This method is the same as calling
|
|
|
313 * <code>BundleContext.addServiceListener(ServiceListener listener,
|
|
|
314 * String filter)</code>
|
|
|
315 * with <code>filter</code> set to <code>null</code>.
|
|
105
|
316 *
|
|
86
|
317 * @param listener The <code>ServiceListener</code> object to be added.
|
|
|
318 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
319 * longer valid.
|
|
105
|
320 *
|
|
86
|
321 * @see #addServiceListener(ServiceListener, String)
|
|
|
322 */
|
|
|
323 public void addServiceListener(ServiceListener listener);
|
|
|
324
|
|
|
325 /**
|
|
|
326 * Removes the specified <code>ServiceListener</code> object from the
|
|
|
327 * context bundle's list of listeners.
|
|
105
|
328 *
|
|
86
|
329 * <p>
|
|
|
330 * If <code>listener</code> is not contained in this context bundle's list
|
|
|
331 * of listeners, this method does nothing.
|
|
105
|
332 *
|
|
86
|
333 * @param listener The <code>ServiceListener</code> to be removed.
|
|
|
334 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
335 * longer valid.
|
|
|
336 */
|
|
|
337 public void removeServiceListener(ServiceListener listener);
|
|
|
338
|
|
|
339 /**
|
|
|
340 * Adds the specified <code>BundleListener</code> object to the context
|
|
|
341 * bundle's list of listeners if not already present. BundleListener objects
|
|
|
342 * are notified when a bundle has a lifecycle state change.
|
|
105
|
343 *
|
|
86
|
344 * <p>
|
|
|
345 * If the context bundle's list of listeners already contains a listener
|
|
|
346 * <code>l</code> such that <code>(l==listener)</code>, this method
|
|
|
347 * does nothing.
|
|
105
|
348 *
|
|
86
|
349 * @param listener The <code>BundleListener</code> to be added.
|
|
|
350 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
351 * longer valid.
|
|
|
352 * @throws java.lang.SecurityException If listener is a
|
|
|
353 * <code>SynchronousBundleListener</code> and the caller does not
|
|
|
354 * have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
|
|
|
355 * and the Java Runtime Environment supports permissions.
|
|
105
|
356 *
|
|
86
|
357 * @see BundleEvent
|
|
|
358 * @see BundleListener
|
|
|
359 */
|
|
|
360 public void addBundleListener(BundleListener listener);
|
|
|
361
|
|
|
362 /**
|
|
|
363 * Removes the specified <code>BundleListener</code> object from the
|
|
|
364 * context bundle's list of listeners.
|
|
105
|
365 *
|
|
86
|
366 * <p>
|
|
|
367 * If <code>listener</code> is not contained in the context bundle's list
|
|
|
368 * of listeners, this method does nothing.
|
|
105
|
369 *
|
|
86
|
370 * @param listener The <code>BundleListener</code> object to be removed.
|
|
|
371 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
372 * longer valid.
|
|
|
373 * @throws java.lang.SecurityException If listener is a
|
|
|
374 * <code>SynchronousBundleListener</code> and the caller does not
|
|
|
375 * have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
|
|
|
376 * and the Java Runtime Environment supports permissions.
|
|
|
377 */
|
|
|
378 public void removeBundleListener(BundleListener listener);
|
|
|
379
|
|
|
380 /**
|
|
|
381 * Adds the specified <code>FrameworkListener</code> object to the context
|
|
|
382 * bundle's list of listeners if not already present. FrameworkListeners are
|
|
|
383 * notified of general Framework events.
|
|
105
|
384 *
|
|
86
|
385 * <p>
|
|
|
386 * If the context bundle's list of listeners already contains a listener
|
|
|
387 * <code>l</code> such that <code>(l==listener)</code>, this method
|
|
|
388 * does nothing.
|
|
105
|
389 *
|
|
86
|
390 * @param listener The <code>FrameworkListener</code> object to be added.
|
|
|
391 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
392 * longer valid.
|
|
105
|
393 *
|
|
86
|
394 * @see FrameworkEvent
|
|
|
395 * @see FrameworkListener
|
|
|
396 */
|
|
|
397 public void addFrameworkListener(FrameworkListener listener);
|
|
|
398
|
|
|
399 /**
|
|
|
400 * Removes the specified <code>FrameworkListener</code> object from the
|
|
|
401 * context bundle's list of listeners.
|
|
105
|
402 *
|
|
86
|
403 * <p>
|
|
|
404 * If <code>listener</code> is not contained in the context bundle's list
|
|
|
405 * of listeners, this method does nothing.
|
|
105
|
406 *
|
|
86
|
407 * @param listener The <code>FrameworkListener</code> object to be
|
|
|
408 * removed.
|
|
|
409 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
410 * longer valid.
|
|
|
411 */
|
|
|
412 public void removeFrameworkListener(FrameworkListener listener);
|
|
|
413
|
|
|
414 /**
|
|
|
415 * Registers the specified service object with the specified properties
|
|
|
416 * under the specified class names into the Framework. A
|
|
|
417 * <code>ServiceRegistration</code> object is returned. The
|
|
|
418 * <code>ServiceRegistration</code> object is for the private use of the
|
|
|
419 * bundle registering the service and should not be shared with other
|
|
|
420 * bundles. The registering bundle is defined to be the context bundle.
|
|
|
421 * Other bundles can locate the service by using either the
|
|
|
422 * {@link #getServiceReferences} or {@link #getServiceReference} method.
|
|
105
|
423 *
|
|
86
|
424 * <p>
|
|
|
425 * A bundle can register a service object that implements the
|
|
|
426 * {@link ServiceFactory} interface to have more flexibility in providing
|
|
|
427 * service objects to other bundles.
|
|
105
|
428 *
|
|
86
|
429 * <p>
|
|
|
430 * The following steps are required to register a service:
|
|
|
431 * <ol>
|
|
|
432 * <li>If <code>service</code> is not a <code>ServiceFactory</code>,
|
|
|
433 * an <code>IllegalArgumentException</code> is thrown if
|
|
|
434 * <code>service</code> is not an <code>instanceof</code> all the
|
|
|
435 * classes named.
|
|
|
436 * <li>The Framework adds these service properties to the specified
|
|
|
437 * <code>Dictionary</code> (which may be <code>null</code>): a property
|
|
|
438 * named {@link Constants#SERVICE_ID} identifying the registration number of
|
|
|
439 * the service and a property named {@link Constants#OBJECTCLASS} containing
|
|
|
440 * all the specified classes. If any of these properties have already been
|
|
|
441 * specified by the registering bundle, their values will be overwritten by
|
|
|
442 * the Framework.
|
|
|
443 * <li>The service is added to the Framework service registry and may now
|
|
|
444 * be used by other bundles.
|
|
|
445 * <li>A service event of type {@link ServiceEvent#REGISTERED} is
|
|
|
446 * fired.
|
|
|
447 * <li>A <code>ServiceRegistration</code> object for this registration is
|
|
|
448 * returned.
|
|
|
449 * </ol>
|
|
105
|
450 *
|
|
86
|
451 * @param clazzes The class names under which the service can be located.
|
|
|
452 * The class names in this array will be stored in the service's
|
|
|
453 * properties under the key {@link Constants#OBJECTCLASS}.
|
|
|
454 * @param service The service object or a <code>ServiceFactory</code>
|
|
|
455 * object.
|
|
|
456 * @param properties The properties for this service. The keys in the
|
|
|
457 * properties object must all be <code>String</code> objects. See
|
|
|
458 * {@link Constants} for a list of standard service property keys.
|
|
|
459 * Changes should not be made to this object after calling this
|
|
|
460 * method. To update the service's properties the
|
|
|
461 * {@link ServiceRegistration#setProperties} method must be called.
|
|
|
462 * The set of properties may be <code>null</code> if the service
|
|
|
463 * has no properties.
|
|
105
|
464 *
|
|
86
|
465 * @return A <code>ServiceRegistration</code> object for use by the bundle
|
|
|
466 * registering the service to update the service's properties or to
|
|
|
467 * unregister the service.
|
|
105
|
468 *
|
|
86
|
469 * @throws java.lang.IllegalArgumentException If one of the following is
|
|
|
470 * true:
|
|
|
471 * <ul>
|
|
|
472 * <li><code>service</code> is <code>null</code>.
|
|
|
473 * <li><code>service</code> is not a <code>ServiceFactory</code>
|
|
|
474 * object and is not an instance of all the named classes in
|
|
|
475 * <code>clazzes</code>.
|
|
|
476 * <li><code>properties</code> contains case variants of the same
|
|
|
477 * key name.
|
|
|
478 * </ul>
|
|
105
|
479 *
|
|
86
|
480 * @throws java.lang.SecurityException If the caller does not have the
|
|
|
481 * <code>ServicePermission</code> to register the service for all
|
|
|
482 * the named classes and the Java Runtime Environment supports
|
|
|
483 * permissions.
|
|
105
|
484 *
|
|
86
|
485 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
486 * longer valid.
|
|
105
|
487 *
|
|
86
|
488 * @see ServiceRegistration
|
|
|
489 * @see ServiceFactory
|
|
|
490 */
|
|
|
491 public ServiceRegistration registerService(String[] clazzes,
|
|
|
492 Object service, Dictionary properties);
|
|
|
493
|
|
|
494 /**
|
|
|
495 * Registers the specified service object with the specified properties
|
|
|
496 * under the specified class name with the Framework.
|
|
105
|
497 *
|
|
86
|
498 * <p>
|
|
|
499 * This method is otherwise identical to
|
|
|
500 * {@link #registerService(java.lang.String[], java.lang.Object,
|
|
|
501 * java.util.Dictionary)} and is provided as a convenience when
|
|
|
502 * <code>service</code> will only be registered under a single class name.
|
|
|
503 * Note that even in this case the value of the service's
|
|
|
504 * {@link Constants#OBJECTCLASS} property will be an array of strings,
|
|
|
505 * rather than just a single string.
|
|
105
|
506 *
|
|
86
|
507 * @param clazz The class name under which the service can be located.
|
|
|
508 * @param service The service object or a <code>ServiceFactory</code>
|
|
|
509 * object.
|
|
105
|
510 * @param properties The properties for this service.
|
|
|
511 *
|
|
86
|
512 * @return A <code>ServiceRegistration</code> object for use by the bundle
|
|
|
513 * registering the service to update the service's properties or to
|
|
|
514 * unregister the service.
|
|
105
|
515 *
|
|
86
|
516 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
517 * longer valid.
|
|
|
518 * @see #registerService(java.lang.String[], java.lang.Object,
|
|
|
519 * java.util.Dictionary)
|
|
|
520 */
|
|
|
521 public ServiceRegistration registerService(String clazz,
|
|
|
522 Object service, Dictionary properties);
|
|
|
523
|
|
|
524 /**
|
|
|
525 * Returns an array of <code>ServiceReference</code> objects. The returned
|
|
|
526 * array of <code>ServiceReference</code> objects contains services that
|
|
|
527 * were registered under the specified class, match the specified filter
|
|
|
528 * criteria, and the packages for the class names under which the services
|
|
|
529 * were registered match the context bundle's packages as defined in
|
|
|
530 * {@link ServiceReference#isAssignableTo(Bundle, String)}.
|
|
105
|
531 *
|
|
86
|
532 * <p>
|
|
|
533 * The list is valid at the time of the call to this method, however since
|
|
|
534 * the Framework is a very dynamic environment, services can be modified or
|
|
|
535 * unregistered at anytime.
|
|
105
|
536 *
|
|
86
|
537 * <p>
|
|
|
538 * <code>filter</code> is used to select the registered service whose
|
|
|
539 * properties objects contain keys and values which satisfy the filter. See
|
|
|
540 * {@link Filter} for a description of the filter string syntax.
|
|
105
|
541 *
|
|
86
|
542 * <p>
|
|
|
543 * If <code>filter</code> is <code>null</code>, all registered services
|
|
|
544 * are considered to match the filter. If <code>filter</code> cannot be
|
|
|
545 * parsed, an {@link InvalidSyntaxException} will be thrown with a human
|
|
|
546 * readable message where the filter became unparsable.
|
|
105
|
547 *
|
|
86
|
548 * <p>
|
|
|
549 * The following steps are required to select a set of
|
|
|
550 * <code>ServiceReference</code> objects:
|
|
|
551 * <ol>
|
|
|
552 * <li>If the filter string is not <code>null</code>, the filter string
|
|
|
553 * is parsed and the set <code>ServiceReference</code> objects of
|
|
|
554 * registered services that satisfy the filter is produced. If the filter
|
|
|
555 * string is <code>null</code>, then all registered services are
|
|
|
556 * considered to satisfy the filter.
|
|
|
557 * <li>If the Java Runtime Environment supports permissions, the set of
|
|
|
558 * <code>ServiceReference</code> objects produced by the previous step is
|
|
|
559 * reduced by checking that the caller has the
|
|
|
560 * <code>ServicePermission</code> to get at least one of the class names
|
|
|
561 * under which the service was registered. If the caller does not have the
|
|
|
562 * correct permission for a particular <code>ServiceReference</code>
|
|
|
563 * object, then it is removed from the set.
|
|
|
564 * <li>If <code>clazz</code> is not <code>null</code>, the set is
|
|
|
565 * further reduced to those services that are an <code>instanceof</code>
|
|
|
566 * and were registered under the specified class. The complete list of
|
|
|
567 * classes of which a service is an instance and which were specified when
|
|
|
568 * the service was registered is available from the service's
|
|
|
569 * {@link Constants#OBJECTCLASS} property.
|
|
|
570 * <li>The set is reduced one final time by cycling through each
|
|
|
571 * <code>ServiceReference</code> object and calling
|
|
|
572 * {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
|
|
|
573 * bundle and each class name under which the <code>ServiceReference</code>
|
|
|
574 * object was registered. For any given <code>ServiceReference</code>
|
|
|
575 * object, if any call to
|
|
|
576 * {@link ServiceReference#isAssignableTo(Bundle, String)} returns
|
|
|
577 * <code>false</code>, then it is removed from the set of
|
|
|
578 * <code>ServiceReference</code> objects.
|
|
|
579 * <li>An array of the remaining <code>ServiceReference</code> objects is
|
|
|
580 * returned.
|
|
|
581 * </ol>
|
|
105
|
582 *
|
|
86
|
583 * @param clazz The class name with which the service was registered or
|
|
|
584 * <code>null</code> for all services.
|
|
|
585 * @param filter The filter criteria.
|
|
|
586 * @return An array of <code>ServiceReference</code> objects or
|
|
|
587 * <code>null</code> if no services are registered which satisfy
|
|
|
588 * the search.
|
|
|
589 * @throws InvalidSyntaxException If <code>filter</code> contains an
|
|
|
590 * invalid filter string that cannot be parsed.
|
|
|
591 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
592 * longer valid.
|
|
|
593 */
|
|
|
594 public ServiceReference[] getServiceReferences(String clazz,
|
|
105
|
595 String filter) ;
|
|
86
|
596
|
|
|
597 /**
|
|
|
598 * Returns an array of <code>ServiceReference</code> objects. The returned
|
|
|
599 * array of <code>ServiceReference</code> objects contains services that
|
|
|
600 * were registered under the specified class and match the specified filter
|
|
|
601 * criteria.
|
|
105
|
602 *
|
|
86
|
603 * <p>
|
|
|
604 * The list is valid at the time of the call to this method, however since
|
|
|
605 * the Framework is a very dynamic environment, services can be modified or
|
|
|
606 * unregistered at anytime.
|
|
105
|
607 *
|
|
86
|
608 * <p>
|
|
|
609 * <code>filter</code> is used to select the registered service whose
|
|
|
610 * properties objects contain keys and values which satisfy the filter. See
|
|
|
611 * {@link Filter} for a description of the filter string syntax.
|
|
105
|
612 *
|
|
86
|
613 * <p>
|
|
|
614 * If <code>filter</code> is <code>null</code>, all registered services
|
|
|
615 * are considered to match the filter. If <code>filter</code> cannot be
|
|
|
616 * parsed, an {@link InvalidSyntaxException} will be thrown with a human
|
|
|
617 * readable message where the filter became unparsable.
|
|
105
|
618 *
|
|
86
|
619 * <p>
|
|
|
620 * The following steps are required to select a set of
|
|
|
621 * <code>ServiceReference</code> objects:
|
|
|
622 * <ol>
|
|
|
623 * <li>If the filter string is not <code>null</code>, the filter string
|
|
|
624 * is parsed and the set <code>ServiceReference</code> objects of
|
|
|
625 * registered services that satisfy the filter is produced. If the filter
|
|
|
626 * string is <code>null</code>, then all registered services are
|
|
|
627 * considered to satisfy the filter.
|
|
|
628 * <li>If the Java Runtime Environment supports permissions, the set of
|
|
|
629 * <code>ServiceReference</code> objects produced by the previous step is
|
|
|
630 * reduced by checking that the caller has the
|
|
|
631 * <code>ServicePermission</code> to get at least one of the class names
|
|
|
632 * under which the service was registered. If the caller does not have the
|
|
|
633 * correct permission for a particular <code>ServiceReference</code>
|
|
|
634 * object, then it is removed from the set.
|
|
|
635 * <li>If <code>clazz</code> is not <code>null</code>, the set is
|
|
|
636 * further reduced to those services that are an <code>instanceof</code>
|
|
|
637 * and were registered under the specified class. The complete list of
|
|
|
638 * classes of which a service is an instance and which were specified when
|
|
|
639 * the service was registered is available from the service's
|
|
|
640 * {@link Constants#OBJECTCLASS} property.
|
|
|
641 * <li>An array of the remaining <code>ServiceReference</code> objects is
|
|
|
642 * returned.
|
|
|
643 * </ol>
|
|
105
|
644 *
|
|
86
|
645 * @param clazz The class name with which the service was registered or
|
|
|
646 * <code>null</code> for all services.
|
|
|
647 * @param filter The filter criteria.
|
|
|
648 * @return An array of <code>ServiceReference</code> objects or
|
|
|
649 * <code>null</code> if no services are registered which satisfy
|
|
|
650 * the search.
|
|
|
651 * @throws InvalidSyntaxException If <code>filter</code> contains an
|
|
|
652 * invalid filter string that cannot be parsed.
|
|
|
653 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
654 * longer valid.
|
|
|
655 * @since 1.3
|
|
|
656 */
|
|
|
657 public ServiceReference[] getAllServiceReferences(String clazz,
|
|
105
|
658 String filter) ;
|
|
86
|
659
|
|
|
660 /**
|
|
|
661 * Returns a <code>ServiceReference</code> object for a service that
|
|
|
662 * implements and was registered under the specified class.
|
|
105
|
663 *
|
|
86
|
664 * <p>
|
|
|
665 * This <code>ServiceReference</code> object is valid at the time of the
|
|
|
666 * call to this method, however as the Framework is a very dynamic
|
|
|
667 * environment, services can be modified or unregistered at anytime.
|
|
105
|
668 *
|
|
86
|
669 * <p>
|
|
|
670 * This method is the same as calling
|
|
|
671 * {@link BundleContext#getServiceReferences(String, String)} with a
|
|
|
672 * <code>null</code> filter string. It is provided as a convenience for
|
|
|
673 * when the caller is interested in any service that implements the
|
|
|
674 * specified class.
|
|
|
675 * <p>
|
|
|
676 * If multiple such services exist, the service with the highest ranking (as
|
|
|
677 * specified in its {@link Constants#SERVICE_RANKING} property) is returned.
|
|
|
678 * <p>
|
|
|
679 * If there is a tie in ranking, the service with the lowest service ID (as
|
|
|
680 * specified in its {@link Constants#SERVICE_ID} property); that is, the
|
|
|
681 * service that was registered first is returned.
|
|
105
|
682 *
|
|
86
|
683 * @param clazz The class name with which the service was registered.
|
|
|
684 * @return A <code>ServiceReference</code> object, or <code>null</code>
|
|
|
685 * if no services are registered which implement the named class.
|
|
|
686 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
687 * longer valid.
|
|
|
688 * @see #getServiceReferences(String, String)
|
|
|
689 */
|
|
|
690 public ServiceReference getServiceReference(String clazz);
|
|
|
691
|
|
|
692 /**
|
|
|
693 * Returns the specified service object for a service.
|
|
|
694 * <p>
|
|
|
695 * A bundle's use of a service is tracked by the bundle's use count of that
|
|
|
696 * service. Each time a service's service object is returned by
|
|
|
697 * {@link #getService(ServiceReference)} the context bundle's use count for
|
|
|
698 * that service is incremented by one. Each time the service is released by
|
|
|
699 * {@link #ungetService(ServiceReference)} the context bundle's use count
|
|
|
700 * for that service is decremented by one.
|
|
|
701 * <p>
|
|
|
702 * When a bundle's use count for a service drops to zero, the bundle should
|
|
|
703 * no longer use that service.
|
|
105
|
704 *
|
|
86
|
705 * <p>
|
|
|
706 * This method will always return <code>null</code> when the service
|
|
|
707 * associated with this <code>reference</code> has been unregistered.
|
|
105
|
708 *
|
|
86
|
709 * <p>
|
|
|
710 * The following steps are required to get the service object:
|
|
|
711 * <ol>
|
|
|
712 * <li>If the service has been unregistered, <code>null</code> is
|
|
|
713 * returned.
|
|
|
714 * <li>The context bundle's use count for this service is incremented by
|
|
|
715 * one.
|
|
|
716 * <li>If the context bundle's use count for the service is currently one
|
|
|
717 * and the service was registered with an object implementing the
|
|
|
718 * <code>ServiceFactory</code> interface, the
|
|
|
719 * {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method is
|
|
|
720 * called to create a service object for the context bundle. This service
|
|
|
721 * object is cached by the Framework. While the context bundle's use count
|
|
|
722 * for the service is greater than zero, subsequent calls to get the
|
|
|
723 * services's service object for the context bundle will return the cached
|
|
|
724 * service object. <br>
|
|
|
725 * If the service object returned by the <code>ServiceFactory</code>
|
|
|
726 * object is not an <code>instanceof</code> all the classes named when the
|
|
|
727 * service was registered or the <code>ServiceFactory</code> object throws
|
|
|
728 * an exception, <code>null</code> is returned and a Framework event of
|
|
|
729 * type {@link FrameworkEvent#ERROR} is fired.
|
|
|
730 * <li>The service object for the service is returned.
|
|
|
731 * </ol>
|
|
105
|
732 *
|
|
86
|
733 * @param reference A reference to the service.
|
|
|
734 * @return A service object for the service associated with
|
|
|
735 * <code>reference</code> or <code>null</code> if the service is
|
|
|
736 * not registered or does not implement the classes under which it
|
|
|
737 * was registered in the case of a <code>ServiceFactory</code>.
|
|
|
738 * @throws java.lang.SecurityException If the caller does not have the
|
|
|
739 * <code>ServicePermission</code> to get the service using at
|
|
|
740 * least one of the named classes the service was registered under
|
|
|
741 * and the Java Runtime Environment supports permissions.
|
|
|
742 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
743 * longer valid.
|
|
|
744 * @see #ungetService(ServiceReference)
|
|
|
745 * @see ServiceFactory
|
|
|
746 */
|
|
|
747 public Object getService(ServiceReference reference);
|
|
|
748
|
|
|
749 /**
|
|
|
750 * Releases the service object referenced by the specified
|
|
|
751 * <code>ServiceReference</code> object. If the context bundle's use count
|
|
|
752 * for the service is zero, this method returns <code>false</code>.
|
|
|
753 * Otherwise, the context bundle's use count for the service is decremented
|
|
|
754 * by one.
|
|
105
|
755 *
|
|
86
|
756 * <p>
|
|
|
757 * The service's service object should no longer be used and all references
|
|
|
758 * to it should be destroyed when a bundle's use count for the service drops
|
|
|
759 * to zero.
|
|
105
|
760 *
|
|
86
|
761 * <p>
|
|
|
762 * The following steps are required to unget the service object:
|
|
|
763 * <ol>
|
|
|
764 * <li>If the context bundle's use count for the service is zero or the
|
|
|
765 * service has been unregistered, <code>false</code> is returned.
|
|
|
766 * <li>The context bundle's use count for this service is decremented by
|
|
|
767 * one.
|
|
|
768 * <li>If the context bundle's use count for the service is currently zero
|
|
|
769 * and the service was registered with a <code>ServiceFactory</code>
|
|
|
770 * object, the
|
|
|
771 * {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
|
|
|
772 * method is called to release the service object for the context bundle.
|
|
|
773 * <li><code>true</code> is returned.
|
|
|
774 * </ol>
|
|
105
|
775 *
|
|
86
|
776 * @param reference A reference to the service to be released.
|
|
|
777 * @return <code>false</code> if the context bundle's use count for the
|
|
|
778 * service is zero or if the service has been unregistered;
|
|
|
779 * <code>true</code> otherwise.
|
|
|
780 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
781 * longer valid.
|
|
|
782 * @see #getService
|
|
|
783 * @see ServiceFactory
|
|
|
784 */
|
|
|
785 public bool ungetService(ServiceReference reference);
|
|
|
786
|
|
|
787 /**
|
|
|
788 * Creates a <code>File</code> object for a file in the persistent storage
|
|
|
789 * area provided for the bundle by the Framework. This method will return
|
|
|
790 * <code>null</code> if the platform does not have file system support.
|
|
105
|
791 *
|
|
86
|
792 * <p>
|
|
|
793 * A <code>File</code> object for the base directory of the persistent
|
|
|
794 * storage area provided for the context bundle by the Framework can be
|
|
|
795 * obtained by calling this method with an empty string as
|
|
|
796 * <code>filename</code>.
|
|
105
|
797 *
|
|
86
|
798 * <p>
|
|
|
799 * If the Java Runtime Environment supports permissions, the Framework will
|
|
|
800 * ensure that the bundle has the <code>java.io.FilePermission</code> with
|
|
|
801 * actions <code>read</code>,<code>write</code>,<code>delete</code>
|
|
|
802 * for all files (recursively) in the persistent storage area provided for
|
|
|
803 * the context bundle.
|
|
105
|
804 *
|
|
86
|
805 * @param filename A relative name to the file to be accessed.
|
|
|
806 * @return A <code>File</code> object that represents the requested file
|
|
|
807 * or <code>null</code> if the platform does not have file system
|
|
|
808 * support.
|
|
|
809 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
810 * longer valid.
|
|
|
811 */
|
|
|
812 public File getDataFile(String filename);
|
|
|
813
|
|
|
814 /**
|
|
|
815 * Creates a <code>Filter</code> object. This <code>Filter</code> object
|
|
|
816 * may be used to match a <code>ServiceReference</code> object or a
|
|
|
817 * <code>Dictionary</code> object.
|
|
105
|
818 *
|
|
86
|
819 * <p>
|
|
|
820 * If the filter cannot be parsed, an {@link InvalidSyntaxException} will be
|
|
|
821 * thrown with a human readable message where the filter became unparsable.
|
|
105
|
822 *
|
|
86
|
823 * @param filter The filter string.
|
|
|
824 * @return A <code>Filter</code> object encapsulating the filter string.
|
|
|
825 * @throws InvalidSyntaxException If <code>filter</code> contains an
|
|
|
826 * invalid filter string that cannot be parsed.
|
|
|
827 * @throws NullPointerException If <code>filter</code> is null.
|
|
|
828 * @throws java.lang.IllegalStateException If this BundleContext is no
|
|
|
829 * longer valid.
|
|
105
|
830 *
|
|
86
|
831 * @since 1.1
|
|
|
832 * @see "Framework specification for a description of the filter string syntax."
|
|
|
833 * @see FrameworkUtil#createFilter(String)
|
|
|
834 */
|
|
105
|
835 public Filter createFilter(String filter) ;
|
|
86
|
836 }
|
