org.osgi.framework.launch
Interface Framework

All Superinterfaces:

Bundle

All Known Implementing Classes:

Felix

public interface Framework
extends Bundle

The System Bundle for a Framework instance. The main class of a framework implementation must implement this interface. The instantiator of the framework implementation class then has a System Bundle object and can then use the methods of this interface to manage and control the created framework instance.

The main class of a framework implementation must provide a public constructor that takes a single argument of type Map. This configuration argument provides this System Bundle with framework properties to configure the framework instance. The framework instance must also examine the system properties for framework properties which are not set in the configuration argument. A framework property in the configuration argument with a null value indicates the framework property is unset and the system properties must not be examined for a value of the framework property. This allows the configuration argument to unset framework properties in the system properties .

If framework properties are not provided by the configuration argument or the system properties, this System Bundle must use some reasonable default configuration appropriate for the current VM. For example, the system packages for the current execution environment should be properly exported. The configuration argument may be null. The framework instance must copy any information needed from the configuration argument since the configuration argument can be changed after the framework instance has been created.

A newly constructed System Bundle must be in the Bundle.INSTALLED state.

Version:

$Revision: 5686 $

Field Summary

Fields inherited from interface org.osgi.framework.Bundle

ACTIVE, INSTALLED, RESOLVED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED

Method Summary

long	getBundleId() Returns the System Bundle unique identifier.
String	getLocation() Returns the System Bundle location identifier.
String	getSymbolicName() Returns the symbolic name of this System Bundle.
void	init() Initialize this System Bundle.
void	start() Start this System Bundle.
void	start(int options) Start this System Bundle.
void	stop() Stop this System Bundle.
void	stop(int options) Stop this System Bundle.
void	uninstall() The System Bundle cannot be uninstalled.
void	update() Stop and restart this System Bundle.
void	update(InputStream in) Stop and restart this System Bundle.
FrameworkEvent	waitForStop(long timeout) Wait until this System Bundle has completely stopped.

Methods inherited from interface org.osgi.framework.Bundle

findEntries, getBundleContext, getEntry, getEntryPaths, getHeaders, getHeaders, getLastModified, getRegisteredServices, getResource, getResources, getServicesInUse, getState, hasPermission, loadClass

Method Detail

init

void init()
          throws BundleException

Initialize this System Bundle. After calling this method, this System Bundle must:

• Be in the Bundle.STARTING state.
• Have a valid Bundle Context.
• Have its framework instance be at start level 0.
• Have event handling enabled in its framework instance.
• Have reified Bundle objects for all bundles installed in its framework instance.
• Register framework services. For example, PackageAdmin, ConditionalPermissionAdmin, StartLevel.

This System Bundle will not actually be started until start is called.

This method does nothing if called when this System Bundle is in the Bundle.STARTING, Bundle.ACTIVE or Bundle.STOPPING states.

Throws:

BundleException - If this System Bundle could not be initialized.

waitForStop

FrameworkEvent waitForStop(long timeout)
                           throws InterruptedException

Wait until this System Bundle has completely stopped. The stop and update methods on a System Bundle performs an asynchronous stop of the System Bundle. This method can be used to wait until the asynchronous stop of this System Bundle has completed. This method will only wait if called when this System Bundle is in the Bundle.STARTING, Bundle.ACTIVE, or Bundle.STOPPING states. Otherwise it will return immediately.

A Framework Event is returned to indicate why this System Bundle has stopped.

Parameters:

timeout - Maximum number of milliseconds to wait until this System Bundle has completely stopped. A value of zero will wait indefinitely.

Returns:

A Framework Event indicating the reason this method returned. The following FrameworkEvent types may be returned by this method.

• STOPPED - This System Bundle has been stopped which has shutdown its framework instance.
• STOPPED_UPDATE - This System Bundle has been updated which has shutdown and will restart its framework instance.
• STOPPED_BOOTCLASSPATH_MODIFIED - This System Bundle has been stopped which has shutdown its framework instance and a bootclasspath extension bundle has been installed or updated. The VM must be restarted in order for the changed boot class path to take affect.
• ERROR - The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.
• INFO - This method has timed out and returned before this System Bundle has stopped.

Throws:

InterruptedException - If another thread interrupted the current thread before or while the current thread was waiting for this System Bundle to completely stop. The interrupted status of the current thread is cleared when this exception is thrown.

IllegalArgumentException - If the value of timeout is negative.

start

void start()
           throws BundleException

Start this System Bundle.

The following steps are taken to start this System Bundle:

1. If this System Bundle is not in the Bundle.STARTING state, initialize this System Bundle.
2. All installed bundles must be started in accordance with each bundle's persistent autostart setting. This means some bundles will not be started, some will be started with eager activation and some will be started with their declared activation policy.
   • If this System Bundle implements the optional Start Level Service Specification, then the start level of this System Bundle's framework instance is moved to the start level specified by the beginning start level framework property, as described in the Start Level Service Specification. If this framework property is not specified, then the start level of this System Bundle's framework instance is moved to start level one (1).
   Any exceptions that occur during bundle starting must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR
3. This System Bundle's state is set to Bundle.ACTIVE.
4. A framework event of type FrameworkEvent.STARTED is fired

Specified by:

start in interface Bundle

Throws:

BundleException - If this System Bundle could not be started.

SecurityException - If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

See Also:

"Start Level Service Specification"

start

void start(int options)
           throws BundleException

Start this System Bundle.

Calling this method is the same as calling start(). There are no start options for the System Bundle.

Specified by:

start in interface Bundle

Parameters:

options - Ignored. There are no start options for the System Bundle.

Throws:

BundleException - If this System Bundle could not be started.

SecurityException - If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

See Also:

start()

stop

void stop()
          throws BundleException

Stop this System Bundle.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

1. This System Bundle's state is set to Bundle.STOPPING.
2. All installed bundles must be stopped without changing each bundle's persistent autostart setting.
   • If this System Bundle implements the optional Start Level Service Specification, then the start level of this System Bundle's framework instance is moved to start level zero (0), as described in the Start Level Service Specification.
   Any exceptions that occur during bundle stopping must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR
3. Unregister all services registered by this System Bundle.
4. Event handling is disabled in this System Bundle's framework instance.
5. This System Bundle's state is set to Bundle.RESOLVED.
6. All resources held by this System Bundle's framework instance are released. This includes threads, bundle class loaders, open files, etc.
7. Notify all threads that are waiting at waitForStop that the stop operation has completed.

After being stopped, this System Bundle may be discarded, initialized or started.

Specified by:

stop in interface Bundle

Throws:

BundleException - If stopping this System Bundle could not be initiated.

SecurityException - If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

See Also:

"Start Level Service Specification"

stop

void stop(int options)
          throws BundleException

Stop this System Bundle.

Calling this method is the same as calling stop(). There are no stop options for the System Bundle.

Specified by:

stop in interface Bundle

Parameters:

options - Ignored. There are no stop options for the System Bundle.

Throws:

BundleException - If stopping this System Bundle could not be initiated.

SecurityException - If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

See Also:

stop()

uninstall

void uninstall()
               throws BundleException

The System Bundle cannot be uninstalled.

This method always throws a BundleException.

Specified by:

uninstall in interface Bundle

Throws:

BundleException - This System Bundle cannot be uninstalled.

SecurityException - If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

update

void update()
            throws BundleException

Stop and restart this System Bundle.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

1. Perform the steps in the stop() method to stop this System Bundle.
2. Perform the steps in the start() method to start this System Bundle.

Specified by:

update in interface Bundle

Throws:

BundleException - If stopping and restarting this System Bundle could not be initiated.

SecurityException - If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

update

void update(InputStream in)
            throws BundleException

Stop and restart this System Bundle.

Calling this method is the same as calling update() except that any provided InputStream is immediately closed.

Specified by:

update in interface Bundle

Parameters:

in - Any provided InputStream is immediately closed before returning from this method and otherwise ignored.

Throws:

BundleException - If stopping and restarting this System Bundle could not be initiated.

SecurityException - If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

getBundleId

long getBundleId()

Returns the System Bundle unique identifier. This System Bundle is assigned the unique identifier zero (0).

Specified by:

getBundleId in interface Bundle

Returns:

0.

See Also:

Bundle.getBundleId()

getLocation

String getLocation()

Returns the System Bundle location identifier.

Specified by:

getLocation in interface Bundle

Returns:

The string "System Bundle".

Throws:

SecurityException - If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

See Also:

Bundle.getLocation(), Constants.SYSTEM_BUNDLE_LOCATION

getSymbolicName

String getSymbolicName()

Returns the symbolic name of this System Bundle. The symbolic name is unique for the implementation of the framework. However, the symbolic name "system.bundle" must be recognized as an alias to the implementation-defined symbolic name.

Specified by:

getSymbolicName in interface Bundle

Returns:

The symbolic name of this System Bundle.

See Also:

Bundle.getSymbolicName(), Constants.SYSTEM_BUNDLE_SYMBOLICNAME