org.osgi.framework
Interface Bundle

public interface Bundle

An installed bundle in the Framework.

A Bundle object is the access point to define the life cycle of an installed bundle. Each bundle installed in the OSGi environment will have an associated Bundle object.

A bundle will have a unique identity, a long, chosen by the Framework. This identity will not change during the life cycle of a bundle, even when the bundle is updated. Uninstalling and then reinstalling the bundle will create a new unique identity.

A bundle can be in one of six states:

• UNINSTALLED
• INSTALLED
• RESOLVED
• STARTING
• STOPPING
• ACTIVE

Values assigned to these states have no specified ordering; they represent bit values that may be ORed together to determine if a bundle is in one of the valid states.

A bundle should only execute code when its state is one of STARTING, ACTIVE, or STOPPING. An UNINSTALLED bundle can not be set to another state; it is a zombie and can only be reached because invalid references are kept somewhere.

The Framework is the only entity that is allowed to create Bundle objects, and these objects are only valid within the Framework that created them.

Version:

$Revision: 1.1 $

Author:

Open Services Gateway Initiative

Field Summary

static int	ACTIVE This bundle is now running.
static int	INSTALLED This bundle is installed but not yet resolved.
static int	RESOLVED This bundle is resolved and is able to be started.
static int	STARTING This bundle is in the process of starting.
static int	STOPPING This bundle is in the process of stopping.
static int	UNINSTALLED This bundle is uninstalled and may not be used.

Method Summary

long	getBundleId() Returns this bundle's identifier.
java.util.Dictionary	getHeaders() Returns this bundle's Manifest headers and values.
java.lang.String	getLocation() Returns this bundle's location identifier.
ServiceReference[]	getRegisteredServices() Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.
java.net.URL	getResource(java.lang.String name) Find the specified resource in this bundle.
ServiceReference[]	getServicesInUse() Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services.
int	getState() Returns this bundle's current state.
boolean	hasPermission(java.lang.Object permission) Determines if this bundle has the specified permissions.
void	start() Starts this bundle.
void	stop() Stops this bundle.
void	uninstall() Uninstalls this bundle.
void	update() Updates this bundle.
void	update(java.io.InputStream in) Updates this bundle from an InputStream.

Field Detail

UNINSTALLED

static final int UNINSTALLED

This bundle is uninstalled and may not be used.

The UNINSTALLED state is only visible after a bundle is uninstalled; the bundle is in an unusable state and all references to the Bundle object should be released immediately.

The value of UNINSTALLED is 0x00000001.

See Also:

Constant Field Values

INSTALLED

static final int INSTALLED

This bundle is installed but not yet resolved.

A bundle is in the INSTALLED state when it has been installed in the Framework but cannot run.

This state is visible if the bundle's code dependencies are not resolved. The Framework may attempt to resolve an INSTALLED bundle's code dependencies and move the bundle to the RESOLVED state.

The value of INSTALLED is 0x00000002.

See Also:

Constant Field Values

RESOLVED

static final int RESOLVED

This bundle is resolved and is able to be started.

A bundle is in the RESOLVED state when the Framework has successfully resolved the bundle's dependencies. These dependencies include:

• The bundle's class path from its Constants.BUNDLE_CLASSPATH Manifest header.
• The bundle's package dependencies from its Constants.EXPORT_PACKAGEand Constants.IMPORT_PACKAGE Manifest headers.

Note that the bundle is not active yet. A bundle must be put in the RESOLVED state before it can be started. The Framework may attempt to resolve a bundle at any time.

The value of RESOLVED is 0x00000004.

See Also:

Constant Field Values

STARTING

static final int STARTING

This bundle is in the process of starting.

A bundle is in the STARTING state when the start()method is active. A bundle will be in this state when the bundle's BundleActivator.start(org.osgi.framework.BundleContext)is called. If this method completes without exception, then the bundle has successfully started and will move to the ACTIVE state.

The value of STARTING is 0x00000008.

See Also:

Constant Field Values

STOPPING

static final int STOPPING

This bundle is in the process of stopping.

A bundle is in the STOPPING state when the stop()method is active. A bundle will be in this state when the bundle's BundleActivator.stop(org.osgi.framework.BundleContext)method is called. When this method completes the bundle is stopped and will move to the RESOLVED state.

The value of STOPPING is 0x00000010.

See Also:

Constant Field Values

ACTIVE

static final int ACTIVE

This bundle is now running.

A bundle is in the ACTIVE state when it has been successfully started.

The value of ACTIVE is 0x00000020.

See Also:

Constant Field Values

Method Detail

getState

int getState()

Returns this bundle's current state.

A bundle can be in only one state at any time.

Returns:

An element of UNINSTALLED, INSTALLED, RESOLVED, STARTING, STOPPING, ACTIVE.

start

void start()
           throws BundleException

Starts this bundle. If the Framework implements the optional Start Level service and the current start level is less than this bundle's start level, then the Framework must persistently mark this bundle as started and delay the starting of this bundle until the Framework's current start level becomes equal or more than the bundle's start level.

Otherwise, the following steps are required to start a bundle:

1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.
2. If this bundle's state is STARTING or STOPPING then this method will wait for this bundle to change state before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be started.
3. If this bundle's state is ACTIVE then this method returns immediately.
4. If this bundle's state is not RESOLVED, an attempt is made to resolve this bundle's package dependencies. If the Framework cannot resolve this bundle, a BundleException is thrown.
5. This bundle's state is set to STARTING.
6. The BundleActivator.start(org.osgi.framework.BundleContext)method of this bundle's BundleActivator, if one is specified, is called. If the BundleActivator is invalid or throws an exception, this bundle's state is set back to RESOLVED.
   Any services registered by the bundle will be unregistered.
   Any services used by the bundle will be released.
   Any listeners registered by the bundle will be removed.
   A BundleException is then thrown.
7. If this bundle's state is UNINSTALLED, because the bundle was uninstalled while the BundleActivator.start method was running, a BundleException is thrown.
8. Since it is recorded that this bundle has been started, when the Framework is restarted this bundle will be automatically started.
9. This bundle's state is set to ACTIVE.
10. A bundle event of type BundleEvent.STARTEDis broadcast.

Preconditions

• getState() in {INSTALLED}, {RESOLVED}.

Postconditions, no exceptions thrown

• getState() in {ACTIVE}.
• BundleActivator.start() has been called and did not throw an exception.

Postconditions, when an exception is thrown

• getState() not in {STARTING}, {ACTIVE}.

Throws:

BundleException - If this bundle couldn't be started. This could be because a code dependency could not be resolved or the specified BundleActivator could not be loaded or threw an exception.

java.lang.IllegalStateException - If this bundle has been uninstalled or this bundle tries to change its own state.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermisson, and the Java Runtime Environment supports permissions.

stop

void stop()
          throws BundleException

Stops this bundle.

The following steps are required to stop a bundle:

1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.
2. If this bundle's state is STARTING or STOPPING then this method will wait for this bundle to change state before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be stopped.
3. If this bundle's state is not ACTIVE then this method returns immediately.
4. This bundle's state is set to STOPPING.
5. Since it is recorded that this bundle has been stopped, Framework is restarted this bundle will not be automatically started.
6. The BundleActivator.stop(org.osgi.framework.BundleContext)method of this bundle's BundleActivator, if one is specified, is called. If this method throws an exception, it will continue to stop this bundle. A BundleException will be thrown after completion of the remaining steps.
7. Any services registered by this bundle must be unregistered.
8. Any services used by this bundle must be released.
9. Any listeners registered by this bundle must be removed.
10. If this bundle's state is UNINSTALLED, because the bundle was uninstalled while the BundleActivator.stop method was running, a BundleException must be thrown.
11. This bundle's state is set to RESOLVED.
12. A bundle event of type BundleEvent.STOPPEDis broadcast.

Preconditions

• getState() in {ACTIVE}.

Postconditions, no exceptions thrown

• getState() not in {ACTIVE, STOPPING}.
• BundleActivator.stop has been called and did not throw an exception.

Postconditions, when an exception is thrown

• None.

Throws:

BundleException - If this bundle's BundleActivator could not be loaded or threw an exception.

java.lang.IllegalStateException - If this bundle has been uninstalled or this bundle tries to change its own state.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

update

void update()
            throws BundleException

Updates this bundle.

If this bundle's state is ACTIVE, it will be stopped before the update and started after the update successfully completes.

If the bundle being updated has exported any packages, these packages will not be updated. Instead, the previous package version will remain exported until the PackageAdmin.refreshPackages method has been has been called or the Framework is relaunched.

The following steps are required to update a bundle:

1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.
2. If this bundle's state is ACTIVE, STARTING or STOPPING, the bundle is stopped as described in the Bundle.stop method. If Bundle.stop throws an exception, the exception is rethrown terminating the update.
3. The download location of the new version of this bundle is determined from either the bundle's Constants.BUNDLE_UPDATELOCATION Manifest header (if available) or the bundle's original location.
4. The location is interpreted in an implementation dependent manner, typically as a URL, and the new version of this bundle is obtained from this location.
5. The new version of this bundle is installed. If the Framework is unable to install the new version of this bundle, the original version of this bundle will be restored and a BundleException will be thrown after completion of the remaining steps.
6. If the bundle has declared an Bundle-RequiredExecutionEnvironment header, then the listed execution environments must be verified against the installed execution environments. If they do not all match, the original version of this bundle will be restored and a BundleException will be thrown after completion of the remaining steps.
7. This bundle's state is set to INSTALLED.
8. If this bundle has not declared an Import-Package header in its Manifest file (specifically, this bundle does not depend on any packages from other bundles), this bundle's state may be set to RESOLVED.
9. If the new version of this bundle was successfully installed, a bundle event of type BundleEvent.UPDATEDis broadcast.
10. If this bundle's state was originally ACTIVE, the updated bundle is started as described in the Bundle.start method. If Bundle.start throws an exception, a Framework event of type FrameworkEvent.ERRORis broadcast containing the exception.

Preconditions

• getState() not in {UNINSTALLED}.

Postconditions, no exceptions thrown

• getState() in {INSTALLED, RESOLVED, ACTIVE}.
• This bundle has been updated.

Postconditions, when an exception is thrown

• getState() in {INSTALLED, RESOLVED, ACTIVE}.
• Original bundle is still used; no update occurred.

Throws:

BundleException - If the update fails.

java.lang.IllegalStateException - If this bundle has been uninstalled or this bundle tries to change its own state.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

See Also:

stop(), start()

update

void update(java.io.InputStream in)
            throws BundleException

Updates this bundle from an InputStream.

This method performs all the steps listed in Bundle.update(), except the bundle will be read from the supplied InputStream, rather than a URL.

This method will always close the InputStream when it is done, even if an exception is thrown.

Parameters:

in - The InputStream from which to read the new bundle.

Throws:

BundleException - If the provided stream cannot be read or the update fails.

java.lang.IllegalStateException - If this bundle has been uninstalled or this bundle tries to change its own state.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

See Also:

update()

uninstall

void uninstall()
               throws BundleException

Uninstalls this bundle.

This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then puts this bundle into the UNINSTALLED state. The Framework will remove any resources related to this bundle that it is able to remove.

If this bundle has exported any packages, the Framework will continue to make these packages available to their importing bundles until the PackageAdmin.refreshPackages method has been called or the Framework is relaunched.

The following steps are required to uninstall a bundle:

1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.
2. If this bundle's state is ACTIVE, STARTING or STOPPING, this bundle is stopped as described in the Bundle.stop method. If Bundle.stop throws an exception, a Framework event of type FrameworkEvent.ERRORis broadcast containing the exception.
3. This bundle's state is set to UNINSTALLED.
4. A bundle event of type BundleEvent.UNINSTALLEDis broadcast.
5. This bundle and any persistent storage area provided for this bundle by the Framework are removed.

Preconditions

• getState() not in {UNINSTALLED}.

Postconditions, no exceptions thrown

• getState() in {UNINSTALLED}.
• This bundle has been uninstalled.

Postconditions, when an exception is thrown

• getState() not in {UNINSTALLED}.
• This Bundle has not been uninstalled.

Throws:

BundleException - If the uninstall failed. This can occur if another thread is attempting to change the bundle's state and does not complete in a timely manner.

java.lang.IllegalStateException - If this bundle has been uninstalled or this bundle tries to change its own state.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

See Also:

stop()

getHeaders

java.util.Dictionary getHeaders()

Returns this bundle's Manifest headers and values. This method returns all the Manifest headers and values from the main section of the bundle's Manifest file; that is, all lines prior to the first blank line.

Manifest header names are case-insensitive. The methods of the returned Dictionary object will operate on header names in a case-insensitive manner.

For example, the following Manifest headers and values are included if they are present in the Manifest file:

 Bundle-Name
 Bundle-Vendor
 Bundle-Version
 Bundle-Description
 Bundle-DocURL
 Bundle-ContactAddress
 

This method will continue to return Manifest header information while this bundle is in the UNINSTALLED state.

Returns:

A Dictionary object containing this bundle's Manifest headers and values.

Throws:

java.lang.SecurityException - If the caller does not have the AdminPermission, and the Java Runtime Environment supports permissions.

getBundleId

long getBundleId()

Returns this bundle's identifier. The bundle is assigned a unique identifier by the Framework when it is installed in the OSGi environment.

A bundle's unique identifier has the following attributes:

• Is unique and persistent.
• Is a long.
• Its value is not reused for another bundle, even after the bundle is uninstalled.
• Does not change while the bundle remains installed.
• Does not change when the bundle is updated.

This method will continue to return this bundle's unique identifier while this bundle is in the UNINSTALLED state.

Returns:

The unique identifier of this bundle.

getLocation

java.lang.String getLocation()

Returns this bundle's location identifier.

The bundle location identifier is the location passed to BundleContext.installBundle(java.lang.String)when a bundle is installed.

This method will continue to return this bundle's location identifier while this bundle is in the UNINSTALLED state.

Returns:

The string representation of this bundle's location identifier.

Throws:

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

getRegisteredServices

ServiceReference[] getRegisteredServices()

Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.

If the Java runtime supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

Returns:

An array of ServiceReference objects or null.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

See Also:

ServiceRegistration, ServiceReference, ServicePermission

getServicesInUse

ServiceReference[] getServicesInUse()

Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services. A bundle is considered to be using a service if its use count for that service is greater than zero.

If the Java Runtime Environment supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

Returns:

An array of ServiceReference objects or null.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

See Also:

ServiceReference, ServicePermission

hasPermission

boolean hasPermission(java.lang.Object permission)

Determines if this bundle has the specified permissions.

If the Java Runtime Environment does not support permissions, this method always returns true.

permission is of type Object to avoid referencing the java.security.Permission class directly. This is to allow the Framework to be implemented in Java environments which do not support permissions.

If the Java Runtime Environment does support permissions, this bundle and all its resources including nested JAR files, belong to the same java.security.ProtectionDomain; that is, they will share the same set of permissions.

Parameters:

permission - The permission to verify.

Returns:

true if this bundle has the specified permission or the permissions possessed by this bundle imply the specified permission; false if this bundle does not have the specified permission or permission is not an instanceof java.security.Permission.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

getResource

java.net.URL getResource(java.lang.String name)

Find the specified resource in this bundle. This bundle's class loader is called to search for the named resource. If this bundle's state is INSTALLED, then only this bundle will be searched for the specified resource. Imported packages cannot be searched when a bundle has not been resolved.

Parameters:

name - The name of the resource. See java.lang.ClassLoader.getResource for a description of the format of a resource name.

Returns:

a URL to the named resource, or null if the resource could not be found or if the caller does not have the AdminPermission, and the Java Runtime Environment supports permissions.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

Since:

1.1