Java > Open Source Codes > org > osgi > framework > BundleContext


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags