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

java.lang.Object
  extended by 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, 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)
          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()
           
protected  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  Bundle[] getFragments()
           
 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.
protected  BundleLoaderProxy[] getHosts()
           
 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.
protected  BundleProtectionDomain getProtectionDomain()
          Get the bundle's ProtectionDomain.
 java.lang.String getResolutionFailureMessage()
           
 java.util.ResourceBundle getResourceBundle(java.lang.String localeString)
           
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()
           
 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()
           
protected  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 classloader.
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.
protected  void unresolvePermissions()
          The bundle must unresolve the permissions.
 void update()
          Update this bundle.
 void update(java.io.InputStream in)
          Update 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 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)
                                      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.

isActive

protected boolean isActive()
Return true if the bundle is starting or active.


isResolved

protected 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
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

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:

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 Postconditions, no exceptions thrown Postconditions, when an exception is thrown

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
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

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
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

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 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. 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. 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 Postconditions, no exceptions thrown Postconditions, when an exception is thrown

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
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

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
Update this bundle. If the bundle is Bundle.ACTIVE, the bundle will be stopped before the update and started after the update successfully completes.

The following steps are followed to update 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, the exception is rethrown terminating the update.
  3. The location for the new version of the bundle is determined from either the manifest header Bundle-UpdateLocation if available or the original location.
  4. The location is interpreted in an implementation dependent way (typically as a URL) and the new version of the bundle is obtained from the location.
  5. The new version of the bundle is installed. If the framework is unable to install the new version of the bundle, the original version of the bundle will be restored and a BundleExceptionwill be thrown after completion of the remaining steps.
  6. The state of the bundle is set to Bundle.INSTALLED.
  7. If the new version of the bundle was successfully installed, a BundleEventof type BundleEvent.UPDATEDis broadcast.
  8. If the bundle was originally Bundle.ACTIVE, the updated bundle is started as described in the start()method. If start() throws an exception, a FrameworkEventof type FrameworkEvent.ERRORis broadcast containing the exception.
Preconditions
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

Specified by:
update in interface Bundle
Throws:
BundleException - If the update fails.
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(), start()

update

public void update(java.io.InputStream in)
            throws BundleException
Update this bundle from an InputStream.

This method performs all the steps listed in update(), except the bundle will be read in through the supplied InputStream, rather than a URL.

Specified by:
update in interface Bundle
Parameters:
in - The InputStream from which to read the new bundle.
Throws:
BundleException - If the provided stream cannot be read or the update fails.
See Also:
update()

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
Postconditons, no exceptions thrown
Postconditions, when an exception is thrown

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:

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

protected BundleProtectionDomain getProtectionDomain()
Get the bundle's ProtectionDomain.

Returns:
bundle's ProtectionDomain.

unresolvePermissions

protected void unresolvePermissions()
The bundle must unresolve the permissions.


getFragments

protected Bundle[] getFragments()

isFragment

protected boolean isFragment()

getHosts

protected BundleLoaderProxy[] getHosts()

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 classloader.

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 classloader 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 "/".

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 classloader 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.

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 name must be unique, it is recommended to use a reverse domain name naming convention like that used for java packages. If this bundle does not have a specified symbolic name then null is returned.

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.

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()

getBundleDescription

protected 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.

getResolutionFailureMessage

public java.lang.String getResolutionFailureMessage()

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 classloader 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();
 

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 and it supports substring matching, 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)