1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
/*
* Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.packageadmin;
import org.osgi.framework.Bundle;
/**
* Framework service which allows bundle programmers to inspect the package
* wiring state of bundles in the Framework as well as other functions related
* to the class loader network among bundles.
*
* <p>
* If present, there will only be a single instance of this service registered
* with the Framework.
*
* @ThreadSafe
* @noimplement
* @author $Id$
* @deprecated This service has been replaced by the
* <code>org.osgi.framework.wiring</code> package.
* @see org.osgi.service.packageadmin.ExportedPackage
* @see org.osgi.service.packageadmin.RequiredBundle
*/
public interface PackageAdmin {
/**
* Gets the exported packages for the specified bundle.
*
* @param bundle The bundle whose exported packages are to be returned, or
* {@code null} if all exported packages are to be returned. If
* the specified bundle is the system bundle (that is, the bundle
* with id zero), this method returns all the packages known to be
* exported by the system bundle. This will include the package
* specified by the {@code org.osgi.framework.system.packages}
* system property as well as any other package exported by the
* framework implementation.
*
* @return An array of exported packages, or {@code null} if the
* specified bundle has no exported packages.
* @throws IllegalArgumentException If the specified {@code Bundle} was
* not created by the same framework instance that registered this
* {@code PackageAdmin} service.
*/
public ExportedPackage[] getExportedPackages(Bundle bundle);
/**
* Gets the exported packages for the specified package name.
*
* @param name The name of the exported packages to be returned.
*
* @return An array of the exported packages, or {@code null} if no
* exported packages with the specified name exists.
* @since 1.2
*/
public ExportedPackage[] getExportedPackages(String name);
/**
* Gets the exported package for the specified package name.
*
* <p>
* If there are multiple exported packages with specified name, the exported
* package with the highest version will be returned.
*
* @param name The name of the exported package to be returned.
*
* @return The exported package, or {@code null} if no exported
* package with the specified name exists.
* @see #getExportedPackages(String)
*/
public ExportedPackage getExportedPackage(String name);
/**
* Forces the update (replacement) or removal of packages exported by the
* specified bundles.
*
* <p>
* If no bundles are specified, this method will update or remove any
* packages exported by any bundles that were previously updated or
* uninstalled since the last call to this method. The technique by which
* this is accomplished may vary among different Framework implementations.
* One permissible implementation is to stop and restart the Framework.
*
* <p>
* This method returns to the caller immediately and then performs the
* following steps on a separate thread:
*
* <ol>
* <li>Compute a graph of bundles starting with the specified bundles. If no
* bundles are specified, compute a graph of bundles starting with bundle
* updated or uninstalled since the last call to this method. Add to the
* graph any bundle that is wired to a package that is currently exported by
* a bundle in the graph. The graph is fully constructed when there is no
* bundle outside the graph that is wired to a bundle in the graph. The
* graph may contain {@code UNINSTALLED} bundles that are currently still
* exporting packages.</li>
*
* <li>Each bundle in the graph that is in the {@code ACTIVE} state will be
* stopped as described in the {@code Bundle.stop} method.</li>
*
* <li>Each bundle in the graph that is in the {@code RESOLVED} state is
* unresolved and thus moved to the {@code INSTALLED} state. The effect of
* this step is that bundles in the graph are no longer {@code RESOLVED}.</li>
*
* <li>Each bundle in the graph that is in the {@code UNINSTALLED} state is
* removed from the graph and is now completely removed from the Framework.</li>
*
* <li>Each bundle in the graph that was in the {@code ACTIVE} state prior
* to Step 2 is started as described in the {@code Bundle.start} method,
* causing all bundles required for the restart to be resolved. It is
* possible that, as a result of the previous steps, packages that were
* previously exported no longer are. Therefore, some bundles may be
* unresolvable until another bundle offering a compatible package for
* export has been installed in the Framework.</li>
* <li>A framework event of type {@code FrameworkEvent.PACKAGES_REFRESHED}
* is fired.</li>
* </ol>
*
* <p>
* For any exceptions that are thrown during any of these steps, a
* {@code FrameworkEvent} of type {@code ERROR} is fired
* containing the exception. The source bundle for these events should be
* the specific bundle to which the exception is related. If no specific
* bundle can be associated with the exception then the System Bundle must
* be used as the source bundle for the event.
*
* @param bundles The bundles whose exported packages are to be updated or
* removed, or {@code null} for all bundles updated or
* uninstalled since the last call to this method.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[System Bundle,RESOLVE]} and the Java
* runtime environment supports permissions.
* @throws IllegalArgumentException If the specified {@code Bundle}s
* were not created by the same framework instance that registered
* this {@code PackageAdmin} service.
*/
public void refreshPackages(Bundle[] bundles);
/**
* Resolve the specified bundles. The Framework must attempt to resolve the
* specified bundles that are unresolved. Additional bundles that are not
* included in the specified bundles may be resolved as a result of calling
* this method. A permissible implementation of this method is to attempt to
* resolve all unresolved bundles installed in the framework.
*
* <p>
* If {@code null} is specified then the Framework will attempt to
* resolve all unresolved bundles. This method must not cause any bundle to
* be refreshed, stopped, or started. This method will not return until the
* operation has completed.
*
* @param bundles The bundles to resolve or {@code null} to resolve all
* unresolved bundles installed in the Framework.
* @return {@code true} if all specified bundles are resolved;
* @throws SecurityException If the caller does not have
* {@code AdminPermission[System Bundle,RESOLVE]} and the Java
* runtime environment supports permissions.
* @throws IllegalArgumentException If the specified {@code Bundle}s
* were not created by the same framework instance that registered
* this {@code PackageAdmin} service.
* @since 1.2
*/
public boolean resolveBundles(Bundle[] bundles);
/**
* Returns an array of required bundles having the specified symbolic name.
*
* <p>
* If {@code null} is specified, then all required bundles will be
* returned.
*
* @param symbolicName The bundle symbolic name or {@code null} for
* all required bundles.
* @return An array of required bundles or {@code null} if no
* required bundles exist for the specified symbolic name.
* @since 1.2
*/
public RequiredBundle[] getRequiredBundles(String symbolicName);
/**
* Returns the bundles with the specified symbolic name whose bundle version
* is within the specified version range. If no bundles are installed that
* have the specified symbolic name, then {@code null} is returned.
* If a version range is specified, then only the bundles that have the
* specified symbolic name and whose bundle versions belong to the specified
* version range are returned. The returned bundles are ordered by version
* in descending version order so that the first element of the array
* contains the bundle with the highest version.
*
* @see org.osgi.framework.Constants#BUNDLE_VERSION_ATTRIBUTE
* @param symbolicName The symbolic name of the desired bundles.
* @param versionRange The version range of the desired bundles, or
* {@code null} if all versions are desired.
* @return An array of bundles with the specified name belonging to the
* specified version range ordered in descending version order, or
* {@code null} if no bundles are found.
* @since 1.2
*/
public Bundle[] getBundles(String symbolicName, String versionRange);
/**
* Returns an array of attached fragment bundles for the specified bundle.
* If the specified bundle is a fragment then {@code null} is returned.
* If no fragments are attached to the specified bundle then
* {@code null} is returned.
* <p>
* This method does not attempt to resolve the specified bundle. If the
* specified bundle is not resolved then {@code null} is returned.
*
* @param bundle The bundle whose attached fragment bundles are to be
* returned.
* @return An array of fragment bundles or {@code null} if the bundle
* does not have any attached fragment bundles or the bundle is not
* resolved.
* @throws IllegalArgumentException If the specified {@code Bundle} was
* not created by the same framework instance that registered this
* {@code PackageAdmin} service.
* @since 1.2
*/
public Bundle[] getFragments(Bundle bundle);
/**
* Returns the host bundles to which the specified fragment bundle is
* attached.
*
* @param bundle The fragment bundle whose host bundles are to be returned.
* @return An array containing the host bundles to which the specified
* fragment is attached or {@code null} if the specified bundle
* is not a fragment or is not attached to any host bundles.
* @throws IllegalArgumentException If the specified {@code Bundle} was
* not created by the same framework instance that registered this
* {@code PackageAdmin} service.
* @since 1.2
*/
public Bundle[] getHosts(Bundle bundle);
/**
* Returns the bundle from which the specified class is loaded. The class
* loader of the returned bundle must have been used to load the specified
* class. If the class was not loaded by a bundle class loader then
* {@code null} is returned.
*
* @param clazz The class object from which to locate the bundle.
* @return The bundle from which the specified class is loaded or
* {@code null} if the class was not loaded by a bundle class
* loader created by the same framework instance that registered
* this {@code PackageAdmin} service.
* @since 1.2
*/
public Bundle getBundle(Class clazz);
/**
* Bundle type indicating the bundle is a fragment bundle.
*
* <p>
* The value of {@code BUNDLE_TYPE_FRAGMENT} is 0x00000001.
*
* @since 1.2
*/
public static final int BUNDLE_TYPE_FRAGMENT = 0x00000001;
/**
* Returns the special type of the specified bundle. The bundle type values
* are:
* <ul>
* <li>{@link #BUNDLE_TYPE_FRAGMENT}</li>
* </ul>
*
* A bundle may be more than one type at a time. A type code is used to
* identify the bundle type for future extendability.
*
* <p>
* If a bundle is not one or more of the defined types then 0x00000000 is
* returned.
*
* @param bundle The bundle for which to return the special type.
* @return The special type of the bundle.
* @throws IllegalArgumentException If the specified {@code Bundle} was
* not created by the same framework instance that registered this
* {@code PackageAdmin} service.
* @since 1.2
*/
public int getBundleType(Bundle bundle);
}
|
