Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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<Bundle>, KeyedElement, Bundle, BundleReference, BundleStartLevel, BundleRevisions
Direct Known Subclasses:
BundleFragment, BundleHost
public abstract class AbstractBundle
extends java.lang.Object
implements Bundle, java.lang.Comparable<Bundle>, KeyedElement, BundleStartLevel, BundleReference, BundleRevisions

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
<A> A
adapt(java.lang.Class<A> adapterType)
          Adapt this bundle to the specified type.
protected
<A> A
adapt0(java.lang.Class<A> adapterType)
           
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(Bundle 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<java.net.URL> findEntries(java.lang.String path, java.lang.String filePattern, boolean recurse)
          Returns entries in this bundle and its attached fragments.
 Bundle getBundle()
          Returns the Bundle object associated with this BundleReference.
 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.io.File getDataFile(java.lang.String filename)
          Creates a File object for a file in the persistent storage area provided for this bundle by the Framework.
 java.net.URL getEntry(java.lang.String fileName)
          Returns a URL to the entry at the specified path in this bundle.
 java.util.Enumeration<java.lang.String> 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<java.lang.String,java.lang.String> getHeaders()
          Return the bundle's manifest headers and values from the manifest's preliminary section.
 java.util.Dictionary<java.lang.String,java.lang.String> 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.List<BundleRevision> getRevisions()
          Return the bundle revisions for the referenced bundle.
 java.util.Map<java.security.cert.X509Certificate,java.util.List<java.security.cert.X509Certificate>> getSignerCertificates(int signersType)
          Return the certificates for the signers of this bundle and the certificate chains for those signers.
 int getStartLevel()
          Return the assigned start level value for the bundle.
 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.
 boolean isActivationPolicyUsed()
          Returns whether the bundle's autostart setting indicates that the activation policy declared in the bundle manifest must be used.
protected  boolean isActive()
          Return true if the bundle is starting or active.
protected  boolean isFragment()
           
 boolean isPersistentlyStarted()
          Returns whether the bundle's autostart setting indicates it must be started.
 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.
 void setStartLevel(int startlevel)
          Assign a start level value to the bundle.
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<java.lang.Object> 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<java.lang.Object> 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 final 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 final 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
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 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. BundleException types thrown by this method include: BundleException.START_TRANSIENT_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

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

Specified by:
stop in interface Bundle
Parameters:
options - The options for stopping this bundle. See Bundle.STOP_TRANSIENT. The Framework must ignore unrecognized options.
Throws:
BundleException - BundleException types thrown by this method include: BundleException.STATECHANGE_ERROR and BundleException.ACTIVATOR_ERROR.

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
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 this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.
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 remain exported until the FrameworkWiring.refreshBundles 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 Postconditions, no exceptions thrown Postconditions, when an exception is thrown

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 this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.
See Also:
Bundle.stop(), Bundle.start()

updateWorker

protected void updateWorker(java.security.PrivilegedExceptionAction<java.lang.Object> 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<java.lang.Object> 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<java.lang.String,java.lang.String> 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<java.lang.String,java.lang.String> 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(Bundle 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<Bundle>
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<java.lang.String> 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 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()

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<java.net.URL> 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 name space 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 no matching 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 attachment order. If this bundle is a fragment, then only matching entries in this fragment are returned.

getSignerCertificates

public java.util.Map<java.security.cert.X509Certificate,java.util.List<java.security.cert.X509Certificate>> 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.

adapt

public final <A> A adapt(java.lang.Class<A> adapterType)
Description copied from interface: Bundle
Adapt this bundle to the specified type.

Adapting this bundle to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this bundle cannot be adapted and null is returned.

Specified by:
adapt in interface Bundle
Type Parameters:
A - The type to which this bundle is to be adapted.
Parameters:
adapterType - Class object for the type to which this bundle is to be adapted.
Returns:
The object, of the specified type, to which this bundle has been adapted or null if this bundle cannot be adapted to the specified type.

getRevisions

public java.util.List<BundleRevision> getRevisions()
Description copied from interface: BundleRevisions
Return the bundle revisions for the referenced bundle.

The result is a list containing the current bundle revision, if there is one, and all in use bundle revisions. The list may also contain intermediate bundle revisions which are not in use.

The list is ordered in reverse chronological order such that the first item is the most recent bundle revision and last item is the oldest bundle revision.

Generally the list will have at least one bundle revision for the bundle: the current bundle revision. However, for an uninstalled bundle with no in use bundle revisions, the list may be empty.

Specified by:
getRevisions in interface BundleRevisions
Returns:
A list containing a snapshot of the BundleRevisions for the referenced bundle.

adapt0

protected <A> A adapt0(java.lang.Class<A> adapterType)

getDataFile

public java.io.File getDataFile(java.lang.String filename)
Description copied from interface: Bundle
Creates a File object for a file in the persistent storage area provided for this bundle by the Framework. This method will return null if the platform does not have file system support or this bundle is a fragment bundle.

A File object for the base directory of the persistent storage area provided for this bundle by the Framework can be obtained by calling this method with an empty string as filename.

If the Java Runtime Environment supports permissions, the Framework will ensure that this bundle has the java.io.FilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for this bundle.

Specified by:
getDataFile in interface Bundle
Parameters:
filename - A relative name to the file to be accessed.
Returns:
A File object that represents the requested file or null if the platform does not have file system support or this bundle is a fragment bundle.

getBundle

public Bundle getBundle()
Description copied from interface: BundleReference
Returns the Bundle object associated with this BundleReference.

Specified by:
getBundle in interface BundleReference
Returns:
The Bundle object associated with this BundleReference.

getStartLevel

public int getStartLevel()
Description copied from interface: BundleStartLevel
Return the assigned start level value for the bundle.

Specified by:
getStartLevel in interface BundleStartLevel
Returns:
The start level value of the bundle.
See Also:
BundleStartLevel.setStartLevel(int)

setStartLevel

public void setStartLevel(int startlevel)
Description copied from interface: BundleStartLevel
Assign a start level value to the bundle.

The bundle will be assigned the specified start level. The start level value assigned to the bundle will be persistently recorded by the Framework.

If the new start level for the bundle is lower than or equal to the active start level of the Framework and the bundle's autostart setting indicates this bundle must be started, the Framework will start the bundle as described in the Bundle.start(int) method using the Bundle.START_TRANSIENT option. The Bundle.START_ACTIVATION_POLICY option must also be used if BundleStartLevel.isActivationPolicyUsed() returns true. The actual starting of the bundle must occur asynchronously.

If the new start level for the bundle is higher than the active start level of the Framework, the Framework will stop the bundle as described in the Bundle.stop(int) method using the Bundle.STOP_TRANSIENT option. The actual stopping of the bundle must occur asynchronously.

Specified by:
setStartLevel in interface BundleStartLevel
Parameters:
startlevel - The new start level for the bundle.

isPersistentlyStarted

public boolean isPersistentlyStarted()
Description copied from interface: BundleStartLevel
Returns whether the bundle's autostart setting indicates it must be started.

The autostart setting of a bundle indicates whether the bundle is to be started when its start level is reached.

Specified by:
isPersistentlyStarted in interface BundleStartLevel
Returns:
true if the autostart setting of the bundle indicates it is to be started. false otherwise.
See Also:
Bundle.START_TRANSIENT

isActivationPolicyUsed

public boolean isActivationPolicyUsed()
Description copied from interface: BundleStartLevel
Returns whether the bundle's autostart setting indicates that the activation policy declared in the bundle manifest must be used.

The autostart setting of a bundle indicates whether the bundle's declared activation policy is to be used when the bundle is started.

Specified by:
isActivationPolicyUsed in interface BundleStartLevel
Returns:
true if the bundle's autostart setting indicates the activation policy declared in the manifest must be used. false if the bundle must be eagerly activated.
See Also:
Bundle.START_ACTIVATION_POLICY
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2007-2012 FuseSource, Corp.. All Rights Reserved.