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:

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


Copyright © 2006-2011 Apache Software Foundation. All Rights Reserved.