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

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

All Implemented Interfaces:

java.lang.Comparable, KeyedElement, Bundle

Direct Known Subclasses:

BundleFragment, BundleHost

public abstract class AbstractBundle
extends java.lang.Object
implements Bundle, java.lang.Comparable, KeyedElement

This object is given out to bundles and wraps the internal Bundle object. It is destroyed when a bundle is uninstalled and reused if a bundle is updated. This class is abstract and is extended by BundleHost and BundleFragment.

Field Summary

protected BundleData	bundledata Bundle's BundleData object
protected BundleProtectionDomain	domain ProtectionDomain for the bundle
protected Framework	framework The Framework this bundle is part of
protected ManifestLocalization	manifestLocalization
protected int	state The state of the bundle.
protected java.lang.Object	statechangeLock Internal object used for state change synchronization
protected java.lang.Thread	stateChanging A flag to denote whether a bundle state change is in progress

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

AbstractBundle(BundleData bundledata, Framework framework) Bundle object constructor.

Method Summary

protected void	beginStateChange() This method marks the bundle's state as changing so that other calls to start/stop/suspend/update/uninstall can wait until the state change is complete.
protected void	checkValid() This method checks that the bundle is not uninstalled.
protected void	close() Close the the Bundle's file.
boolean	compare(KeyedElement other) Compares this element with a specified element
int	compareTo(java.lang.Object obj) Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.
protected void	completeStateChange() This method completes the bundle state change by setting stateChanging to null and notifying one waiter that the state change has completed.
protected static AbstractBundle	createBundle(BundleData bundledata, Framework framework, boolean setBundle) Bundle object constructor.
java.util.Enumeration	findEntries(java.lang.String path, java.lang.String filePattern, boolean recurse) Returns entries in this bundle and its attached fragments.
protected void	findLocalEntryPaths(java.lang.String path, Filter patternFilter, java.util.Hashtable patternProps, boolean recurse, java.util.List pathList)
BundleContext	getBundleContext() Returns this bundle's BundleContext.
BundleData	getBundleData()
BundleDescription	getBundleDescription()
long	getBundleId() Retrieve the bundle's unique identifier, which the framework assigned to this bundle when it was installed.
protected abstract BundleLoader	getBundleLoader()
protected abstract BundleContextImpl	getContext() Return the current context for this bundle.
java.net.URL	getEntry(java.lang.String fileName) Returns a URL to the entry at the specified path in this bundle.
java.util.Enumeration	getEntryPaths(java.lang.String path) Returns an Enumeration of all the paths (String objects) to entries within this bundle whose longest sub-path matches the specified path.
protected BundleFragment[]	getFragments()
Framework	getFramework()
java.util.Dictionary	getHeaders() Return the bundle's manifest headers and values from the manifest's preliminary section.
java.util.Dictionary	getHeaders(java.lang.String localeString) Returns this bundle's Manifest headers and values.
java.lang.Object	getKey() Returns the key for this element
int	getKeyHashCode() Returns the hash code of the key
long	getLastModified() Returns the time when this bundle was last modified.
java.lang.String	getLocation() Retrieve the location identifier of the bundle.
BundleProtectionDomain	getProtectionDomain() Get the bundle's ProtectionDomain.
BundleException	getResolutionFailureException()
java.util.ResourceBundle	getResourceBundle(java.lang.String localeString)
java.util.Map	getSignerCertificates(int signersType) Return the certificates for the signers of this bundle and the certificate chains for those signers.
protected int	getStartLevel()
int	getState() Returns the current state of the bundle.
java.lang.Thread	getStateChanging()
java.lang.String	getSymbolicName() Returns the symbolic name of this bundle as specified by its Bundle-SymbolicName manifest header.
Version	getVersion() Returns the version of this bundle as specified by its Bundle-Version manifest header.
boolean	hasPermission(java.lang.Object permission) Determine whether the bundle has the requested permission.
protected boolean	isActive() Return true if the bundle is starting or active.
protected boolean	isFragment()
boolean	isResolved() Return true if the bundle is resolved.
protected abstract void	load() Load the bundle.
protected BundleActivator	loadBundleActivator() Load and instantiate bundle's BundleActivator class
java.lang.Class	loadClass(java.lang.String classname) Loads the specified class using this bundle's class loader.
protected abstract java.lang.Class	loadClass(java.lang.String name, boolean checkPermission) This method loads a class from the bundle.
protected boolean	readyToResume() This method does the following Return false if the bundle is a fragment Return false if the bundle is not at the correct start-level Return false if the bundle is not persistently marked for start Return true if the bundle's activation policy is persistently ignored Return true if the bundle does not define an activation policy Transition to STARTING state and Fire LAZY_ACTIVATION event Return false
protected abstract void	refresh() Refresh the bundle.
protected abstract boolean	reload(AbstractBundle newBundle) Reload from a new bundle.
protected void	resolve() Mark this bundle as resolved.
protected void	resume() Start this bundle w/o marking is persistently started.
protected void	setStatus(int mask, boolean state) Set the persistent status bit for the bundle.
void	start() Start this bundle.
void	start(int options) Starts this bundle.
protected abstract void	startWorker(int options) Internal worker to start a bundle.
void	stop() Stop this bundle.
void	stop(int options) Stops this bundle.
protected abstract void	stopWorker(int options) Internal worker to stop a bundle.
protected void	suspend(boolean lock) Stop this bundle w/o marking is persistently stopped.
boolean	testStateChanging(java.lang.Object thread)
java.lang.String	toString() Return a string representation of this bundle.
void	uninstall() Uninstall this bundle.
protected void	uninstallWorker(java.security.PrivilegedExceptionAction action) Uninstall worker.
protected void	uninstallWorkerPrivileged() Uninstall worker.
protected abstract boolean	unload() Unload the bundle.
void	update() Updates this bundle.
void	update(java.io.InputStream in) Updates this bundle from an InputStream.
protected void	updateWorker(java.security.PrivilegedExceptionAction action) Update worker.
protected void	updateWorkerPrivileged(java.net.URLConnection source, java.security.AccessControlContext callerContext) Update worker.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.osgi.framework.Bundle

getRegisteredServices, getResource, getResources, getServicesInUse

Field Detail

framework

protected Framework framework

The Framework this bundle is part of

state

protected volatile int state

The state of the bundle.

stateChanging

protected volatile java.lang.Thread stateChanging

A flag to denote whether a bundle state change is in progress

bundledata

protected BundleData bundledata

Bundle's BundleData object

statechangeLock

protected java.lang.Object statechangeLock

Internal object used for state change synchronization

domain

protected BundleProtectionDomain domain

ProtectionDomain for the bundle

manifestLocalization

protected volatile ManifestLocalization manifestLocalization

Constructor Detail

AbstractBundle

protected AbstractBundle(BundleData bundledata,
                         Framework framework)

Bundle object constructor. This constructor should not perform any real work.

Parameters:

bundledata - BundleData for this bundle

framework - Framework this bundle is running in

Method Detail

createBundle

protected static AbstractBundle createBundle(BundleData bundledata,
                                             Framework framework,
                                             boolean setBundle)
                                      throws BundleException

Bundle object constructor. This constructor should not perform any real work.

Parameters:

bundledata - BundleData for this bundle

framework - Framework this bundle is running in

Throws:

BundleException

load

protected abstract void load()

Load the bundle.

reload

protected abstract boolean reload(AbstractBundle newBundle)

Reload from a new bundle. This method must be called while holding the bundles lock.

Parameters:

newBundle - Dummy Bundle which contains new data.

Returns:

true if an exported package is "in use". i.e. it has been imported by a bundle

refresh

protected abstract void refresh()

Refresh the bundle. This is called by Framework.refreshPackages. This method must be called while holding the bundles lock. this.loader.unimportPackages must have already been called before calling this method!

unload

protected abstract boolean unload()

Unload the bundle. This method must be called while holding the bundles lock.

Returns:

true if an exported package is "in use". i.e. it has been imported by a bundle

close

protected void close()

Close the the Bundle's file.

loadBundleActivator

protected BundleActivator loadBundleActivator()
                                       throws BundleException

Load and instantiate bundle's BundleActivator class

Throws:

BundleException

loadClass

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

This method loads a class from the bundle.

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.

getState

public int getState()

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

Specified by:

getState in interface Bundle

Returns:

bundle's state.

getFramework

public Framework getFramework()

isActive

protected boolean isActive()

Return true if the bundle is starting or active.

isResolved

public boolean isResolved()

Return true if the bundle is resolved.

start

public void start()
           throws BundleException

Start this bundle. If 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 the bundle is Bundle.UNINSTALLEDthen an IllegalStateException is thrown.
2. If the bundle is Bundle.ACTIVEor Bundle.STARTINGthen this method returns immediately.
3. If the bundle is Bundle.STOPPINGthen this method may wait for the bundle to return to the Bundle.RESOLVEDstate before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate the bundle was unable to be started.
4. If the bundle is not Bundle.RESOLVED, an attempt is made to resolve the bundle. If the bundle cannot be resolved, a BundleExceptionis thrown.
5. The state of the bundle is set to Bundle.STARTING.
6. The startmethod of the bundle's BundleActivator, if one is specified, is called. If the BundleActivatoris invalid or throws an exception, the state of the bundle is set back to Bundle.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 BundleExceptionis 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 Bundle.ACTIVE.
9. A BundleEventof type BundleEvent.STARTEDis broadcast.

Preconditons

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

Postconditons, no exceptions thrown

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

Postconditions, when an exception is thrown

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

Specified by:

start in interface Bundle

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.

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

java.lang.SecurityException - If the caller does not have AdminPermission permission and the Java runtime environment supports permissions.

See Also:

Bundle.start(int)

start

public void start(int options)
           throws BundleException

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

Parameters:

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

Throws:

BundleException - If this bundle could not 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 or this bundle is a fragment.

startWorker

protected abstract void startWorker(int options)
                             throws BundleException

Internal worker to start a bundle.

Parameters:

options -

Throws:

BundleException

readyToResume

protected boolean readyToResume()

This method does the following

1. Return false if the bundle is a fragment
2. Return false if the bundle is not at the correct start-level
3. Return false if the bundle is not persistently marked for start
4. Return true if the bundle's activation policy is persistently ignored
5. Return true if the bundle does not define an activation policy
6. Transition to STARTING state and Fire LAZY_ACTIVATION event
7. Return false

Returns:

true if the bundle should be resumed

resume

protected void resume()
               throws BundleException

Start this bundle w/o marking is persistently started.

The following steps are followed to start a bundle:

1. If the bundle is Bundle.UNINSTALLEDthen an IllegalStateException is thrown.
2. If the bundle is Bundle.ACTIVEor Bundle.STARTINGthen this method returns immediately.
3. If the bundle is Bundle.STOPPINGthen this method may wait for the bundle to return to the Bundle.RESOLVEDstate before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate the bundle was unable to be started.
4. If the bundle is not Bundle.RESOLVED, an attempt is made to resolve the bundle. If the bundle cannot be resolved, a BundleExceptionis thrown.
5. The state of the bundle is set to Bundle.STARTING.
6. The startmethod of the bundle's BundleActivator, if one is specified, is called. If the BundleActivatoris invalid or throws an exception, the state of the bundle is set back to Bundle.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 BundleExceptionis then thrown.
7. The state of the bundle is set to Bundle.ACTIVE.
8. A BundleEventof type BundleEvent.STARTEDis broadcast.

Preconditons

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

Postconditons, no exceptions thrown

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

Postconditions, when an exception is thrown

• getState() not in {Bundle.STARTING,Bundle.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.

java.lang.IllegalStateException - If the bundle tries to change its own state.

stop

public void stop()
          throws BundleException

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 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. 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 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.
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 Bundle.RESOLVED.
9. 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.

Specified by:

stop in interface Bundle

Throws:

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

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

java.lang.SecurityException - If the caller does not have AdminPermission permission and the Java runtime environment supports permissions.

See Also:

Bundle.start(int)

stop

public void stop(int options)
          throws BundleException

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

Parameters:

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

Throws:

BundleException - If this bundle's BundleActivator threw an exception or this bundle is a fragment.

stopWorker

protected abstract void stopWorker(int options)
                            throws BundleException

Internal worker to stop a bundle.

Parameters:

options -

Throws:

BundleException

setStatus

protected void setStatus(int mask,
                         boolean state)

Set the persistent status bit for the bundle.

Parameters:

mask - Mask for bit to set/clear

state - true to set bit, false to clear bit

suspend

protected void suspend(boolean lock)
                throws BundleException

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.

Parameters:

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

Throws:

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

java.lang.IllegalStateException - If the bundle tries to change its own state.

update

public void update()
            throws BundleException

Description copied from interface: Bundle

Updates this bundle.

This method performs the same function as calling Bundle.update(InputStream) with a null InputStream.

Specified by:

update in interface Bundle

Throws:

BundleException - If the update fails.

See Also:

Bundle.update(InputStream)

update

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

Description copied from interface: Bundle

Updates this bundle from an InputStream.

If the specified InputStream is null, the Framework must create the InputStream from which to read the updated bundle by interpreting, in an implementation dependent manner, this bundle's Bundle-UpdateLocation Manifest header, if present, or this bundle's original location.

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

If this bundle has exported any packages that are imported by another bundle, these packages must not be updated. Instead, the previous package version must 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, this 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 updated version of this bundle is read from the input stream and installed. If the Framework is unable to install the updated version of this bundle, the original version of this bundle must be restored and a BundleException must be thrown after completion of the remaining steps.
4. This bundle's state is set to INSTALLED.
5. If the updated version of this bundle was successfully installed, a bundle event of type BundleEvent.UPDATED is fired.
6. 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.ERROR is fired 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.

Specified by:

update in interface Bundle

Parameters:

in - The InputStream from which to read the new bundle or null to indicate the Framework must create the input stream from this bundle's Bundle-UpdateLocation Manifest header, if present, or this bundle's original location. The input stream must always be closed when this method completes, even if an exception is thrown.

Throws:

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

See Also:

Bundle.stop(), Bundle.start()

updateWorker

protected void updateWorker(java.security.PrivilegedExceptionAction action)
                     throws BundleException

Update worker. Assumes the caller has the state change lock.

Throws:

BundleException

updateWorkerPrivileged

protected void updateWorkerPrivileged(java.net.URLConnection source,
                                      java.security.AccessControlContext callerContext)
                               throws BundleException

Update worker. Assumes the caller has the state change lock.

Throws:

BundleException

uninstall

public void uninstall()
               throws BundleException

Uninstall this bundle.

This method removes all traces of the bundle, including any data in the persistent storage area provided for the bundle by the framework.

The following steps are followed to uninstall a bundle:

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

Preconditions

• getState() not in {Bundle.UNINSTALLED}.

Postconditons, no exceptions thrown

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

Postconditions, when an exception is thrown

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

Specified by:

uninstall in interface Bundle

Throws:

BundleException - If the uninstall failed.

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

java.lang.SecurityException - If the caller does not have AdminPermission permission and the Java runtime environment supports permissions.

See Also:

stop()

uninstallWorker

protected void uninstallWorker(java.security.PrivilegedExceptionAction action)
                        throws BundleException

Uninstall worker. Assumes the caller has the state change lock.

Throws:

BundleException

uninstallWorkerPrivileged

protected void uninstallWorkerPrivileged()
                                  throws BundleException

Uninstall worker. Assumes the caller has the state change lock.

Throws:

BundleException

getHeaders

public java.util.Dictionary getHeaders()

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 Bundle.UNINSTALLEDstate.

Specified by:

getHeaders in interface Bundle

Returns:

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

Throws:

java.lang.SecurityException - If the caller does not have AdminPermission permission and the Java runtime environment supports permissions.

See Also:

Constants.BUNDLE_LOCALIZATION

getHeaders

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

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

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.

Throws:

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

See Also:

Bundle.getHeaders(), Constants.BUNDLE_LOCALIZATION

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 Bundle.UNINSTALLEDstate.

Specified by:

getBundleId in interface Bundle

Returns:

This bundle's unique identifier.

getLocation

public java.lang.String getLocation()

Retrieve the location identifier of the bundle. This is typically the location passed to BundleContext.installBundlewhen 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 Bundle.UNINSTALLEDstate.

Specified by:

getLocation in interface Bundle

Returns:

A string that is the location identifier of the bundle.

Throws:

java.lang.SecurityException - If the caller does not have AdminPermission permission and the Java runtime environment supports permissions.

hasPermission

public boolean hasPermission(java.lang.Object permission)

Determine whether the bundle has the requested permission.

If the Java runtime environment does not supports 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.

Specified by:

hasPermission in interface Bundle

Parameters:

permission - The requested permission.

Returns:

true if the bundle has the requested permission or false if the bundle does not have the permission or the permission parameter is not an instanceof java.security.Permission.

Throws:

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

beginStateChange

protected void beginStateChange()
                         throws BundleException

This method marks the bundle's state as changing so that other calls to start/stop/suspend/update/uninstall can wait until the state change is complete. If stateChanging is non-null when this method is called, we will wait for the state change to complete. If the timeout expires without changing state (this may happen if the state change is back up our call stack), a BundleException is thrown so that we don't wait forever. A call to this method should be immediately followed by a try block whose finally block calls completeStateChange(). beginStateChange(); try { // change the bundle's state here... } finally { completeStateChange(); }

Throws:

BundleException - if the bundles state is still changing after waiting for the timeout.

completeStateChange

protected void completeStateChange()

This method completes the bundle state change by setting stateChanging to null and notifying one waiter that the state change has completed.

toString

public java.lang.String toString()

Return a string representation of this bundle.

Overrides:

toString in class java.lang.Object

Returns:

String

compareTo

public int compareTo(java.lang.Object obj)

Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - another Bundle an object to compare the receiver to

Returns:

int which should be <0 if the receiver should sort before the argument, 0 if the receiver should sort in the same position as the argument, and >0 if the receiver should sort after the argument.

Throws:

java.lang.ClassCastException - if the argument can not be converted into something comparable with the receiver.

checkValid

protected void checkValid()

This method checks that the bundle is not uninstalled. If the bundle is uninstalled, an IllegalStateException is thrown.

Throws:

java.lang.IllegalStateException - If the bundle is uninstalled.

getProtectionDomain

public BundleProtectionDomain getProtectionDomain()

Get the bundle's ProtectionDomain.

Returns:

bundle's ProtectionDomain.

getFragments

protected BundleFragment[] getFragments()

isFragment

protected boolean isFragment()

loadClass

public java.lang.Class loadClass(java.lang.String classname)
                          throws java.lang.ClassNotFoundException

Description copied from interface: Bundle

Loads the specified class using this bundle's class loader.

If this bundle is a fragment bundle then this method must throw a ClassNotFoundException.

If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to load the class.

If this bundle cannot be resolved, a Framework event of type FrameworkEvent.ERROR is fired containing a BundleException with details of the reason this bundle could not be resolved. This method must then throw a ClassNotFoundException.

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

Specified by:

loadClass in interface Bundle

Parameters:

classname - The name of the class to load.

Returns:

The Class object for the requested class.

Throws:

java.lang.ClassNotFoundException - If no such class can be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,CLASS], and the Java Runtime Environment supports permissions.

getEntryPaths

public java.util.Enumeration getEntryPaths(java.lang.String path)

Description copied from interface: Bundle

Returns an Enumeration of all the paths (String objects) to entries within this bundle whose longest sub-path matches the specified path. This bundle's class loader is not used to search for entries. Only the contents of this bundle are searched.

The specified path is always relative to the root of this bundle and may begin with a "/". A path value of "/" indicates the root of this bundle.

Returned paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of this bundle and must not begin with "/".

Note: Jar and zip files are not required to include directory entries. Paths to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getEntryPaths in interface Bundle

Parameters:

path - The path name for which to return entry paths.

Returns:

An Enumeration of the entry paths (String objects) or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

getEntry

public java.net.URL getEntry(java.lang.String fileName)

Description copied from interface: Bundle

Returns a URL to the entry at the specified path in this bundle. This bundle's class loader is not used to search for the entry. Only the contents of this bundle are searched for the entry.

The specified path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getEntry in interface Bundle

Parameters:

fileName - The path name of the entry.

Returns:

A URL to the entry, or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

getSymbolicName

public java.lang.String getSymbolicName()

Description copied from interface: Bundle

Returns the symbolic name of this bundle as specified by its Bundle-SymbolicName manifest header. The bundle symbolic name together with a version must identify a unique bundle. The bundle symbolic name should be based on the reverse domain name naming convention like that used for java packages.

This method must continue to return this bundle's symbolic name while this bundle is in the UNINSTALLED state.

Specified by:

getSymbolicName in interface Bundle

Returns:

The symbolic name of this bundle or null if this bundle does not have a symbolic name.

getLastModified

public long getLastModified()

Description copied from interface: Bundle

Returns the time when this bundle was last modified. A bundle is considered to be modified when it is installed, updated or uninstalled.

The time value is the number of milliseconds since January 1, 1970, 00:00:00 GMT.

Specified by:

getLastModified in interface Bundle

Returns:

The time when this bundle was last modified.

getBundleData

public BundleData getBundleData()

getVersion

public Version getVersion()

Description copied from interface: Bundle

Returns the version of this bundle as specified by its Bundle-Version manifest header. If this bundle does not have a specified version then Version.emptyVersion is returned.

This method must continue to return this bundle's version while this bundle is in the UNINSTALLED state.

Specified by:

getVersion in interface Bundle

Returns:

The version of this bundle.

getBundleDescription

public BundleDescription getBundleDescription()

getStartLevel

protected int getStartLevel()

getBundleLoader

protected abstract BundleLoader getBundleLoader()

resolve

protected void resolve()

Mark this bundle as resolved.

getBundleContext

public BundleContext getBundleContext()

Description copied from interface: Bundle

Returns this bundle's BundleContext. The returned BundleContext can be used by the caller to act on behalf of this bundle.

If this bundle is not in the Bundle.STARTING, Bundle.ACTIVE, or Bundle.STOPPING states or this bundle is a fragment bundle, then this bundle has no valid BundleContext. This method will return null if this bundle has no valid BundleContext.

Specified by:

getBundleContext in interface Bundle

Returns:

A BundleContext for this bundle or null if this bundle has no valid BundleContext.

getContext

protected abstract BundleContextImpl getContext()

Return the current context for this bundle.

Returns:

BundleContext for this bundle.

getResolutionFailureException

public BundleException getResolutionFailureException()

getKeyHashCode

public int getKeyHashCode()

Description copied from interface: KeyedElement

Returns the hash code of the key

Specified by:

getKeyHashCode in interface KeyedElement

Returns:

the hash code of the key

compare

public boolean compare(KeyedElement other)

Description copied from interface: KeyedElement

Compares this element with a specified element

Specified by:

compare in interface KeyedElement

Parameters:

other - the element to compare with

Returns:

returns true if the specified element equals this element

getKey

public java.lang.Object getKey()

Description copied from interface: KeyedElement

Returns the key for this element

Specified by:

getKey in interface KeyedElement

Returns:

the key for this element

getResourceBundle

public java.util.ResourceBundle getResourceBundle(java.lang.String localeString)

testStateChanging

public boolean testStateChanging(java.lang.Object thread)

getStateChanging

public java.lang.Thread getStateChanging()

findEntries

public java.util.Enumeration findEntries(java.lang.String path,
                                         java.lang.String filePattern,
                                         boolean recurse)

Description copied from interface: Bundle

Returns entries in this bundle and its attached fragments. This bundle's class loader is not used to search for entries. Only the contents of this bundle and its attached fragments are searched for the specified entries. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to find entries.

This method is intended to be used to obtain configuration, setup, localization and other information from this bundle. This method takes into account that the "contents" of this bundle can be extended with fragments. This "bundle space" is not a namespace with unique members; the same entry name can be present multiple times. This method therefore returns an enumeration of URL objects. These URLs can come from different JARs but have the same path name. This method can either return only entries in the specified path or recurse into subdirectories returning entries in the directory tree beginning at the specified path. Fragments can be attached after this bundle is resolved, possibly changing the set of URLs returned by this method. If this bundle is not resolved, only the entries in the JAR file of this bundle are returned.

Examples:

 // List all XML files in the OSGI-INF directory and below
 Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
 
 // Find a specific localization file
 Enumeration e = b
                .findEntries("OSGI-INF/l10n", "bundle_nl_DU.properties", false);
 if (e.hasMoreElements())
        return (URL) e.nextElement();
 

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

findEntries in interface Bundle

Parameters:

path - The path name in which to look. The path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

filePattern - The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. If the entry is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.

recurse - If true, recurse into subdirectories. Otherwise only return entries from the specified path.

Returns:

An enumeration of URL objects for each matching entry, or null if an entry could not be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions. The URLs are sorted such that entries from this bundle are returned first followed by the entries from attached fragments in ascending bundle id order. If this bundle is a fragment, then only matching entries in this fragment are returned.

findLocalEntryPaths

protected void findLocalEntryPaths(java.lang.String path,
                                   Filter patternFilter,
                                   java.util.Hashtable patternProps,
                                   boolean recurse,
                                   java.util.List pathList)

getSignerCertificates

public java.util.Map getSignerCertificates(int signersType)

Description copied from interface: Bundle

Return the certificates for the signers of this bundle and the certificate chains for those signers.

Specified by:

getSignerCertificates in interface Bundle

Parameters:

signersType - If Bundle.SIGNERS_ALL is specified, then information on all signers of this bundle is returned. If Bundle.SIGNERS_TRUSTED is specified, then only information on the signers of this bundle trusted by the framework is returned.

Returns:

The X509Certificates for the signers of this bundle and the X509Certificate chains for those signers. The keys of the Map are the X509Certificates of the signers of this bundle. The value for a key is a List containing the X509Certificate chain for the signer. The first item in the List is the signer's X509Certificate which is then followed by the rest of the X509Certificate chain. The returned Map will be empty if there are no signers. The returned Map is the property of the caller who is free to modify it.