org.eclipse.osgi.framework.internal.core
Class PackageAdminImpl

java.lang.Object
  org.eclipse.osgi.framework.internal.core.PackageAdminImpl

All Implemented Interfaces:

BundleReference, FrameworkWiring, PackageAdmin

public class PackageAdminImpl
extends java.lang.Object
implements PackageAdmin, FrameworkWiring

PackageAdmin service for the OSGi specification. 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 in the framework.

The term exported package (and the corresponding interface ExportedPackage) refers to a package that has actually been exported (as opposed to one that is available for export).

Note that the information about exported packages returned by this service is valid only until the next time refreshPackages(org.osgi.framework.Bundle[]) is called. If an ExportedPackage becomes stale, (that is, the package it references has been updated or removed as a result of calling PackageAdmin.refreshPackages()), its getName() and getSpecificationVersion() continue to return their old values, isRemovalPending() returns true, and getExportingBundle() and getImportingBundles() return null.

Field Summary

protected Framework

framework framework object

Fields inherited from interface org.osgi.service.packageadmin.PackageAdmin

BUNDLE_TYPE_FRAGMENT

Constructor Summary

protected

PackageAdminImpl(Framework framework) Constructor.

Method Summary

protected void	cleanup()
protected void	doResolveBundles(Bundle[] bundles, boolean refreshPackages, FrameworkListener[] listeners)
Bundle	getBundle() Returns the Bundle object associated with this BundleReference.
Bundle	getBundle(java.lang.Class clazz) Returns the bundle from which the specified class is loaded.
Bundle[]	getBundles(java.lang.String symbolicName, java.lang.String versionRange) Returns the bundles with the specified symbolic name whose bundle version is within the specified version range.
int	getBundleType(Bundle bundle) Returns the special type of the specified bundle.
java.util.Collection<Bundle>	getDependencyClosure(java.util.Collection<Bundle> bundles) Returns the dependency closure for the specified bundles.
ExportedPackage	getExportedPackage(java.lang.String name) Gets the exported package for the specified package name.
ExportedPackage[]	getExportedPackages(Bundle bundle) Gets the exported packages for the specified bundle.
ExportedPackage[]	getExportedPackages(java.lang.String name) Gets the exported packages for the specified package name.
Bundle[]	getFragments(Bundle bundle) Returns an array of attached fragment bundles for the specified bundle.
Bundle[]	getHosts(Bundle bundle) Returns the host bundles to which the specified fragment bundle is attached.
java.util.Collection<Bundle>	getRemovalPendingBundles() Returns the bundles that have non-current, in use bundle wirings.
RequiredBundle[]	getRequiredBundles(java.lang.String symbolicName) Returns an array of required bundles having the specified symbolic name.
void	refreshBundles(java.util.Collection<Bundle> bundles, FrameworkListener... listeners) Refreshes the specified bundles.
void	refreshPackages(Bundle[] input) Forces the update (replacement) or removal of packages exported by the specified bundles.
void	refreshPackages(Bundle[] input, boolean synchronously, FrameworkListener[] listeners)
boolean	resolveBundles(Bundle[] bundles) Resolve the specified bundles.
boolean	resolveBundles(java.util.Collection<Bundle> bundles) Resolves the specified bundles.
protected void	setResolvedBundles(InternalSystemBundle systemBundle)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

framework

protected Framework framework

framework object

Constructor Detail

PackageAdminImpl

protected PackageAdminImpl(Framework framework)

Constructor.

Parameters:

framework - Framework object.

Method Detail

getExportedPackages

public ExportedPackage[] getExportedPackages(Bundle bundle)

Description copied from interface: PackageAdmin

Gets the exported packages for the specified bundle.

Specified by:

getExportedPackages in interface PackageAdmin

Parameters:

bundle - The bundle whose exported packages are to be returned, or 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 org.osgi.framework.system.packages system property as well as any other package exported by the framework implementation.

Returns:

An array of exported packages, or null if the specified bundle has no exported packages.

getExportedPackage

public ExportedPackage getExportedPackage(java.lang.String name)

Description copied from interface: PackageAdmin

Gets the exported package for the specified package name.

If there are multiple exported packages with specified name, the exported package with the highest version will be returned.

Specified by:

getExportedPackage in interface PackageAdmin

Parameters:

name - The name of the exported package to be returned.

Returns:

The exported package, or null if no exported package with the specified name exists.

See Also:

PackageAdmin.getExportedPackages(String)

getExportedPackages

public ExportedPackage[] getExportedPackages(java.lang.String name)

Description copied from interface: PackageAdmin

Gets the exported packages for the specified package name.

Specified by:

getExportedPackages in interface PackageAdmin

Parameters:

name - The name of the exported packages to be returned.

Returns:

An array of the exported packages, or null if no exported packages with the specified name exists.

refreshPackages

public void refreshPackages(Bundle[] input)

Description copied from interface: PackageAdmin

Forces the update (replacement) or removal of packages exported by the specified bundles.

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.

This method returns to the caller immediately and then performs the following steps on a separate thread:

1. 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 UNINSTALLED bundles that are currently still exporting packages.
2. Each bundle in the graph that is in the ACTIVE state will be stopped as described in the Bundle.stop method.
3. Each bundle in the graph that is in the RESOLVED state is unresolved and thus moved to the INSTALLED state. The effect of this step is that bundles in the graph are no longer RESOLVED.
4. Each bundle in the graph that is in the UNINSTALLED state is removed from the graph and is now completely removed from the Framework.
5. Each bundle in the graph that was in the ACTIVE state prior to Step 2 is started as described in the 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.
6. A framework event of type FrameworkEvent.PACKAGES_REFRESHED is fired.

For any exceptions that are thrown during any of these steps, a FrameworkEvent of type 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.

Specified by:

refreshPackages in interface PackageAdmin

Parameters:

input - The bundles whose exported packages are to be updated or removed, or null for all bundles updated or uninstalled since the last call to this method.

refreshPackages

public void refreshPackages(Bundle[] input,
                            boolean synchronously,
                            FrameworkListener[] listeners)

resolveBundles

public boolean resolveBundles(Bundle[] bundles)

Description copied from interface: PackageAdmin

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.

If 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.

Specified by:

resolveBundles in interface PackageAdmin

Parameters:

bundles - The bundles to resolve or null to resolve all unresolved bundles installed in the Framework.

Returns:

true if all specified bundles are resolved;

doResolveBundles

protected void doResolveBundles(Bundle[] bundles,
                                boolean refreshPackages,
                                FrameworkListener[] listeners)

getRequiredBundles

public RequiredBundle[] getRequiredBundles(java.lang.String symbolicName)

Description copied from interface: PackageAdmin

Returns an array of required bundles having the specified symbolic name.

If null is specified, then all required bundles will be returned.

Specified by:

getRequiredBundles in interface PackageAdmin

Parameters:

symbolicName - The bundle symbolic name or null for all required bundles.

Returns:

An array of required bundles or null if no required bundles exist for the specified symbolic name.

getBundles

public Bundle[] getBundles(java.lang.String symbolicName,
                           java.lang.String versionRange)

Description copied from interface: PackageAdmin

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 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.

Specified by:

getBundles in interface PackageAdmin

Parameters:

symbolicName - The symbolic name of the desired bundles.

versionRange - The version range of the desired bundles, or null if all versions are desired.

Returns:

An array of bundles with the specified name belonging to the specified version range ordered in descending version order, or null if no bundles are found.

See Also:

Constants.BUNDLE_VERSION_ATTRIBUTE

getFragments

public Bundle[] getFragments(Bundle bundle)

Description copied from interface: PackageAdmin

Returns an array of attached fragment bundles for the specified bundle. If the specified bundle is a fragment then null is returned. If no fragments are attached to the specified bundle then null is returned.

This method does not attempt to resolve the specified bundle. If the specified bundle is not resolved then null is returned.

Specified by:

getFragments in interface PackageAdmin

Parameters:

bundle - The bundle whose attached fragment bundles are to be returned.

Returns:

An array of fragment bundles or null if the bundle does not have any attached fragment bundles or the bundle is not resolved.

getHosts

public Bundle[] getHosts(Bundle bundle)

Description copied from interface: PackageAdmin

Returns the host bundles to which the specified fragment bundle is attached.

Specified by:

getHosts in interface PackageAdmin

Parameters:

bundle - The fragment bundle whose host bundles are to be returned.

Returns:

An array containing the host bundles to which the specified fragment is attached or null if the specified bundle is not a fragment or is not attached to any host bundles.

getBundle

public Bundle getBundle(java.lang.Class clazz)

Description copied from interface: PackageAdmin

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 null is returned.

Specified by:

getBundle in interface PackageAdmin

Parameters:

clazz - The class object from which to locate the bundle.

Returns:

The bundle from which the specified class is loaded or null if the class was not loaded by a bundle class loader created by the same framework instance that registered this PackageAdmin service.

getBundleType

public int getBundleType(Bundle bundle)

Description copied from interface: PackageAdmin

Returns the special type of the specified bundle. The bundle type values are:

• PackageAdmin.BUNDLE_TYPE_FRAGMENT

A bundle may be more than one type at a time. A type code is used to identify the bundle type for future extendability.

If a bundle is not one or more of the defined types then 0x00000000 is returned.

Specified by:

getBundleType in interface PackageAdmin

Parameters:

bundle - The bundle for which to return the special type.

Returns:

The special type of the bundle.

cleanup

protected void cleanup()

setResolvedBundles

protected void setResolvedBundles(InternalSystemBundle systemBundle)

getBundle

public Bundle getBundle()

Description copied from interface: BundleReference

Returns the Bundle object associated with this BundleReference.

Specified by:

getBundle in interface BundleReference

Returns:

The Bundle object associated with this BundleReference.

refreshBundles

public void refreshBundles(java.util.Collection<Bundle> bundles,
                           FrameworkListener... listeners)

Description copied from interface: FrameworkWiring

Refreshes the specified bundles. This forces the update (replacement) or removal of packages exported by the specified bundles.

The technique by which the framework refreshes bundles may vary among different framework implementations. A permissible implementation is to stop and restart the framework.

This method returns to the caller immediately and then performs the following steps on a separate thread:

1. Compute the dependency closure of the specified bundles. If no bundles are specified, compute the dependency closure of the removal pending bundles.
2. Each bundle in the dependency closure that is in the ACTIVE state will be stopped as described in the Bundle.stop method.
3. Each bundle in the dependency closure that is in the RESOLVED state is unresolved and thus moved to the INSTALLED state. The effect of this step is that bundles in the dependency closure are no longer RESOLVED.
4. Each bundle in the dependency closure that is in the UNINSTALLED state is removed from the dependency closure and is now completely removed from the Framework.
5. Each bundle in the dependency closure that was in the ACTIVE state prior to Step 2 is started as described in the 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 bundles satisfying the dependencies have been installed in the Framework.

For any exceptions that are thrown during any of these steps, a framework event of type FrameworkEvent.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. All framework events fired by this method are also delivered to the specified FrameworkListeners in the order they are specified.

When this process completes after the bundles are refreshed, the Framework will fire a Framework event of type FrameworkEvent.PACKAGES_REFRESHED to announce it has completed the bundle refresh. The specified FrameworkListeners are notified in the order specified. Each specified FrameworkListener will be called with a Framework event of type FrameworkEvent.PACKAGES_REFRESHED.

Specified by:

refreshBundles in interface FrameworkWiring

Parameters:

bundles - The bundles to be refreshed, or null to refresh the removal pending bundles.

listeners - Zero or more listeners to be notified when the bundle refresh has been completed. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is already registered with the framework, it will be notified twice.

resolveBundles

public boolean resolveBundles(java.util.Collection<Bundle> bundles)

Description copied from interface: FrameworkWiring

Resolves 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.

If no bundles are 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.

Specified by:

resolveBundles in interface FrameworkWiring

Parameters:

bundles - The bundles to resolve or null to resolve all unresolved bundles installed in the Framework.

Returns:

true if all specified bundles are resolved; false otherwise.

getRemovalPendingBundles

public java.util.Collection<Bundle> getRemovalPendingBundles()

Description copied from interface: FrameworkWiring

Returns the bundles that have non-current, in use bundle wirings. This is typically the bundles which have been updated or uninstalled since the last call to FrameworkWiring.refreshBundles(Collection, FrameworkListener...).

Specified by:

getRemovalPendingBundles in interface FrameworkWiring

Returns:

A collection containing a snapshot of the Bundles which have non-current, in use BundleWirings, or an empty collection if there are no such bundles.

getDependencyClosure

public java.util.Collection<Bundle> getDependencyClosure(java.util.Collection<Bundle> bundles)

Description copied from interface: FrameworkWiring

Returns the dependency closure for the specified bundles.

A graph of bundles is computed starting with the specified bundles. The graph is expanded by adding any bundle that is either wired to a package that is currently exported by a bundle in the graph or requires 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 UNINSTALLED bundles that are removal pending.

Specified by:

getDependencyClosure in interface FrameworkWiring

Parameters:

bundles - The initial bundles for which to generate the dependency closure.

Returns:

A collection containing a snapshot of the dependency closure of the specified bundles, or an empty collection if there were no specified bundles.