Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.osgi.service.packageadmin
Interface PackageAdmin

public interface PackageAdmin

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.

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

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` object 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
`static int` | `BUNDLE_TYPE_FRAGMENT` The bundle is a fragment bundle.

Method Summary
`Bundle[]` | `getBundles(java.lang.String symbolicName, java.lang.String versionRange)` Returns the bundles with the specified symbolic name within the specified version range.
`int` | `getBundleType(Bundle bundle)` Returns the special type of the specified bundle.
`ExportedPackage` | `getExportedPackage(java.lang.String name)` Gets the `ExportedPackage` object with the specified package name.
`ExportedPackage[]` | `getExportedPackages(Bundle bundle)` Gets the packages exported by the specified bundle.
`Bundle[]` | `getFragments(Bundle bundle)` Returns an array of attached fragment bundles for the specified bundle.
`Bundle[]` | `getHosts(Bundle bundle)` Returns an array of host bundles to which the specified fragment bundle is attached or `null` if the specified bundle is not attached to a host or is not a fragment bundle.
`ProvidingBundle[]` | `getProvidingBundles(java.lang.String symbolicName)` Returns an array of ProvidingBundles for each resolved bundle with the specified symbolic name.
`void` | `refreshPackages(Bundle[] bundles)` Forces the update (replacement) or removal of packages exported by the specified bundles.
`boolean` | `resolveBundles(Bundle[] bundles)` Resolve the specified bundles.

Field Detail

### BUNDLE_TYPE_FRAGMENT

    public static final int BUNDLE_TYPE_FRAGMENT

  The bundle is a fragment bundle.

  The value of `BUNDLE_TYPE_FRAGMENT` is 0x00000001.

  Since:
    1.2 EXPERIMENTAL

Method Detail

### getExportedPackages

    public ExportedPackage[] getExportedPackages(Bundle bundle)

  Gets the packages exported by the specified bundle.
  Parameters:
    `bundle` - The bundle whose exported packages are to be returned, or `null` 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.
  Returns:
    The array of packages exported by the specified bundle, or `null` if the specified bundle has not exported any packages.

### getExportedPackage

    public ExportedPackage getExportedPackage(java.lang.String name)

  Gets the `ExportedPackage` object with the specified package name. All exported packages will be checked for the specified name. 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 `ExportedPackage` object that was not present in the list returned by a prior call to `getExportedPackages()`.
  Parameters:
    `name` - The name of the exported package to be returned.
  Returns:
    The exported package with the specified name, or `null` if no expored package with that name exists.

### refreshPackages

    public void refreshPackages(Bundle[] bundles)

  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 in its own thread:

  1. 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 `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 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 broadcast.

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

  Parameters:
    `bundles` - the bundles whose exported packages are to be updated or removed, or `null` for all previously updated or uninstalled bundles.
  Throws:
    `java.lang.SecurityException` - if the caller does not have the `AdminPermission` and the Java runtime environment supports permissions.

### resolveBundles

    public boolean resolveBundles(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.

  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.

  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;
  Since:
    1.2 EXPERIMENTAL

### getProvidingBundles

    public ProvidingBundle[] getProvidingBundles(java.lang.String symbolicName)

  Returns an array of ProvidingBundles for each resolved bundle with the specified symbolic name. If the symbolic name argument is `null` then all resolved bundles with symbolic names are returned.
  Parameters:
    `symbolicName` - The symbolic name of the desired bundles or `null` for all bundles with symbolic names.
  Returns:
    An array of ProvidingBundles with the specified symbolic name or `null` if no resolved bundles exist with that symbolic name.
  Since:
    1.2 EXPERIMENTAL

### getBundles

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

  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 `null` 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.
  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.
  Since:
    1.2 EXPERIMENTAL
  See Also:
    `Constants.BUNDLE_VERSION_ATTRIBUTE`

### getFragments

    public Bundle[] getFragments(Bundle bundle)

  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.
  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.
  Since:
    1.2 EXPERIMENTAL

### getHosts

    public Bundle[] getHosts(Bundle bundle)

  Returns an array of host bundles to which the specified fragment bundle is attached or `null` if the specified bundle is not attached to a host or is not a fragment bundle.
  Parameters:
    `bundle` - The bundle whose host bundles are to be returned.
  Returns:
    An array of host bundles or `null` if the bundle does not have any host bundles.
  Since:
    1.2 EXPERIMENTAL

### getBundleType

    public int getBundleType(Bundle bundle)

  Returns the special type of the specified bundle. The bundle type values are:
  - `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.

  Returns:
    The special type of the bundle.
  Since:
    1.2 EXPERIMENTAL

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.