PackageAdmin


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