org.osgi/src/main/java/org/osgi/service/packageadmin/PackageAdmin.java - onos-felix - Gitiles

 /*
  * $Header: /cvshome/build/org.osgi.service.packageadmin/src/org/osgi/service/packageadmin/PackageAdmin.java,v 1.10 2005/05/13 20:32:34 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2001, 2005). All Rights Reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0 which accompanies this
  * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
  */

 package org.osgi.service.packageadmin;

 import org.osgi.framework.Bundle;

 /**
  * Framework service which allows bundle programmers to inspect the packages
  * exported in the Framework and eagerly update or uninstall bundles.
  *
  * If present, there will only be a single instance of this service registered
  * with the Framework.
  *
  * <p>
  * The term <i>exported package </i> (and the corresponding interface
  * {@link ExportedPackage})refers to a package that has actually been exported
  * (as opposed to one that is available for export).
  *
  * <p>
  * The information about exported packages returned by this service is valid
  * only until the next time {@link #refreshPackages}is called. If an
  * <code>ExportedPackage</code> object becomes stale, (that is, the package it
  * references has been updated or removed as a result of calling
  * <code>PackageAdmin.refreshPackages()</code>), its <code>getName()</code> and
  * <code>getSpecificationVersion()</code> continue to return their old values,
  * <code>isRemovalPending()</code> returns <code>true</code>, and
  * <code>getExportingBundle()</code> and <code>getImportingBundles()</code> return
  * <code>null</code>.
  *
  * @version $Revision: 1.10 $
  */
 public interface PackageAdmin {
 	/**
 	 * Gets the packages exported by the specified bundle.
 	 *
 	 * @param bundle The bundle whose exported packages are to be returned, or
 	 *        <code>null</code> if all the packages currently exported in the
 	 *        Framework 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 on the system classpath whose name does
 	 *        not start with "java.". In an environment where the exhaustive
 	 *        list of packages on the system classpath is not known in advance,
 	 *        this method will return all currently known packages on the system
 	 *        classpath, that is, all packages on the system classpath that
 	 *        contains one or more classes that have been loaded.
 	 *
 	 * @return The array of packages exported by the specified bundle, or
 	 *         <code>null</code> if the specified bundle has not exported any
 	 *         packages.
 	 */
 	public ExportedPackage[] getExportedPackages(Bundle bundle);

 	/**
 	 * Gets the <code>ExportedPackage</code> object with the specified package
 	 * name. All exported packages will be checked for the specified name. The
 	 * exported package with the highest version will be returned.
 	 * <p>
 	 * In an environment where the exhaustive list of packages on the system
 	 * classpath is not known in advance, this method attempts to see if the
 	 * named package is on the system classpath. This means that this method may
 	 * discover an <code>ExportedPackage</code> object that was not present in the
 	 * list returned by a prior call to <code>getExportedPackages()</code>.
 	 *
 	 * @param name The name of the exported package to be returned.
 	 *
 	 * @return The exported package with the specified name, or <code>null</code>
 	 *         if no exported packages with that name exists.
 	 */
 	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 in its own 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
 	 * previously updated or uninstalled ones. Add to the graph any bundle that
 	 * imports 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 imports a package from a bundle in the graph. The graph may contain
 	 * <code>UNINSTALLED</code> bundles that are currently still exporting
 	 * packages.
 	 *
 	 * <li>Each bundle in the graph that is in the <code>ACTIVE</code> state will
 	 * be stopped as described in the <code>Bundle.stop</code> method.
 	 *
 	 * <li>Each bundle in the graph that is in the <code>RESOLVED</code> state is
 	 * moved to the <code>INSTALLED</code> state. The effect of this step is that
 	 * bundles in the graph are no longer <code>RESOLVED</code>.
 	 *
 	 * <li>Each bundle in the graph that is in the <code>UNINSTALLED</code> state
 	 * is removed from the graph and is now completely removed from the
 	 * Framework.
 	 *
 	 * <li>Each bundle in the graph that was in the <code>ACTIVE</code> state
 	 * prior to Step 2 is started as described in the <code>Bundle.start</code>
 	 * 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>A framework event of type <code>FrameworkEvent.PACKAGES_REFRESHED</code>
 	 * is broadcast.
 	 * </ol>
 	 *
 	 * <p>
 	 * For any exceptions that are thrown during any of these steps, a
 	 * <code>FrameworkEvent</code> of type <code>ERROR</code> is broadcast,
 	 * 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</code> for all previously updated or
 	 *        uninstalled bundles.
 	 *
 	 * @exception SecurityException if the caller does not have the
 	 *            <code>AdminPermission</code> and the Java runtime environment
 	 *            supports permissions.
 	 */
 	public void refreshPackages(Bundle[] bundles);

 	/**
 	 * Get the <code>ExportedPackage</code> objects with the specified
 	 * package name. All exported packages will be checked for the specified
 	 * name.
 	 * <p>
 	 * In an environment where the exhaustive list of packages on the system
 	 * classpath is not known in advance, this method attempts to see if the
 	 * named package is on the system classpath. This means that this method may
 	 * discover an <code>ExportedPackage</code> object that was not present in the
 	 * list returned by a prior call to <code>getExportedPackages()</code>.
 	 *
 	 * @param name The name of the exported packages to be returned.
 	 *
 	 * @return An array of the exported packages with the specified name, or
 	 *         <code>null</code> if no exported packages with that name exists.
 	 * @since 1.2
 	 */
 	public ExportedPackage[] getExportedPackages(String name);

 	/**
 	 * 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</code> 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</code> to resolve all
 	 *        unresolved bundles installed in the Framework.
 	 * @return <code>true</code> if all specified bundles are resolved;
 	 * @since 1.2
 	 */
 	public boolean resolveBundles(Bundle[] bundles);

 	/**
 	 * Returns an array of RequiredBundles with the specified symbolic name. If
 	 * the symbolic name argument is <code>null</code> then all RequiredBundles
 	 * are returned.
 	 *
 	 * @param symbolicName The symbolic name of the RequiredBundle or
 	 *        <code>null</code> for all RequiredBundles in the Framework.
 	 * @return An array of RequiredBundles with the specified symbolic name or
 	 *         <code>null</code> if no RequiredBundles exist with that symbolic
 	 *         name.
 	 * @since 1.2
 	 */
 	public RequiredBundle[] getRequiredBundles(String symbolicName);

 	/**
 	 * Returns the bundles with the specified symbolic name within the specified
 	 * version range. If no bundles are installed that have the specified
 	 * symbolic name, then <code>null</code> is returned. If a version range is
 	 * specified, then only the bundles that have the specified symbolic name
 	 * and 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</code> 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</code> 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</code> is returned.
 	 * If no fragments are attached to the specified bundle then <code>null</code>
 	 * is returned.
 	 * <p>
 	 * This method does not attempt to resolve the specified bundle.  If the
 	 * specified bundle is not resolved then <code>null</code> is returned.
 	 *
 	 * @param bundle The bundle whose attached fragment bundles are to be
 	 *        returned.
 	 * @return An array of fragment bundles or <code>null</code> if the bundle
 	 *         does not have any attached fragment bundles or the bundle is not
 	 *         resolved.
 	 * @since 1.2
 	 */
 	public Bundle[] getFragments(Bundle bundle);

 	/**
 	 * Returns an array of host bundles to which the specified fragment bundle
 	 * is attached or <code>null</code> if the specified bundle is not attached to
 	 * a host or is not a fragment bundle.
 	 *
 	 * @param bundle The bundle whose host bundles are to be returned.
 	 * @return An array of host bundles or <code>null</code> if the bundle does
 	 *         not have any host bundles.
 	 * @since 1.2
 	 */
 	public Bundle[] getHosts(Bundle bundle);

 	/**
 	 * Returns the bundle for which the specified class is loaded from. The
 	 * classloader of the bundle returned must have been used to load the
 	 * specified class. If the class was not loaded by a bundle classloader then
 	 * <code>null</code> is returned.
 	 *
 	 * @param clazz the class object to get a bundle for
 	 * @return the bundle from which the specified class is loaded or
 	 *         <code>null</code> if the class was not loaded by a bundle
 	 *         classloader
 	 * @since 1.2
 	 */
 	public Bundle getBundle(Class clazz);

 	/**
 	 * The bundle is a fragment bundle.
 	 *
 	 * <p>
 	 * The value of <code>BUNDLE_TYPE_FRAGMENT</code> 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}
 	 * </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.
 	 *
 	 * @return The special type of the bundle.
 	 * @since 1.2
 	 */
 	public int getBundleType(Bundle bundle);
 }
	/*
	* $Header: /cvshome/build/org.osgi.service.packageadmin/src/org/osgi/service/packageadmin/PackageAdmin.java,v 1.10 2005/05/13 20:32:34 hargrave Exp $
	*
	* Copyright (c) OSGi Alliance (2001, 2005). All Rights Reserved.
	*
	* This program and the accompanying materials are made available under the
	* terms of the Eclipse Public License v1.0 which accompanies this
	* distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
	*/

	package org.osgi.service.packageadmin;

	import org.osgi.framework.Bundle;

	/**
	* Framework service which allows bundle programmers to inspect the packages
	* exported in the Framework and eagerly update or uninstall bundles.
	*
	* If present, there will only be a single instance of this service registered
	* with the Framework.
	*
	* <p>
	* The term <i>exported package </i> (and the corresponding interface
	* {@link ExportedPackage})refers to a package that has actually been exported
	* (as opposed to one that is available for export).
	*
	* <p>
	* The information about exported packages returned by this service is valid
	* only until the next time {@link #refreshPackages}is called. If an
	* <code>ExportedPackage</code> object becomes stale, (that is, the package it
	* references has been updated or removed as a result of calling
	* <code>PackageAdmin.refreshPackages()</code>), its <code>getName()</code> and
	* <code>getSpecificationVersion()</code> continue to return their old values,
	* <code>isRemovalPending()</code> returns <code>true</code>, and
	* <code>getExportingBundle()</code> and <code>getImportingBundles()</code> return
	* <code>null</code>.
	*
	* @version $Revision: 1.10 $
	*/
	public interface PackageAdmin {
	/**
	* Gets the packages exported by the specified bundle.
	*
	* @param bundle The bundle whose exported packages are to be returned, or
	* <code>null</code> if all the packages currently exported in the
	* Framework 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 on the system classpath whose name does
	* not start with "java.". In an environment where the exhaustive
	* list of packages on the system classpath is not known in advance,
	* this method will return all currently known packages on the system
	* classpath, that is, all packages on the system classpath that
	* contains one or more classes that have been loaded.
	*
	* @return The array of packages exported by the specified bundle, or
	* <code>null</code> if the specified bundle has not exported any
	* packages.
	*/
	public ExportedPackage[] getExportedPackages(Bundle bundle);

	/**
	* Gets the <code>ExportedPackage</code> object with the specified package
	* name. All exported packages will be checked for the specified name. The
	* exported package with the highest version will be returned.
	* <p>
	* In an environment where the exhaustive list of packages on the system
	* classpath is not known in advance, this method attempts to see if the
	* named package is on the system classpath. This means that this method may
	* discover an <code>ExportedPackage</code> object that was not present in the
	* list returned by a prior call to <code>getExportedPackages()</code>.
	*
	* @param name The name of the exported package to be returned.
	*
	* @return The exported package with the specified name, or <code>null</code>
	* if no exported packages with that name exists.
	*/
	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 in its own 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
	* previously updated or uninstalled ones. Add to the graph any bundle that
	* imports 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 imports a package from a bundle in the graph. The graph may contain
	* <code>UNINSTALLED</code> bundles that are currently still exporting
	* packages.
	*
	* <li>Each bundle in the graph that is in the <code>ACTIVE</code> state will
	* be stopped as described in the <code>Bundle.stop</code> method.
	*
	* <li>Each bundle in the graph that is in the <code>RESOLVED</code> state is
	* moved to the <code>INSTALLED</code> state. The effect of this step is that
	* bundles in the graph are no longer <code>RESOLVED</code>.
	*
	* <li>Each bundle in the graph that is in the <code>UNINSTALLED</code> state
	* is removed from the graph and is now completely removed from the
	* Framework.
	*
	* <li>Each bundle in the graph that was in the <code>ACTIVE</code> state
	* prior to Step 2 is started as described in the <code>Bundle.start</code>
	* 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>A framework event of type <code>FrameworkEvent.PACKAGES_REFRESHED</code>
	* is broadcast.
	* </ol>
	*
	* <p>
	* For any exceptions that are thrown during any of these steps, a
	* <code>FrameworkEvent</code> of type <code>ERROR</code> is broadcast,
	* 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</code> for all previously updated or
	* uninstalled bundles.
	*
	* @exception SecurityException if the caller does not have the
	* <code>AdminPermission</code> and the Java runtime environment
	* supports permissions.
	*/
	public void refreshPackages(Bundle[] bundles);

	/**
	* Get the <code>ExportedPackage</code> objects with the specified
	* package name. All exported packages will be checked for the specified
	* name.
	* <p>
	* In an environment where the exhaustive list of packages on the system
	* classpath is not known in advance, this method attempts to see if the
	* named package is on the system classpath. This means that this method may
	* discover an <code>ExportedPackage</code> object that was not present in the
	* list returned by a prior call to <code>getExportedPackages()</code>.
	*
	* @param name The name of the exported packages to be returned.
	*
	* @return An array of the exported packages with the specified name, or
	* <code>null</code> if no exported packages with that name exists.
	* @since 1.2
	*/
	public ExportedPackage[] getExportedPackages(String name);

	/**
	* 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</code> 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</code> to resolve all
	* unresolved bundles installed in the Framework.
	* @return <code>true</code> if all specified bundles are resolved;
	* @since 1.2
	*/
	public boolean resolveBundles(Bundle[] bundles);

	/**
	* Returns an array of RequiredBundles with the specified symbolic name. If
	* the symbolic name argument is <code>null</code> then all RequiredBundles
	* are returned.
	*
	* @param symbolicName The symbolic name of the RequiredBundle or
	* <code>null</code> for all RequiredBundles in the Framework.
	* @return An array of RequiredBundles with the specified symbolic name or
	* <code>null</code> if no RequiredBundles exist with that symbolic
	* name.
	* @since 1.2
	*/
	public RequiredBundle[] getRequiredBundles(String symbolicName);

	/**
	* Returns the bundles with the specified symbolic name within the specified
	* version range. If no bundles are installed that have the specified
	* symbolic name, then <code>null</code> is returned. If a version range is
	* specified, then only the bundles that have the specified symbolic name
	* and 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</code> 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</code> 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</code> is returned.
	* If no fragments are attached to the specified bundle then <code>null</code>
	* is returned.
	* <p>
	* This method does not attempt to resolve the specified bundle. If the
	* specified bundle is not resolved then <code>null</code> is returned.
	*
	* @param bundle The bundle whose attached fragment bundles are to be
	* returned.
	* @return An array of fragment bundles or <code>null</code> if the bundle
	* does not have any attached fragment bundles or the bundle is not
	* resolved.
	* @since 1.2
	*/
	public Bundle[] getFragments(Bundle bundle);

	/**
	* Returns an array of host bundles to which the specified fragment bundle
	* is attached or <code>null</code> if the specified bundle is not attached to
	* a host or is not a fragment bundle.
	*
	* @param bundle The bundle whose host bundles are to be returned.
	* @return An array of host bundles or <code>null</code> if the bundle does
	* not have any host bundles.
	* @since 1.2
	*/
	public Bundle[] getHosts(Bundle bundle);

	/**
	* Returns the bundle for which the specified class is loaded from. The
	* classloader of the bundle returned must have been used to load the
	* specified class. If the class was not loaded by a bundle classloader then
	* <code>null</code> is returned.
	*
	* @param clazz the class object to get a bundle for
	* @return the bundle from which the specified class is loaded or
	* <code>null</code> if the class was not loaded by a bundle
	* classloader
	* @since 1.2
	*/
	public Bundle getBundle(Class clazz);

	/**
	* The bundle is a fragment bundle.
	*
	* <p>
	* The value of <code>BUNDLE_TYPE_FRAGMENT</code> 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}
	* </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.
	*
	* @return The special type of the bundle.
	* @since 1.2
	*/
	public int getBundleType(Bundle bundle);
	}