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