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


1 /*
2  * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Bundle.java,v 1.54 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.IOException ;
22 import java.io.InputStream ;
23 import java.net.URL ;
24 import java.util.Dictionary ;
25 import java.util.Enumeration ;
26
27 /**
28  * An installed bundle in the Framework.
29  *
30  * <p>
31  * A <code>Bundle</code> object is the access point to define the lifecycle of
32  * an installed bundle. Each bundle installed in the OSGi environment must have
33  * an associated <code>Bundle</code> object.
34  *
35  * <p>
36  * A bundle must have a unique identity, a <code>long</code>, chosen by the
37  * Framework. This identity must not change during the lifecycle of a bundle,
38  * even when the bundle is updated. Uninstalling and then reinstalling the
39  * bundle must create a new unique identity.
40  *
41  * <p>
42  * A bundle can be in one of six states:
43  * <ul>
44  * <li>{@link #UNINSTALLED}
45  * <li>{@link #INSTALLED}
46  * <li>{@link #RESOLVED}
47  * <li>{@link #STARTING}
48  * <li>{@link #STOPPING}
49  * <li>{@link #ACTIVE}
50  * </ul>
51  * <p>
52  * Values assigned to these states have no specified ordering; they represent
53  * bit values that may be ORed together to determine if a bundle is in one of
54  * the valid states.
55  *
56  * <p>
57  * A bundle should only execute code when its state is one of
58  * <code>STARTING</code>,<code>ACTIVE</code>, or <code>STOPPING</code>.
59  * An <code>UNINSTALLED</code> bundle can not be set to another state; it is a
60  * zombie and can only be reached because references are kept somewhere.
61  *
62  * <p>
63  * The Framework is the only entity that is allowed to create
64  * <code>Bundle</code> objects, and these objects are only valid within the
65  * Framework that created them.
66  *
67  * @ThreadSafe
68  * @version $Revision: 1.54 $
69  */
70 public interface Bundle {
71     /**
72      * The bundle is uninstalled and may not be used.
73      *
74      * <p>
75      * The <code>UNINSTALLED</code> state is only visible after a bundle is
76      * uninstalled; the bundle is in an unusable state but references to the
77      * <code>Bundle</code> object may still be available and used for
78      * introspection.
79      * <p>
80      * The value of <code>UNINSTALLED</code> is 0x00000001.
81      */
82     public static final int UNINSTALLED = 0x00000001;
83
84     /**
85      * The bundle is installed but not yet resolved.
86      *
87      * <p>
88      * A bundle is in the <code>INSTALLED</code> state when it has been
89      * installed in the Framework but is not or cannot be resolved.
90      * <p>
91      * This state is visible if the bundle's code dependencies are not resolved.
92      * The Framework may attempt to resolve an <code>INSTALLED</code> bundle's
93      * code dependencies and move the bundle to the <code>RESOLVED</code>
94      * state.
95      * <p>
96      * The value of <code>INSTALLED</code> is 0x00000002.
97      */
98     public static final int INSTALLED = 0x00000002;
99
100     /**
101      * The bundle is resolved and is able to be started.
102      *
103      * <p>
104      * A bundle is in the <code>RESOLVED</code> state when the Framework has
105      * successfully resolved the bundle's code dependencies. These dependencies
106      * include:
107      * <ul>
108      * <li>The bundle's class path from its {@link Constants#BUNDLE_CLASSPATH}
109      * Manifest header.
110      * <li>The bundle's package dependencies from its
111      * {@link Constants#EXPORT_PACKAGE} and {@link Constants#IMPORT_PACKAGE}
112      * Manifest headers.
113      * <li>The bundle's required bundle dependencies from its
114      * {@link Constants#REQUIRE_BUNDLE} Manifest header.
115      * <li>A fragment bundle's host dependency from its
116      * {@link Constants#FRAGMENT_HOST} Manifest header.
117      * </ul>
118      * <p>
119      * Note that the bundle is not active yet. A bundle must be put in the
120      * <code>RESOLVED</code> state before it can be started. The Framework may
121      * attempt to resolve a bundle at any time.
122      * <p>
123      * The value of <code>RESOLVED</code> is 0x00000004.
124      */
125     public static final int RESOLVED = 0x00000004;
126
127     /**
128      * The bundle is in the process of starting.
129      *
130      * <p>
131      * A bundle is in the <code>STARTING</code> state when its
132      * {@link #start(int) start} method is active. A bundle must be in this
133      * state when the bundle's {@link BundleActivator#start} is called. If the
134      * <code>BundleActivator.start</code> method completes without exception,
135      * then the bundle has successfully started and must move to the
136      * <code>ACTIVE</code> state.
137      * <p>
138      * If the bundle has a
139      * {@link Constants#ACTIVATION_LAZY lazy activation policy}, then the
140      * bundle may remain in this state for some time until the activation is
141      * triggered.
142      * <p>
143      * The value of <code>STARTING</code> is 0x00000008.
144      */
145     public static final int STARTING = 0x00000008;
146
147     /**
148      * The bundle is in the process of stopping.
149      *
150      * <p>
151      * A bundle is in the <code>STOPPING</code> state when its
152      * {@link #stop(int) stop} method is active. A bundle must be in this state
153      * when the bundle's {@link BundleActivator#stop} method is called. When the
154      * <code>BundleActivator.stop</code> method completes the bundle is
155      * stopped and must move to the <code>RESOLVED</code> state.
156      * <p>
157      * The value of <code>STOPPING</code> is 0x00000010.
158      */
159     public static final int STOPPING = 0x00000010;
160
161     /**
162      * The bundle is now running.
163      *
164      * <p>
165      * A bundle is in the <code>ACTIVE</code> state when it has been
166      * successfully started and activated.
167      * <p>
168      * The value of <code>ACTIVE</code> is 0x00000020.
169      */
170     public static final int ACTIVE = 0x00000020;
171
172     /**
173      * The bundle start operation is transient and the persistent autostart
174      * setting of the bundle is not modified.
175      *
176      * <p>
177      * This bit may be set when calling {@link #start(int)} to notify the
178      * framework that the autostart setting of the bundle must not be modified.
179      * If this bit is not set, then the autostart setting of the bundle is
180      * modified.
181      *
182      * @since 1.4
183      * @see #start(int)
184      */
185     public static final int START_TRANSIENT = 0x00000001;
186
187     /**
188      * The bundle start operation must activate the bundle according to the
189      * bundle's declared
190      * {@link Constants#BUNDLE_ACTIVATIONPOLICY activation policy}.
191      *
192      * <p>
193      * This bit may be set when calling {@link #start(int)} to notify the
194      * framework that the bundle must be activated using the bundle's declared
195      * activation policy.
196      *
197      * @since 1.4
198      * @see Constants#BUNDLE_ACTIVATIONPOLICY
199      * @see #start(int)
200      */
201     public static final int START_ACTIVATION_POLICY = 0x00000002;
202
203     /**
204      * The bundle stop is transient and the persistent autostart setting of the
205      * bundle is not modified.
206      *
207      * <p>
208      * This bit may be set when calling {@link #stop(int)} to notify the
209      * framework that the autostart setting of the bundle must not be modified.
210      * If this bit is not set, then the autostart setting of the bundle is
211      * modified.
212      *
213      * @since 1.4
214      * @see #stop(int)
215      */
216     public static final int STOP_TRANSIENT = 0x00000001;
217
218     /**
219      * Returns this bundle's current state.
220      *
221      * <p>
222      * A bundle can be in only one state at any time.
223      *
224      * @return An element of <code>UNINSTALLED</code>,<code>INSTALLED</code>,
225      * <code>RESOLVED</code>,<code>STARTING</code>,
226      * <code>STOPPING</code>,<code>ACTIVE</code>.
227      */
228     public int getState();
229
230     /**
231      * Starts this bundle.
232      *
233      * <p>
234      * If this bundle's state is <code>UNINSTALLED</code> then an
235      * <code>IllegalStateException</code> is thrown.
236      * <p>
237      * If the Framework implements the optional Start Level service and the
238      * current start level is less than this bundle's start level:
239      * <ul>
240      * <li>If the {@link #START_TRANSIENT} option is set, then a
241      * <code>BundleException</code> is thrown indicating this bundle cannot be
242      * started due to the Framework's current start level.
243      *
244      * <li>Otherwise, the Framework must set this bundle's persistent autostart
245      * setting to <em>Started with declared activation</em> if the
246      * {@link #START_ACTIVATION_POLICY} option is set or
247      * <em>Started with eager activation</em> if not set.
248      * </ul>
249      * <p>
250      * When the Framework's current start level becomes equal to or more than
251      * this bundle's start level, this bundle will be started.
252      * <p>
253      * Otherwise, the following steps are required to start this bundle:
254      * <ol>
255      * <li>If this bundle is in the process of being activated or deactivated
256      * then this method must wait for activation or deactivation to complete
257      * before continuing. If this does not occur in a reasonable time, a
258      * <code>BundleException</code> is thrown to indicate this bundle was
259      * unable to be started.
260      *
261      * <li>If this bundle's state is <code>ACTIVE</code> then this method
262      * returns immediately.
263      *
264      * <li>If the {@link #START_TRANSIENT} option is not set then set this
265      * bundle's autostart setting to <em>Started with declared activation</em>
266      * if the {@link #START_ACTIVATION_POLICY} option is set or
267      * <em>Started with eager activation</em> if not set. When the Framework
268      * is restarted and this bundle's autostart setting is not <em>Stopped</em>,
269      * this bundle must be automatically started.
270      *
271      * <li>If this bundle's state is not <code>RESOLVED</code>, an attempt
272      * is made to resolve this bundle. If the Framework cannot resolve this
273      * bundle, a <code>BundleException</code> is thrown.
274      *
275      * <li>If the {@link #START_ACTIVATION_POLICY} option is set and this
276      * bundle's declared activation policy is
277      * {@link Constants#ACTIVATION_LAZY lazy} then:
278      * <ul>
279      * <li>If this bundle's state is <code>STARTING</code> then this method
280      * returns immediately.
281      * <li>This bundle's state is set to <code>STARTING</code>.
282      * <li>A bundle event of type {@link BundleEvent#LAZY_ACTIVATION} is fired.
283      * <li>This method returns immediately and the remaining steps will be
284      * followed when this bundle's activation is later triggered.
285      * </ul>
286      * <i></i>
287      * <li>This bundle's state is set to <code>STARTING</code>.
288      *
289      * <li>A bundle event of type {@link BundleEvent#STARTING} is fired.
290      *
291      * <li>The {@link BundleActivator#start} method of this bundle's
292      * <code>BundleActivator</code>, if one is specified, is called. If the
293      * <code>BundleActivator</code> is invalid or throws an exception then:
294      * <ul>
295      * <li>This bundle's state is set to <code>STOPPING</code>.
296      * <li>A bundle event of type {@link BundleEvent#STOPPING} is fired.
297      * <li>Any services registered by this bundle must be unregistered.
298      * <li>Any services used by this bundle must be released.
299      * <li>Any listeners registered by this bundle must be removed.
300      * <li>This bundle's state is set to <code>RESOLVED</code>.
301      * <li>A bundle event of type {@link BundleEvent#STOPPED} is fired.
302      * <li>A <code>BundleException</code> is then thrown.
303      * </ul>
304      * <i></i>
305      * <li>If this bundle's state is <code>UNINSTALLED</code>, because this
306      * bundle was uninstalled while the <code>BundleActivator.start</code>
307      * method was running, a <code>BundleException</code> is thrown.
308      *
309      * <li>This bundle's state is set to <code>ACTIVE</code>.
310      *
311      * <li>A bundle event of type {@link BundleEvent#STARTED} is fired.
312      * </ol>
313      *
314      * <b>Preconditions </b>
315      * <ul>
316      * <li><code>getState()</code> in {<code>INSTALLED</code>,
317      * <code>RESOLVED</code>} or {<code>INSTALLED</code>,
318      * <code>RESOLVED</code>, <code>STARTING</code>} if this bundle has a
319      * lazy activation policy.
320      * </ul>
321      * <b>Postconditions, no exceptions thrown </b>
322      * <ul>
323      * <li>Bundle autostart setting is modified unless the
324      * {@link #START_TRANSIENT} option was set.
325      * <li><code>getState()</code> in {<code>ACTIVE</code>} unless the
326      * lazy activation policy was used.
327      * <li><code>BundleActivator.start()</code> has been called and did not
328      * throw an exception unless the lazy activation policy was used.
329      * </ul>
330      * <b>Postconditions, when an exception is thrown </b>
331      * <ul>
332      * <li>Depending on when the exception occurred, bundle autostart setting
333      * is modified unless the {@link #START_TRANSIENT} option was set.
334      * <li><code>getState()</code> not in {<code>STARTING</code>,
335      * <code>ACTIVE</code>}.
336      * </ul>
337      *
338      * @param options The options for starting this bundle. See
339      * {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}.
340      * The Framework must ignore unrecognized options.
341      * @throws BundleException If this bundle could not be started. This could
342      * be because a code dependency could not be resolved or the
343      * specified <code>BundleActivator</code> could not be loaded or
344      * threw an exception or this bundle is a fragment.
345      * @throws java.lang.IllegalStateException If this bundle has been
346      * uninstalled or this bundle tries to change its own state.
347      * @throws java.lang.SecurityException If the caller does not have the
348      * appropriate <code>AdminPermission[this,EXECUTE]</code>, and
349      * the Java Runtime Environment supports permissions.
350      * @since 1.4
351      */
352     public void start(int options) throws BundleException;
353
354     /**
355      * Starts this bundle with no options.
356      *
357      * <p>
358      * This method calls <code>start(0)</code>.
359      *
360      * @throws BundleException If this bundle could not be started. This could
361      * be because a code dependency could not be resolved or the
362      * specified <code>BundleActivator</code> could not be loaded or
363      * threw an exception or this bundle is a fragment.
364      * @throws java.lang.IllegalStateException If this bundle has been
365      * uninstalled or this bundle tries to change its own state.
366      * @throws java.lang.SecurityException If the caller does not have the
367      * appropriate <code>AdminPermission[this,EXECUTE]</code>, and
368      * the Java Runtime Environment supports permissions.
369      * @see #start(int)
370      */
371     public void start() throws BundleException;
372
373     /**
374      * Stops this bundle.
375      *
376      * <p>
377      * The following steps are required to stop a bundle:
378      * <ol>
379      * <li>If this bundle's state is <code>UNINSTALLED</code> then an
380      * <code>IllegalStateException</code> is thrown.
381      *
382      * <li>If this bundle is in the process of being activated or deactivated
383      * then this method must wait for activation or deactivation to complete
384      * before continuing. If this does not occur in a reasonable time, a
385      * <code>BundleException</code> is thrown to indicate this bundle was
386      * unable to be stopped.
387      * <li>If the {@link #STOP_TRANSIENT} option is not set then then set this
388      * bundle's persistent autostart setting to to <em>Stopped</em>. When the
389      * Framework is restarted and this bundle's autostart setting is
390      * <em>Stopped</em>, this bundle must not be automatically started.
391      *
392      * <li>If this bundle's state is not <code>ACTIVE</code> then this method
393      * returns immediately.
394      *
395      * <li>This bundle's state is set to <code>STOPPING</code>.
396      *
397      * <li>A bundle event of type {@link BundleEvent#STOPPING} is fired.
398      *
399      * <li>The {@link BundleActivator#stop} method of this bundle's
400      * <code>BundleActivator</code>, if one is specified, is called. If that
401      * method throws an exception, this method must continue to stop this
402      * bundle. A <code>BundleException</code> must be thrown after completion
403      * of the remaining steps.
404      *
405      * <li>Any services registered by this bundle must be unregistered.
406      * <li>Any services used by this bundle must be released.
407      * <li>Any listeners registered by this bundle must be removed.
408      *
409      * <li>If this bundle's state is <code>UNINSTALLED</code>, because this
410      * bundle was uninstalled while the <code>BundleActivator.stop</code>
411      * method was running, a <code>BundleException</code> must be thrown.
412      *
413      * <li>This bundle's state is set to <code>RESOLVED</code>.
414      *
415      * <li>A bundle event of type {@link BundleEvent#STOPPED} is fired.
416      * </ol>
417      *
418      * <b>Preconditions </b>
419      * <ul>
420      * <li><code>getState()</code> in {<code>ACTIVE</code>}.
421      * </ul>
422      * <b>Postconditions, no exceptions thrown </b>
423      * <ul>
424      * <li>Bundle autostart setting is modified unless the
425      * {@link #STOP_TRANSIENT} option was set.
426      * <li><code>getState()</code> not in {<code>ACTIVE</code>,
427      * <code>STOPPING</code>}.
428      * <li><code>BundleActivator.stop</code> has been called and did not
429      * throw an exception.
430      * </ul>
431      * <b>Postconditions, when an exception is thrown </b>
432      * <ul>
433      * <li>Bundle autostart setting is modified unless the
434      * {@link #STOP_TRANSIENT} option was set.
435      * </ul>
436      *
437      * @param options The options for stoping this bundle. See
438      * {@link #STOP_TRANSIENT}. The Framework must ignore unrecognized
439      * options.
440      * @throws BundleException If this bundle's <code>BundleActivator</code>
441      * threw an exception or this bundle is a fragment.
442      * @throws java.lang.IllegalStateException If this bundle has been
443      * uninstalled or this bundle tries to change its own state.
444      * @throws java.lang.SecurityException If the caller does not have the
445      * appropriate <code>AdminPermission[this,EXECUTE]</code>, and
446      * the Java Runtime Environment supports permissions.
447      * @since 1.4
448      */
449     public void stop(int options) throws BundleException;
450
451     /**
452      * Stops this bundle with no options.
453      *
454      * <p>
455      * This method calls <code>stop(0)</code>.
456      *
457      * @throws BundleException If this bundle's <code>BundleActivator</code>
458      * threw an exception or this bundle is a fragment.
459      * @throws java.lang.IllegalStateException If this bundle has been
460      * uninstalled or this bundle tries to change its own state.
461      * @throws java.lang.SecurityException If the caller does not have the
462      * appropriate <code>AdminPermission[this,EXECUTE]</code>, and
463      * the Java Runtime Environment supports permissions.
464      * @see #start(int)
465      */
466     public void stop() throws BundleException;
467
468     /**
469      * Updates this bundle.
470      *
471      * <p>
472      * If this bundle's state is <code>ACTIVE</code>, it must be stopped
473      * before the update and started after the update successfully completes.
474      *
475      * <p>
476      * If this bundle has exported any packages, these packages must not be
477      * updated. Instead, the previous package version must remain exported until
478      * the <code>PackageAdmin.refreshPackages</code> method has been has been
479      * called or the Framework is relaunched.
480      *
481      * <p>
482      * The following steps are required to update a bundle:
483      * <ol>
484      * <li>If this bundle's state is <code>UNINSTALLED</code> then an
485      * <code>IllegalStateException</code> is thrown.
486      *
487      * <li>If this bundle's state is <code>ACTIVE</code>,
488      * <code>STARTING</code> or <code>STOPPING</code>, this bundle is
489      * stopped as described in the <code>Bundle.stop</code> method. If
490      * <code>Bundle.stop</code> throws an exception, the exception is rethrown
491      * terminating the update.
492      *
493      * <li>The download location of the new version of this bundle is
494      * determined from either this bundle's
495      * {@link Constants#BUNDLE_UPDATELOCATION} Manifest header (if available) or
496      * this bundle's original location.
497      *
498      * <li>The location is interpreted in an implementation dependent manner,
499      * typically as a URL, and the new version of this bundle is obtained from
500      * this location.
501      *
502      * <li>The new version of this bundle is installed. If the Framework is
503      * unable to install the new version of this bundle, the original version of
504      * this bundle must be restored and a <code>BundleException</code> must be
505      * thrown after completion of the remaining steps.
506      *
507      * <li>If this bundle has declared an Bundle-RequiredExecutionEnvironment
508      * header, then the listed execution environments must be verified against
509      * the installed execution environments. If they do not all match, the
510      * original version of this bundle must be restored and a
511      * <code>BundleException</code> must be thrown after completion of the
512      * remaining steps.
513      *
514      * <li>This bundle's state is set to <code>INSTALLED</code>.
515      *
516      * <li>If the new version of this bundle was successfully installed, a
517      * bundle event of type {@link BundleEvent#UPDATED} is fired.
518      *
519      * <li>If this bundle's state was originally <code>ACTIVE</code>, the
520      * updated bundle is started as described in the <code>Bundle.start</code>
521      * method. If <code>Bundle.start</code> throws an exception, a Framework
522      * event of type {@link FrameworkEvent#ERROR} is fired containing the
523      * exception.
524      * </ol>
525      *
526      * <b>Preconditions </b>
527      * <ul>
528      * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
529      * </ul>
530      * <b>Postconditions, no exceptions thrown </b>
531      * <ul>
532      * <li><code>getState()</code> in {<code>INSTALLED</code>,
533      * <code>RESOLVED</code>,<code>ACTIVE</code>}.
534      * <li>This bundle has been updated.
535      * </ul>
536      * <b>Postconditions, when an exception is thrown </b>
537      * <ul>
538      * <li><code>getState()</code> in {<code>INSTALLED</code>,
539      * <code>RESOLVED</code>,<code>ACTIVE</code>}.
540      * <li>Original bundle is still used; no update occurred.
541      * </ul>
542      *
543      * @throws BundleException If the update fails.
544      * @throws java.lang.IllegalStateException If this bundle has been
545      * uninstalled or this bundle tries to change its own state.
546      * @throws java.lang.SecurityException If the caller does not have the
547      * appropriate <code>AdminPermission[this,LIFECYCLE]</code> for
548      * both the current bundle and the updated bundle, and the Java
549      * Runtime Environment supports permissions.
550      * @see #stop()
551      * @see #start()
552      */
553     public void update() throws BundleException;
554
555     /**
556      * Updates this bundle from an <code>InputStream</code>.
557      *
558      * <p>
559      * This method performs all the steps listed in <code>Bundle.update()</code>,
560      * except the new version of this bundle must be read from the supplied
561      * <code>InputStream</code>, rather than a <code>URL</code>.
562      * <p>
563      * This method must always close the <code>InputStream</code> when it is
564      * done, even if an exception is thrown.
565      *
566      * @param in The <code>InputStream</code> from which to read the new
567      * bundle.
568      * @throws BundleException If the provided stream cannot be read or the
569      * update fails.
570      * @throws java.lang.IllegalStateException If this bundle has been
571      * uninstalled or this bundle tries to change its own state.
572      * @throws java.lang.SecurityException If the caller does not have the
573      * appropriate <code>AdminPermission[this,LIFECYCLE]</code> for
574      * both the current bundle and the updated bundle, and the Java
575      * Runtime Environment supports permissions.
576      * @see #update()
577      */
578     public void update(InputStream in) throws BundleException;
579
580     /**
581      * Uninstalls this bundle.
582      *
583      * <p>
584      * This method causes the Framework to notify other bundles that this bundle
585      * is being uninstalled, and then puts this bundle into the
586      * <code>UNINSTALLED</code> state. The Framework must remove any resources
587      * related to this bundle that it is able to remove.
588      *
589      * <p>
590      * If this bundle has exported any packages, the Framework must continue to
591      * make these packages available to their importing bundles until the
592      * <code>PackageAdmin.refreshPackages</code> method has been called or the
593      * Framework is relaunched.
594      *
595      * <p>
596      * The following steps are required to uninstall a bundle:
597      * <ol>
598      * <li>If this bundle's state is <code>UNINSTALLED</code> then an
599      * <code>IllegalStateException</code> is thrown.
600      *
601      * <li>If this bundle's state is <code>ACTIVE</code>,
602      * <code>STARTING</code> or <code>STOPPING</code>, this bundle is
603      * stopped as described in the <code>Bundle.stop</code> method. If
604      * <code>Bundle.stop</code> throws an exception, a Framework event of type
605      * {@link FrameworkEvent#ERROR} is fired containing the exception.
606      *
607      * <li>This bundle's state is set to <code>UNINSTALLED</code>.
608      *
609      * <li>A bundle event of type {@link BundleEvent#UNINSTALLED} is fired.
610      *
611      * <li>This bundle and any persistent storage area provided for this bundle
612      * by the Framework are removed.
613      * </ol>
614      *
615      * <b>Preconditions </b>
616      * <ul>
617      * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
618      * </ul>
619      * <b>Postconditions, no exceptions thrown </b>
620      * <ul>
621      * <li><code>getState()</code> in {<code>UNINSTALLED</code>}.
622      * <li>This bundle has been uninstalled.
623      * </ul>
624      * <b>Postconditions, when an exception is thrown </b>
625      * <ul>
626      * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
627      * <li>This Bundle has not been uninstalled.
628      * </ul>
629      *
630      * @throws BundleException If the uninstall failed. This can occur if
631      * another thread is attempting to change this bundle's state and
632      * does not complete in a timely manner.
633      * @throws java.lang.IllegalStateException If this bundle has been
634      * uninstalled or this bundle tries to change its own state.
635      * @throws java.lang.SecurityException If the caller does not have the
636      * appropriate <code>AdminPermission[this,LIFECYCLE]</code>, and
637      * the Java Runtime Environment supports permissions.
638      * @see #stop()
639      */
640     public void uninstall() throws BundleException;
641
642     /**
643      * Returns this bundle's Manifest headers and values. This method returns
644      * all the Manifest headers and values from the main section of this
645      * bundle's Manifest file; that is, all lines prior to the first blank line.
646      *
647      * <p>
648      * Manifest header names are case-insensitive. The methods of the returned
649      * <code>Dictionary</code> object must operate on header names in a
650      * case-insensitive manner.
651      *
652      * If a Manifest header value starts with &quot;%&quot;, it must be
653      * localized according to the default locale.
654      *
655      * <p>
656      * For example, the following Manifest headers and values are included if
657      * they are present in the Manifest file:
658      *
659      * <pre>
660      * Bundle-Name
661      * Bundle-Vendor
662      * Bundle-Version
663      * Bundle-Description
664      * Bundle-DocURL
665      * Bundle-ContactAddress
666      * </pre>
667      *
668      * <p>
669      * This method must continue to return Manifest header information while
670      * this bundle is in the <code>UNINSTALLED</code> state.
671      *
672      * @return A <code>Dictionary</code> object containing this bundle's
673      * Manifest headers and values.
674      *
675      * @throws java.lang.SecurityException If the caller does not have the
676      * appropriate <code>AdminPermission[this,METADATA]</code>, and
677      * the Java Runtime Environment supports permissions.
678      *
679      * @see Constants#BUNDLE_LOCALIZATION
680      */
681     public Dictionary getHeaders();
682
683     /**
684      * Returns this bundle's unique identifier. This bundle is assigned a unique
685      * identifier by the Framework when it was installed in the OSGi
686      * environment.
687      *
688      * <p>
689      * A bundle's unique identifier has the following attributes:
690      * <ul>
691      * <li>Is unique and persistent.
692      * <li>Is a <code>long</code>.
693      * <li>Its value is not reused for another bundle, even after a bundle is
694      * uninstalled.
695      * <li>Does not change while a bundle remains installed.
696      * <li>Does not change when a bundle is updated.
697      * </ul>
698      *
699      * <p>
700      * This method must continue to return this bundle's unique identifier while
701      * this bundle is in the <code>UNINSTALLED</code> state.
702      *
703      * @return The unique identifier of this bundle.
704      */
705     public long getBundleId();
706
707     /**
708      * Returns this bundle's location identifier.
709      *
710      * <p>
711      * The location identifier is the location passed to
712      * <code>BundleContext.installBundle</code> when a bundle is installed.
713      * The location identifier does not change while this bundle remains
714      * installed, even if this bundle is updated.
715      *
716      * <p>
717      * This method must continue to return this bundle's location identifier
718      * while this bundle is in the <code>UNINSTALLED</code> state.
719      *
720      * @return The string representation of this bundle's location identifier.
721      * @throws java.lang.SecurityException If the caller does not have the
722      * appropriate <code>AdminPermission[this,METADATA]</code>, and
723      * the Java Runtime Environment supports permissions.
724      */
725     public String getLocation();
726
727     /**
728      * Returns this bundle's <code>ServiceReference</code> list for all
729      * services it has registered or <code>null</code> if this bundle has no
730      * registered services.
731      *
732      * <p>
733      * If the Java runtime supports permissions, a <code>ServiceReference</code>
734      * object to a service is included in the returned list only if the caller
735      * has the <code>ServicePermission</code> to get the service using at
736      * least one of the named classes the service was registered under.
737      *
738      * <p>
739      * The list is valid at the time of the call to this method, however, as the
740      * Framework is a very dynamic environment, services can be modified or
741      * unregistered at anytime.
742      *
743      * @return An array of <code>ServiceReference</code> objects or
744      * <code>null</code>.
745      * @throws java.lang.IllegalStateException If this bundle has been
746      * uninstalled.
747      * @see ServiceRegistration
748      * @see ServiceReference
749      * @see ServicePermission
750      */
751     public ServiceReference[] getRegisteredServices();
752
753     /**
754      * Returns this bundle's <code>ServiceReference</code> list for all
755      * services it is using or returns <code>null</code> if this bundle is not
756      * using any services. A bundle is considered to be using a service if its
757      * use count for that service is greater than zero.
758      *
759      * <p>
760      * If the Java Runtime Environment supports permissions, a
761      * <code>ServiceReference</code> object to a service is included in the
762      * returned list only if the caller has the <code>ServicePermission</code>
763      * to get the service using at least one of the named classes the service
764      * was registered under.
765      * <p>
766      * The list is valid at the time of the call to this method, however, as the
767      * Framework is a very dynamic environment, services can be modified or
768      * unregistered at anytime.
769      *
770      * @return An array of <code>ServiceReference</code> objects or
771      * <code>null</code>.
772      * @throws java.lang.IllegalStateException If this bundle has been
773      * uninstalled.
774      * @see ServiceReference
775      * @see ServicePermission
776      */
777     public ServiceReference[] getServicesInUse();
778
779     /**
780      * Determines if this bundle has the specified permissions.
781      *
782      * <p>
783      * If the Java Runtime Environment does not support permissions, this method
784      * always returns <code>true</code>.
785      * <p>
786      * <code>permission</code> is of type <code>Object</code> to avoid
787      * referencing the <code>java.security.Permission</code> class directly.
788      * This is to allow the Framework to be implemented in Java environments
789      * which do not support permissions.
790      *
791      * <p>
792      * If the Java Runtime Environment does support permissions, this bundle and
793      * all its resources including embedded JAR files, belong to the same
794      * <code>java.security.ProtectionDomain</code>; that is, they must share
795      * the same set of permissions.
796      *
797      * @param permission The permission to verify.
798      *
799      * @return <code>true</code> if this bundle has the specified permission
800      * or the permissions possessed by this bundle imply the specified
801      * permission; <code>false</code> if this bundle does not have the
802      * specified permission or <code>permission</code> is not an
803      * <code>instanceof</code> <code>java.security.Permission</code>.
804      *
805      * @throws java.lang.IllegalStateException If this bundle has been
806      * uninstalled.
807      */
808     public boolean hasPermission(Object permission);
809
810     /**
811      * Find the specified resource from this bundle.
812      *
813      * This bundle's class loader is called to search for the specified
814      * resource. If this bundle's state is <code>INSTALLED</code>, this
815      * method must attempt to resolve this bundle before attempting to get the
816      * specified resource. If this bundle cannot be resolved, then only this
817      * bundle must be searched for the specified resource. Imported packages
818      * cannot be searched when this bundle has not been resolved. If this bundle
819      * is a fragment bundle then <code>null</code> is returned.
820      *
821      * @param name The name of the resource. See
822      * <code>java.lang.ClassLoader.getResource</code> for a description
823      * of the format of a resource name.
824      * @return A URL to the named resource, or <code>null</code> if the
825      * resource could not be found or if this bundle is a fragment
826      * bundle or if the caller does not have the appropriate
827      * <code>AdminPermission[this,RESOURCE]</code>, and the Java
828      * Runtime Environment supports permissions.
829      *
830      * @since 1.1
831      * @throws java.lang.IllegalStateException If this bundle has been
832      * uninstalled.
833      * @see #getEntry
834      * @see #findEntries
835      */
836     public URL getResource(String name);
837
838     /**
839      * Returns this bundle's Manifest headers and values localized to the
840      * specified locale.
841      *
842      * <p>
843      * This method performs the same function as
844      * <code>Bundle.getHeaders()</code> except the manifest header values are
845      * localized to the specified locale.
846      *
847      * <p>
848      * If a Manifest header value starts with &quot;%&quot;, it must be
849      * localized according to the specified locale. If a locale is specified and
850      * cannot be found, then the header values must be returned using the
851      * default locale. Localizations are searched for in the following order:
852      *
853      * <pre>
854      * bn + "_" + Ls + "_" + Cs + "_" + Vs
855      * bn + "_" + Ls + "_" + Cs
856      * bn + "_" + Ls
857      * bn + "_" + Ld + "_" + Cd + "_" + Vd
858      * bn + "_" + Ld + "_" + Cd
859      * bn + "_" + Ld
860      * bn
861      * </pre>
862      *
863      * Where <code>bn</code> is this bundle's localization basename,
864      * <code>Ls</code>, <code>Cs</code> and <code>Vs</code> are the
865      * specified locale (language, country, variant) and <code>Ld</code>,
866      * <code>Cd</code> and <code>Vd</code> are the default locale (language,
867      * country, variant).
868      *
869      * If <code>null</code> is specified as the locale string, the header
870      * values must be localized using the default locale. If the empty string
871      * (&quot;&quot;) is specified as the locale string, the header values must
872      * not be localized and the raw (unlocalized) header values, including any
873      * leading &quot;%&quot;, must be returned.
874      *
875      * <p>
876      * This method must continue to return Manifest header information while
877      * this bundle is in the <code>UNINSTALLED</code> state, however the
878      * header values must only be available in the raw and default locale
879      * values.
880      *
881      * @param locale The locale name into which the header values are to be
882      * localized. If the specified locale is <code>null</code> then the
883      * locale returned by <code>java.util.Locale.getDefault</code> is
884      * used. If the specified locale is the empty string, this method
885      * will return the raw (unlocalized) manifest headers including any
886      * leading &quot;%&quot;.
887      * @return A <code>Dictionary</code> object containing this bundle's
888      * Manifest headers and values.
889      *
890      * @throws java.lang.SecurityException If the caller does not have the
891      * appropriate <code>AdminPermission[this,METADATA]</code>, and
892      * the Java Runtime Environment supports permissions.
893      *
894      * @see #getHeaders()
895      * @see Constants#BUNDLE_LOCALIZATION
896      * @since 1.3
897      */
898     public Dictionary getHeaders(String locale);
899
900     /**
901      * Returns the symbolic name of this bundle as specified by its
902      * <code>Bundle-SymbolicName</code> manifest header. The name must be
903      * unique, it is recommended to use a reverse domain name naming convention
904      * like that used for java packages. If this bundle does not have a
905      * specified symbolic name then <code>null</code> is returned.
906      *
907      * <p>
908      * This method must continue to return this bundle's symbolic name while
909      * this bundle is in the <code>UNINSTALLED</code> state.
910      *
911      * @return The symbolic name of this bundle.
912      * @since 1.3
913      */
914     public String getSymbolicName();
915
916     /**
917      * Loads the specified class using this bundle's classloader.
918      *
919      * <p>
920      * If this bundle is a fragment bundle then this method must throw a
921      * <code>ClassNotFoundException</code>.
922      *
923      * <p>
924      * If this bundle's state is <code>INSTALLED</code>, this method must
925      * attempt to resolve this bundle before attempting to load the class.
926      *
927      * <p>
928      * If this bundle cannot be resolved, a Framework event of type
929      * {@link FrameworkEvent#ERROR} is fired containing a
930      * <code>BundleException</code> with details of the reason this bundle
931      * could not be resolved. This method must then throw a
932      * <code>ClassNotFoundException</code>.
933      *
934      * <p>
935      * If this bundle's state is <code>UNINSTALLED</code>, then an
936      * <code>IllegalStateException</code> is thrown.
937      *
938      * @param name The name of the class to load.
939      * @return The Class object for the requested class.
940      * @throws java.lang.ClassNotFoundException If no such class can be found or
941      * if this bundle is a fragment bundle or if the caller does not
942      * have the appropriate <code>AdminPermission[this,CLASS]</code>,
943      * and the Java Runtime Environment supports permissions.
944      * @throws java.lang.IllegalStateException If this bundle has been
945      * uninstalled.
946      * @since 1.3
947      */
948     public Class loadClass(String name) throws ClassNotFoundException ;
949
950     /**
951      * Find the specified resources from this bundle.
952      *
953      * This bundle's class loader is called to search for the specified
954      * resources. If this bundle's state is <code>INSTALLED</code>, this
955      * method must attempt to resolve this bundle before attempting to get the
956      * specified resources. If this bundle cannot be resolved, then only this
957      * bundle must be searched for the specified resources. Imported packages
958      * cannot be searched when a bundle has not been resolved. If this bundle is
959      * a fragment bundle then <code>null</code> is returned.
960      *
961      * @param name The name of the resource. See
962      * <code>java.lang.ClassLoader.getResources</code> for a
963      * description of the format of a resource name.
964      * @return An enumeration of URLs to the named resources, or
965      * <code>null</code> if the resource could not be found or if this
966      * bundle is a fragment bundle or if the caller does not have the
967      * appropriate <code>AdminPermission[this,RESOURCE]</code>, and
968      * the Java Runtime Environment supports permissions.
969      *
970      * @since 1.3
971      * @throws java.lang.IllegalStateException If this bundle has been
972      * uninstalled.
973      * @throws java.io.IOException If there is an I/O error.
974      */
975     public Enumeration getResources(String name) throws IOException ;
976
977     /**
978      * Returns an Enumeration of all the paths (<code>String</code> objects)
979      * to entries within this bundle whose longest sub-path matches the
980      * specified path. This bundle's classloader is not used to search for
981      * entries. Only the contents of this bundle are searched.
982      * <p>
983      * The specified path is always relative to the root of this bundle and may
984      * begin with a &quot;/&quot;. A path value of &quot;/&quot; indicates the
985      * root of this bundle.
986      * <p>
987      * Returned paths indicating subdirectory paths end with a &quot;/&quot;.
988      * The returned paths are all relative to the root of this bundle and must
989      * not begin with &quot;/&quot;.
990      *
991      * @param path The path name for which to return entry paths.
992      * @return An Enumeration of the entry paths (<code>String</code>
993      * objects) or <code>null</code> if no entry could be found or if
994      * the caller does not have the appropriate
995      * <code>AdminPermission[this,RESOURCE]</code> and the Java
996      * Runtime Environment supports permissions.
997      * @throws java.lang.IllegalStateException If this bundle has been
998      * uninstalled.
999      * @since 1.3
1000     */
1001    public Enumeration getEntryPaths(String path);
1002
1003    /**
1004     * Returns a URL to the entry at the specified path in this bundle. This
1005     * bundle's classloader is not used to search for the entry. Only the
1006     * contents of this bundle are searched for the entry.
1007     * <p>
1008     * The specified path is always relative to the root of this bundle and may
1009     * begin with &quot;/&quot;. A path value of &quot;/&quot; indicates the
1010     * root of this bundle.
1011     *
1012     * @param path The path name of the entry.
1013     * @return A URL to the entry, or <code>null</code> if no entry could be
1014     * found or if the caller does not have the appropriate
1015     * <code>AdminPermission[this,RESOURCE]</code> and the Java
1016     * Runtime Environment supports permissions.
1017     *
1018     * @throws java.lang.IllegalStateException If this bundle has been
1019     * uninstalled.
1020     * @since 1.3
1021     */
1022    public URL getEntry(String path);
1023
1024    /**
1025     * Returns the time when this bundle was last modified. A bundle is
1026     * considered to be modified when it is installed, updated or uninstalled.
1027     *
1028     * <p>
1029     * The time value is the number of milliseconds since January 1, 1970,
1030     * 00:00:00 GMT.
1031     *
1032     * @return The time when this bundle was last modified.
1033     * @since 1.3
1034     */
1035    public long getLastModified();
1036
1037    /**
1038     * Returns entries in this bundle and its attached fragments. This bundle's
1039     * classloader is not used to search for entries. Only the contents of this
1040     * bundle and its attached fragments are searched for the specified entries.
1041     *
1042     * If this bundle's state is <code>INSTALLED</code>, this method must
1043     * attempt to resolve this bundle before attempting to find entries.
1044     *
1045     * <p>
1046     * This method is intended to be used to obtain configuration, setup,
1047     * localization and other information from this bundle. This method takes
1048     * into account that the &quot;contents&quot; of this bundle can be extended
1049     * with fragments. This &quot;bundle space&quot; is not a namespace with
1050     * unique members; the same entry name can be present multiple times. This
1051     * method therefore returns an enumeration of URL objects. These URLs can
1052     * come from different JARs but have the same path name. This method can
1053     * either return only entries in the specified path or recurse into
1054     * subdirectories returning entries in the directory tree beginning at the
1055     * specified path. Fragments can be attached after this bundle is resolved,
1056     * possibly changing the set of URLs returned by this method. If this bundle
1057     * is not resolved, only the entries in the JAR file of this bundle are
1058     * returned.
1059     * <p>
1060     * Examples:
1061     *
1062     * <pre>
1063     * // List all XML files in the OSGI-INF directory and below
1064     * Enumeration e = b.findEntries(&quot;OSGI-INF&quot;, &quot;*.xml&quot;, true);
1065     *
1066     * // Find a specific localization file
1067     * Enumeration e = b.findEntries(&quot;OSGI-INF/l10n&quot;,
1068     * &quot;bundle_nl_DU.properties&quot;,
1069     * false);
1070     * if (e.hasMoreElements())
1071     * return (URL) e.nextElement();
1072     * </pre>
1073     *
1074     * @param path The path name in which to look. The path is always relative
1075     * to the root of this bundle and may begin with &quot;/&quot;. A
1076     * path value of &quot;/&quot; indicates the root of this bundle.
1077     * @param filePattern The file name pattern for selecting entries in the
1078     * specified path. The pattern is only matched against the last
1079     * element of the entry path and it supports substring matching, as
1080     * specified in the Filter specification, using the wildcard
1081     * character (&quot;*&quot;). If null is specified, this is
1082     * equivalent to &quot;*&quot; and matches all files.
1083     * @param recurse If <code>true</code>, recurse into subdirectories.
1084     * Otherwise only return entries from the specified path.
1085     * @return An enumeration of URL objects for each matching entry, or
1086     * <code>null</code> if an entry could not be found or if the
1087     * caller does not have the appropriate
1088     * <code>AdminPermission[this,RESOURCE]</code>, and the Java
1089     * Runtime Environment supports permissions. The URLs are sorted
1090     * such that entries from this bundle are returned first followed by
1091     * the entries from attached fragments in ascending bundle id order.
1092     * If this bundle is a fragment, then only matching entries in this
1093     * fragment are returned.
1094     * @since 1.3
1095     */
1096    public Enumeration findEntries(String path, String filePattern,
1097            boolean recurse);
1098
1099    /**
1100     * Returns this bundle's {@link BundleContext}. The returned
1101     * <code>BundleContext</code> can be used by the caller to act on behalf
1102     * of this bundle.
1103     *
1104     * <p>
1105     * If this bundle is not in the {@link #STARTING}, {@link #ACTIVE}, or
1106     * {@link #STOPPING} states or this bundle is a fragment bundle, then this
1107     * bundle has no valid <code>BundleContext</code>. This method will
1108     * return <code>null</code> if this bundle has no valid
1109     * <code>BundleContext</code>.
1110     *
1111     * @return A <code>BundleContext</code> for this bundle or
1112     * <code>null</code> if this bundle has no valid
1113     * <code>BundleContext</code>.
1114     * @throws java.lang.SecurityException If the caller does not have the
1115     * appropriate <code>AdminPermission[this,CONTEXT]</code>, and
1116     * the Java Runtime Environment supports permissions.
1117     * @since 1.4
1118     */
1119    public BundleContext getBundleContext();
1120}
1121

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags