org.eclipse.osgi.framework.internal.core
Class InternalSystemBundle

java.lang.Object
  org.eclipse.osgi.framework.internal.core.AbstractBundle
      org.eclipse.osgi.framework.internal.core.BundleHost
          org.eclipse.osgi.framework.internal.core.InternalSystemBundle

All Implemented Interfaces:

java.lang.Comparable, KeyedElement, Bundle, Framework

public class InternalSystemBundle
extends BundleHost
implements Framework

This class subclasses Bundle to provide a system Bundle so that the framework can be represented as a bundle and can access the services provided by other bundles.

Field Summary

Fields inherited from class org.eclipse.osgi.framework.internal.core.BundleHost

context, fragments, LAZY_TRIGGER

Fields inherited from class org.eclipse.osgi.framework.internal.core.AbstractBundle

bundledata, domain, framework, manifestLocalization, state, statechangeLock, stateChanging

Fields inherited from interface org.osgi.framework.Bundle

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

Constructor Summary

protected

InternalSystemBundle(Framework framework) Private SystemBundle object constructor.

Method Summary

protected void	close() Close the the Bundle's file.
java.lang.ClassLoader	getClassLoader() Gets the class loader for the host bundle.
java.util.Dictionary	getHeaders(java.lang.String localeString) Returns this bundle's Manifest headers and values.
java.net.URL	getResource(java.lang.String name) Find the specified resource in this bundle.
boolean	hasPermission(java.lang.Object permission) Determine whether the bundle has the requested permission.
void	init() Initialize this Framework.
protected boolean	isUnresolved() Indicate SystemBundle is resolved.
protected void	load() Load the bundle.
protected java.lang.Class	loadClass(java.lang.String name, boolean checkPermission) This method loads a class from the bundle.
protected void	refresh() Refresh the bundle.
protected boolean	reload(AbstractBundle newBundle) Reload from a new bundle.
protected void	resume() Start the SystemBundle.
void	start() Start this bundle.
void	start(int options) Starts this bundle.
void	stop() Stop the framework.
void	stop(int options) Stops this bundle.
protected void	suspend() Stop the SystemBundle.
protected void	suspend(boolean lock) Stop this bundle w/o marking is persistently stopped.
void	uninstall() Uninstall this bundle.
protected boolean	unload() Unload the bundle.
protected void	unresolvePermissions(AbstractBundle[] refreshedBundles) No work to do for the SystemBundle.
void	update() Update this bundle.
void	update(java.io.InputStream in) Update this bundle from an InputStream.
FrameworkEvent	waitForStop(long timeout) Wait until this Framework has completely stopped.

Methods inherited from class org.eclipse.osgi.framework.internal.core.BundleHost

attachFragment, createContext, getBundleLoader, getContext, getFragments, getLoaderProxy, getRegisteredServices, getResources, getServicesInUse, readyToResume, startHook, startWorker, stopHook, stopWorker

Methods inherited from class org.eclipse.osgi.framework.internal.core.AbstractBundle

beginStateChange, checkValid, compare, compareTo, completeStateChange, createBundle, findEntries, findLocalEntryPaths, getBundleContext, getBundleData, getBundleDescription, getBundleId, getEntry, getEntryPaths, getFramework, getHeaders, getKey, getKeyHashCode, getLastModified, getLocation, getProtectionDomain, getResolutionFailureException, getResourceBundle, getSignerCertificates, getStartLevel, getState, getStateChanging, getSymbolicName, getVersion, isActive, isFragment, isResolved, loadBundleActivator, loadClass, resolve, setStatus, testStateChanging, toString, uninstallWorker, uninstallWorkerPrivileged, updateWorker, updateWorkerPrivileged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.osgi.framework.launch.Framework

getBundleId, getLocation, getSymbolicName

Methods inherited from interface org.osgi.framework.Bundle

findEntries, getBundleContext, getEntry, getEntryPaths, getHeaders, getLastModified, getRegisteredServices, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, loadClass

Constructor Detail

InternalSystemBundle

protected InternalSystemBundle(Framework framework)
                        throws BundleException

Private SystemBundle object constructor. This method creates the SystemBundle and its BundleContext. The SystemBundle's state is set to STARTING. This method is called when the framework is constructed.

Parameters:

framework - Framework this bundle is running in

Throws:

BundleException

Method Detail

load

protected void load()

Load the bundle. This methods overrides the Bundle method and does nothing.

Overrides:

load in class BundleHost

reload

protected boolean reload(AbstractBundle newBundle)

Reload from a new bundle. This methods overrides the Bundle method and does nothing.

Overrides:

reload in class BundleHost

Parameters:

newBundle -

Returns:

false

refresh

protected void refresh()

Refresh the bundle. This methods overrides the Bundle method and does nothing.

Overrides:

refresh in class BundleHost

unload

protected boolean unload()

Unload the bundle. This methods overrides the Bundle method and does nothing.

Overrides:

unload in class BundleHost

Returns:

false

close

protected void close()

Close the the Bundle's file. This method closes the BundleContext for the SystemBundle.

Overrides:

close in class AbstractBundle

loadClass

protected java.lang.Class loadClass(java.lang.String name,
                                    boolean checkPermission)
                             throws java.lang.ClassNotFoundException

This method loads a class from the bundle.

Overrides:

loadClass in class BundleHost

Parameters:

name - the name of the desired Class.

checkPermission - indicates whether a permission check should be done.

Returns:

the resulting Class

Throws:

java.lang.ClassNotFoundException - if the class definition was not found.

getResource

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

Find the specified resource in this bundle. This methods returns null for the system bundle.

Specified by:

getResource in interface Bundle

Overrides:

getResource in class BundleHost

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.

See Also:

Bundle.getEntry(java.lang.String), Bundle.findEntries(java.lang.String, java.lang.String, boolean)

isUnresolved

protected boolean isUnresolved()

Indicate SystemBundle is resolved.

start

public void start()

Start this bundle. This methods overrides the Bundle method and does nothing.

Specified by:

start in interface Bundle

Specified by:

start in interface Framework

Overrides:

start in class AbstractBundle

See Also:

Bundle.start(int)

start

public void start(int options)

Description copied from interface: Bundle

Starts this bundle.

If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.

If the Framework implements the optional Start Level service and the current start level is less than this bundle's start level:

• If the Bundle.START_TRANSIENT option is set, then a BundleException is thrown indicating this bundle cannot be started due to the Framework's current start level.
• Otherwise, the Framework must set this bundle's persistent autostart setting to Started with declared activation if the Bundle.START_ACTIVATION_POLICY option is set or Started with eager activation if not set.

When the Framework's current start level becomes equal to or more than this bundle's start level, this bundle will be started.

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

1. If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be started.
2. If this bundle's state is ACTIVE then this method returns immediately.
3. If the Bundle.START_TRANSIENT option is not set then set this bundle's autostart setting to Started with declared activation if the Bundle.START_ACTIVATION_POLICY option is set or Started with eager activation if not set. When the Framework is restarted and this bundle's autostart setting is not Stopped, this bundle must be automatically started.
4. If this bundle's state is not RESOLVED, an attempt is made to resolve this bundle. If the Framework cannot resolve this bundle, a BundleException is thrown.
5. If the Bundle.START_ACTIVATION_POLICY option is set and this bundle's declared activation policy is lazy then:
   • If this bundle's state is STARTING then this method returns immediately.
   • This bundle's state is set to STARTING.
   • A bundle event of type BundleEvent.LAZY_ACTIVATION is fired.
   • This method returns immediately and the remaining steps will be followed when this bundle's activation is later triggered.
6. This bundle's state is set to STARTING.
7. A bundle event of type BundleEvent.STARTING is fired.
8. 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 then:
   • This bundle's state is set to STOPPING.
   • A bundle event of type BundleEvent.STOPPING is fired.
   • Any services registered by this bundle must be unregistered.
   • Any services used by this bundle must be released.
   • Any listeners registered by this bundle must be removed.
   • This bundle's state is set to RESOLVED.
   • A bundle event of type BundleEvent.STOPPED is fired.
   • A BundleException is then thrown.
9. If this bundle's state is UNINSTALLED, because this bundle was uninstalled while the BundleActivator.start method was running, a BundleException is thrown.
10. This bundle's state is set to ACTIVE.
11. A bundle event of type BundleEvent.STARTED is fired.

Preconditions

• getState() in { INSTALLED, RESOLVED } or { INSTALLED, RESOLVED, STARTING } if this bundle has a lazy activation policy.

Postconditions, no exceptions thrown

• Bundle autostart setting is modified unless the Bundle.START_TRANSIENT option was set.
• getState() in { ACTIVE } unless the lazy activation policy was used.
• BundleActivator.start() has been called and did not throw an exception unless the lazy activation policy was used.

Postconditions, when an exception is thrown

• Depending on when the exception occurred, bundle autostart setting is modified unless the Bundle.START_TRANSIENT option was set.
• getState() not in { STARTING, ACTIVE }.

Specified by:

start in interface Bundle

Specified by:

start in interface Framework

Overrides:

start in class AbstractBundle

Parameters:

options - The options for starting this bundle. See Bundle.START_TRANSIENT and Bundle.START_ACTIVATION_POLICY. The Framework must ignore unrecognized options.

See Also:

Framework.start()

resume

protected void resume()

Start the SystemBundle. This method launches the framework.

Overrides:

resume in class AbstractBundle

stop

public void stop()

Stop the framework. This method spawns a thread which will call framework.shutdown.

Specified by:

stop in interface Bundle

Specified by:

stop in interface Framework

Overrides:

stop in class AbstractBundle

See Also:

Bundle.start(int)

stop

public void stop(int options)

Description copied from interface: Bundle

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 is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete 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 the Bundle.STOP_TRANSIENT option is not set then then set this bundle's persistent autostart setting to to Stopped. When the Framework is restarted and this bundle's autostart setting is Stopped, this bundle must not be automatically started.
4. If this bundle's state is not STARTING or ACTIVE then this method returns immediately.
5. This bundle's state is set to STOPPING.
6. A bundle event of type BundleEvent.STOPPING is fired.
7. If this bundle's state was ACTIVE prior to setting the state to STOPPING, the BundleActivator.stop(org.osgi.framework.BundleContext) method of this bundle's BundleActivator, if one is specified, is called. If that method throws an exception, this method must continue to stop this bundle and a BundleException must be thrown after completion of the remaining steps.
8. Any services registered by this bundle must be unregistered.
9. Any services used by this bundle must be released.
10. Any listeners registered by this bundle must be removed.
11. If this bundle's state is UNINSTALLED, because this bundle was uninstalled while the BundleActivator.stop method was running, a BundleException must be thrown.
12. This bundle's state is set to RESOLVED.
13. A bundle event of type BundleEvent.STOPPED is fired.

Preconditions

• getState() in { ACTIVE }.

Postconditions, no exceptions thrown

• Bundle autostart setting is modified unless the Bundle.STOP_TRANSIENT option was set.
• getState() not in { ACTIVE, STOPPING }.
• BundleActivator.stop has been called and did not throw an exception.

Postconditions, when an exception is thrown

• Bundle autostart setting is modified unless the Bundle.STOP_TRANSIENT option was set.

Specified by:

stop in interface Bundle

Specified by:

stop in interface Framework

Overrides:

stop in class AbstractBundle

Parameters:

options - The options for stoping this bundle. See Bundle.STOP_TRANSIENT. The Framework must ignore unrecognized options.

See Also:

Framework.stop()

suspend

protected void suspend()

Stop the SystemBundle. This method shuts down the framework.

suspend

protected void suspend(boolean lock)

Description copied from class: AbstractBundle

Stop this bundle w/o marking is persistently stopped. 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 Bundle.UNINSTALLEDthen an IllegalStateException is thrown.
2. If the bundle is Bundle.STOPPING,Bundle.RESOLVED, or Bundle.INSTALLEDthen this method returns immediately.
3. If the bundle is Bundle.STARTINGthen this method may wait for the bundle to reach the Bundle.ACTIVEstate before continuing. If this does not occur in a reasonable time, a BundleExceptionis thrown to indicate the bundle was unable to be stopped.
4. The state of the bundle is set to Bundle.STOPPING.
5. The stopmethod of the bundle's BundleActivator, if one is specified, is called. If the BundleActivatorthrows an exception, this method will continue to stop the bundle. A BundleExceptionwill be thrown after completion of the remaining steps.
6. 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.
7. The state of the bundle is set to Bundle.RESOLVED.
8. A BundleEventof type BundleEvent.STOPPEDis broadcast.

Preconditons

• getState() in {Bundle.ACTIVE}.

Postconditons, no exceptions thrown

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

Postconditions, when an exception is thrown

• None.

Overrides:

suspend in class AbstractBundle

Parameters:

lock - true if state change lock should be held when returning from this method.

update

public void update()

Update this bundle. This method spawns a thread which will call framework.shutdown followed by framework.launch.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Overrides:

update in class AbstractBundle

See Also:

Bundle.update(InputStream)

update

public void update(java.io.InputStream in)

Update this bundle from an InputStream. This methods overrides the Bundle method and does nothing.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Overrides:

update in class AbstractBundle

Parameters:

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

See Also:

Bundle.stop(), Bundle.start()

uninstall

public void uninstall()
               throws BundleException

Uninstall this bundle. This methods overrides the Bundle method and throws an exception.

Specified by:

uninstall in interface Bundle

Specified by:

uninstall in interface Framework

Overrides:

uninstall in class AbstractBundle

Throws:

BundleException - If the uninstall failed.

See Also:

AbstractBundle.stop()

hasPermission

public boolean hasPermission(java.lang.Object permission)

Determine whether the bundle has the requested permission. This methods overrides the Bundle method and returns true.

Specified by:

hasPermission in interface Bundle

Overrides:

hasPermission in class AbstractBundle

Parameters:

permission - The requested permission.

Returns:

true

unresolvePermissions

protected void unresolvePermissions(AbstractBundle[] refreshedBundles)

No work to do for the SystemBundle.

Parameters:

refreshedBundles - A list of bundles which have been refreshed as a result of a packageRefresh

getHeaders

public java.util.Dictionary getHeaders(java.lang.String localeString)

Description copied from class: AbstractBundle

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. If a Manifest header begins with a '%', it will be evaluated with the specified properties file for the specied Locale.

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.

Specified by:

getHeaders in interface Bundle

Overrides:

getHeaders in class AbstractBundle

Parameters:

localeString - The locale name into which the header values are to be localized. If the specified locale is null then the locale returned by java.util.Locale.getDefault is used. If the specified locale is the empty string, this method will return the raw (unlocalized) manifest headers including any leading "%".

Returns:

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

See Also:

Bundle.getHeaders(), Constants.BUNDLE_LOCALIZATION

init

public void init()

Description copied from interface: Framework

Initialize this Framework. After calling this method, this Framework must:

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

This Framework will not actually be started until start is called.

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

Specified by:

init in interface Framework

waitForStop

public FrameworkEvent waitForStop(long timeout)
                           throws java.lang.InterruptedException

Description copied from interface: Framework

Wait until this Framework has completely stopped. The stop and update methods on a Framework performs an asynchronous stop of the Framework. This method can be used to wait until the asynchronous stop of this Framework has completed. This method will only wait if called when this Framework 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 Framework has stopped.

Specified by:

waitForStop in interface Framework

Parameters:

timeout - Maximum number of milliseconds to wait until this Framework 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 Framework has been stopped.
• STOPPED_UPDATE - This Framework has been updated which has shutdown and will now restart.
• STOPPED_BOOTCLASSPATH_MODIFIED - This Framework has been stopped 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.
• WAIT_TIMEDOUT - This method has timed out and returned before this Framework has stopped.

Throws:

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

getClassLoader

public java.lang.ClassLoader getClassLoader()

Description copied from class: BundleHost

Gets the class loader for the host bundle. This may end up creating the bundle class loader if it was not already created. A null value may be returned if the bundle is not resolved.

Overrides:

getClassLoader in class BundleHost

Returns:

the bundle class loader or null if the bundle is not resolved.