Bundle

Syntax

public interface Bundle

Description

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

A bundle will have a unique identity, a long, choosen 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 will create a new identity.

The Bundle has six states: UNINSTALLED, INSTALLED, RESOLVED, STARTING, STOPPING, and ACTIVE. The values assigned to these states have no specified ordering. They represent bit values that may be ORed together for the purposes of determining if a bundle is in one of a set of states.

A bundle should only be executing code when its state is in {STARTING, ACTIVE, STOPPING }. An UNINSTALLED bundle can never go back to another state. It is a zombie and can only be reached because invalid references are kept somewhere. The framework is the only one that can create Bundle objects and these objects are only valid within the framework that created them.

Fields

ACTIVE

public static final int ACTIVE
						

Active state, the bundle is now running. The bundle is in the ACTIVE state when it has been successfully started.

The value of ACTIVE is 0x00000020.

INSTALLED

public static final int INSTALLED
						

Installed state, the bundle is installed but not yet resolved. The 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.

RESOLVED

public static final int RESOLVED
						

Resolved state, the bundle is resolved and is able to be started. The bundle is in the RESOLVED state when the framework has successfully resolved the bundle's code dependencies. These dependencies include:

• The bundle's class path from its Bundle-ClassPath manifest header.

• The bundle's native code from its Bundle-NativeCode manifest header.

• The bundle's package dependencies from its Export-Package and Import-Package manifest headers.

However, the bundle is not active yet. A bundle must be 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.

STARTING

public static final int STARTING
						

Starting state, the bundle is in the process of starting. The bundle is in the STARTING state when the start() method is active. The bundle will be in this state when the bundle's BundleActivator.start(BundleContext) is called. If the BundleActivator.start(BundleContext) method completes without exception, the bundle has successfully started and will move to the ACTIVE state.

The value of STARTING is 0x00000008.

STOPPING

public static final int STOPPING
						

Stopping state, the bundle is in the process of stopping. The bundle is in the STOPPING state when the stop() method is active. The bundle will be in this state when the bundle's BundleActivator.stop(BundleContext) is called. When the BundleActivator.stop(BundleContext) method completes the bundle is stopped and will move to the RESOLVED state.

The value of STOPPING is 0x00000010.

UNINSTALLED

public static final int UNINSTALLED
						

Uninstalled state, the bundle is uninstalled and may not be used. The UNINSTALLED state is only be 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.

Methods

getBundleId()

public long getBundleId()

Retrieve the bundle's unique identifier, which the framework assigned to this bundle when it was installed.

The unique identifier has the following attributes:

• It is unique and persistent.

• The identifier is a long.

• Once its value is assigned to a bundle, that value is not reused for another bundle, even after the bundle is uninstalled.

• Its value does not change as long as the bundle remains installed.

• Its value does not change when the bundle is updated

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

Returns: This bundle's unique identifier.

getHeaders()

public java.util.Dictionary getHeaders()
            throws java.lang.SecurityException

Return the bundle's manifest headers and values from the manifest's preliminary section. That is all the manifest's headers and values 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:

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

This method will continue to return this information when the bundle is in the UNINSTALLED state.

Returns: A Dictionary object containing the bundle's manifest headers and values.

Throws:

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

getLocation()

public java.lang.String getLocation()
            throws java.lang.SecurityException

Retrieve the location identifier of the bundle. This is typically the location passed to BundleContext.installBundle(String) when the bundle was installed. The location identifier of the bundle may change during bundle update. Calling this method while framework is updating the bundle results in undefined behavior.

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

Returns: A string that is the location identifier of the bundle.

Throws:

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

getRegisteredServices()

public ServiceReference[] getRegisteredServices()
            throws java.lang.IllegalStateException

Provides a list of ServiceReference s for the services registered by this bundle or null if the bundle has no registered services.

If the Java runtime supports permissions, a ServiceReference to a service is included in the returned list if and 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, but the framework is a very dynamic environment and services can be modified or unregistered at anytime.

Returns: An array of ServiceReference or null.

Throws:

javalang.IllegalStateException— If the bundle has been uninstalled.

See Also: ServiceRegistration, ServiceReference

getServicesInUse()

public ServiceReference[] getServicesInUse()
            throws java.lang.IllegalStateException

Provides a list of ServiceReference s for the services this bundle is using, or null if the bundle is not using any services. A bundle is considered to be using a service if the bundle's use count for the service is greater than zero.

If the Java runtime supports permissions, a ServiceReference to a service is included in the returned list if and 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, but the framework is a very dynamic environment and services can be modified or unregistered at anytime.

Returns: An array of ServiceReference or null.

Throws:

javalang.IllegalStateException— If the bundle has been uninstalled.

See Also: ServiceReference

getState()

public int getState()

Returns the current state of the bundle. A bundle can only be in one state at any time.

Returns: element of {UNINSTALLED, INSTALLED, RESOLVED, STARTING, STOPPING, ACTIVE }

hasPermission(Object)

public boolean hasPermission(java.lang.Object permission)
            throws java.lang.IllegalStateException

Determine whether the bundle has the requested permission.

If the Java runtime environment does not support permissions this method always returns true. The permission parameter 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.

Parameters:

permission— The requested permission.

Returns: true if the bundle has the requested permission or the permissions possessed by the bundle imply the requested permission; false if the bundle does not have the permission or the permission parameter is not an instanceof java.security.Permission.

Throws:

javalang.IllegalStateException— If the bundle has been uninstalled.

start()

public void start()
            throws BundleException, java.lang.IllegalState-Exception,
            java.lang.SecurityException

Start this bundle.

The following steps are followed to start a bundle:

 

1.	If the bundle is UNINSTALLED then an IllegalStateException is thrown.
2.	If the bundle is STARTING or STOPPING then this method will wait for the bundle to change state before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate the bundle was unable to be started.
3.	If the bundle is ACTIVE then this method returns immediately.
4.	If the bundle is not RESOLVED, an attempt is made to resolve the bundle. If the bundle cannot be resolved, a BundleException is thrown.
5.	The state of the bundle is set to STARTING.
6.	The start(BundleContext) method of the bundle's BundleActivator, if one is specified, is called. If the BundleActivator is invalid or throws an exception, the state of the bundle is set back to RESOLVED, the bundle's listeners, if any, are removed, service's registered by the bundle, if any, are unregistered, and service's used by the bundle, if any, are released. A BundleException is then thrown.
7.	It is recorded that this bundle has been started, so that when the framework is restarted, this bundle will be automatically started.
8.	The state of the bundle is set to ACTIVE.
9.	A BundleEvent of type BundleEvent.STARTED is broadcast.

Preconditions

• getState() in {INSTALLED,RESOLVED }.

Postconditions, no exceptions thrown

• getState() in {ACTIVE }.

• BundleActivator.start(BundleContext) has been called and did not throw an exception.

Postconditions, when an exception is thrown

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

Throws:

BundleException— If the 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.

javalang.IllegalStateException— If the bundle has been uninstalled or the bundle tries to change its own state.

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

stop()

public void stop()
            throws BundleException, java.lang.IllegalState-Exception,
            java.lang.SecurityException

Stop this bundle. Any services registered by this bundle will be unregistered. Any services used by this bundle will be released. Any listeners registered by this bundle will be removed.

The following steps are followed to stop a bundle:

 

1.	If the bundle is UNINSTALLED then an IllegalStateException is thrown.
2.	If the bundle is STARTING or STOPPING then this method will wait for the bundle to change state before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate the bundle was unable to be stopped.
3.	If the bundle is not ACTIVE then this method returns immediately.
4.	The state of the bundle is set to STOPPING.
5.	It is recorded that this bundle has been stopped, so that when the framework is restarted, this bundle will not be automatically started.
6.	The stop(BundleContext) method of the bundle's BundleActivator, if one is specified, is called. If the BundleActivator throws an exception, this method will continue to stop the bundle. A BundleException will be thrown after completion of the remaining steps.
7.	The bundle's listeners, if any, are removed, service's registered by the bundle, if any, are unregistered, and service's used by the bundle, if any, are released.
8.	The state of the bundle is set to RESOLVED.
9.	A BundleEvent of type BundleEvent.STOPPED is broadcast.

Preconditions

• getState() in {ACTIVE }.

Postconditions, no exceptions thrown

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

• BundleActivator.stop(BundleContext) has been called and did not throw an exception.

Postconditions, when an exception is thrown

• None.

Throws:

BundleException— If the bundle's BundleActivator could not be loaded or threw an exception.

javalang.IllegalStateException— If the bundle has been uninstalled or the bundle tries to change its own state.

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

uninstall()

public void uninstall()
            throws BundleException, java.lang.IllegalState-Exception,
            java.lang.SecurityException

Uninstall this bundle.

This causes the framework to notify other bundles that this bundle is being uninstalled, and then to put this bundle into the UNINSTALLED state. The framework will remove any resources related to this bundle that it can.

If this bundle has been exporting any packages, the framework may either:

• continue to make all packages exported by this bundle available to the importing bundles until the framework is relaunched (at which time, the importing bundles will be bound to another bundle exporting a compatible package, or they will not be started); or

• remove all packages exported by this bundle, possibly stopping all importing bundles and putting them into the INSTALLED state until another bundle offering a compatible package for export has been selected by the framework.

The following steps are followed to uninstall a bundle:

 

1.	If the bundle is UNINSTALLED then an IllegalStateException is thrown.
2.	If the bundle is ACTIVE or STARTING, the bundle is stopped as described in the stop() method. If stop() throws an exception, a FrameworkEvent of type FrameworkEvent.ERROR is broadcast containing the exception.
3.	A BundleEvent of type BundleEvent.UNINSTALLED is broadcast.
4.	The state of the bundle is set to UNINSTALLED.
5.	The bundle and the persistent storage area provided for the bundle by the framework, if any, is removed.

Preconditions

• getState() not in {UNINSTALLED }.

Postconditions, no exceptions thrown

• getState() in {UNINSTALLED }.

• The bundle has been uninstalled.

Postconditions, when an exception is thrown

• getState() not in {UNINSTALLED }.

• The bundle has not been uninstalled.

Throws:

BundleException— If the uninstall failed.

javalang.IllegalStateException— If the bundle has been uninstalled or the bundle tries to change its own state.

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

See Also: stop()

update()

public void update()
            throws BundleException, java.lang.IllegalState-Exception,
            java.lang.SecurityException

Update this bundle. If the bundle is ACTIVE, the bundle will be stopped before the update and started after the update successfully completes.

If the bundle that is being updated has exported any packages, it is the framework's responsibility to ensure that all bundles that are importing those packages (including the bundle that is exporting them) share the same version of the exported class files. In one implementation of the framework, updating a package may not have any effect on the importing bundles until the framework is restarted. Another framework implementation may choose to resolve all importing bundles against the updated class files, by possibly stopping and restarting them.

The following steps are followed to update a bundle:

 

1.	If the bundle is UNINSTALLED then an IllegalStateException is thrown.
2.	If the bundle is ACTIVE or STARTING, the bundle is stopped as described in the stop() method. If stop() throws an exception, the exception is rethrown terminating the update.
3.	The location for the new version of the bundle is determined from either the manifest header Bundle-UpdateLocation if available or the original location.
4.	The location is interpreted in an implementation dependent way (typically as a URL) and the new version of the bundle is obtained from the location.
5.	The new version of the bundle is installed. If the framework is unable to install the new version of the bundle, the original version of the bundle will be restored and a BundleException will be thrown after completion of the remaining steps.
6.	The state of the bundle is set to INSTALLED.
7.	If the new version of the bundle was successfully installed, a BundleEvent of type BundleEvent.UPDATED is broadcast.
8.	If the bundle was originally ACTIVE, the updated bundle is started as described in the start() method. If start() throws an exception, a FrameworkEvent of type FrameworkEvent.ERROR is broadcast containing the exception.

Preconditions

• getState() not in {UNINSTALLED }.

Postconditions, no exceptions thrown

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

• The bundle has been updated.

Postconditions, when an exception is thrown

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

• Original bundle is still used, no update took place.

Throws:

BundleException— If the update fails.

javalang.IllegalStateException— If the bundle has been uninstalled or the bundle tries to change its own state.

javalang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

See Also: stop(), start()

update(InputStream)

public void update(java.io.InputStream in)

Update this bundle from an InputStream.

This method performs all the steps listed in update(), except the bundle will be read in through 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

See Also: update()