Save This Page
Home » db-derby-10.5.3.0 » org.osgi.framework » [javadoc | source]
org.osgi.framework
public interface: Bundle [javadoc | source] An installed bundle in the Framework.

A Bundle object is the access point to define the lifecycle of an installed bundle. Each bundle installed in the OSGi environment must have an associated Bundle object.

A bundle must have a unique identity, a long, chosen by the Framework. This identity must not change during the lifecycle of a bundle, even when the bundle is updated. Uninstalling and then reinstalling the bundle must create a new unique identity.

A bundle can be in one of six states:

Values assigned to these states have no specified ordering; they represent bit values that may be ORed together to determine if a bundle is in one of the valid states.

A bundle should only execute code when its state is one of STARTING,ACTIVE, or STOPPING. An UNINSTALLED bundle can not be set to another state; it is a zombie and can only be reached because references are kept somewhere.

The Framework is the only entity that is allowed to create Bundle objects, and these objects are only valid within the Framework that created them.

Field Summary
public static final  int UNINSTALLED    The bundle is uninstalled and may not be used.

The UNINSTALLED state is only visible after a bundle is uninstalled; the bundle is in an unusable state but references to the Bundle object may still be available and used for introspection.

The value of UNINSTALLED is 0x00000001. 

public static final  int INSTALLED    The bundle is installed but not yet resolved.

A bundle is in the INSTALLED state when it has been installed in the Framework but is not or cannot be resolved.

This state is visible if the bundle's code dependencies are not resolved. The Framework may attempt to resolve an INSTALLED bundle's code dependencies and move the bundle to the RESOLVED state.

The value of INSTALLED is 0x00000002. 

public static final  int RESOLVED    The bundle is resolved and is able to be started.

A bundle is in the RESOLVED state when the Framework has successfully resolved the bundle's code dependencies. These dependencies include:

Note that the bundle is not active yet. A bundle must be put in the RESOLVED state before it can be started. The Framework may attempt to resolve a bundle at any time.

The value of RESOLVED is 0x00000004. 

public static final  int STARTING    The bundle is in the process of starting.

A bundle is in the STARTING state when its start method is active. A bundle must be in this state when the bundle's BundleActivator#start is called. If the BundleActivator.start method completes without exception, then the bundle has successfully started and must move to the ACTIVE state.

If the bundle has a lazy activation policy , then the bundle may remain in this state for some time until the activation is triggered.

The value of STARTING is 0x00000008. 

public static final  int STOPPING    The bundle is in the process of stopping.

A bundle is in the STOPPING state when its stop method is active. A bundle must be in this state when the bundle's BundleActivator#stop method is called. When the BundleActivator.stop method completes the bundle is stopped and must move to the RESOLVED state.

The value of STOPPING is 0x00000010. 

public static final  int ACTIVE    The bundle is now running.

A bundle is in the ACTIVE state when it has been successfully started and activated.

The value of ACTIVE is 0x00000020. 

public static final  int START_TRANSIENT    The bundle start operation is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling #start(int) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

 
public static final  int START_ACTIVATION_POLICY    The bundle start operation must activate the bundle according to the bundle's declared activation policy .

This bit may be set when calling #start(int) to notify the framework that the bundle must be activated using the bundle's declared activation policy.

    Also see:
    Constants#BUNDLE_ACTIVATIONPOLICY
    start(int)
    since: 1.4 -
 
public static final  int STOP_TRANSIENT    The bundle stop is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling #stop(int) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

 
Method from org.osgi.framework.Bundle Summary:
findEntries,   getBundleContext,   getBundleId,   getEntry,   getEntryPaths,   getHeaders,   getHeaders,   getLastModified,   getLocation,   getRegisteredServices,   getResource,   getResources,   getServicesInUse,   getState,   getSymbolicName,   hasPermission,   loadClass,   start,   start,   stop,   stop,   uninstall,   update,   update
Method from org.osgi.framework.Bundle Detail:
 public Enumeration findEntries(String path,
    String filePattern,
    boolean recurse)
    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();
    
 public BundleContext getBundleContext()
    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 #STARTING , #ACTIVE , or #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.

 public long getBundleId()
    Returns this bundle's unique identifier. This bundle is assigned a unique identifier by the Framework when it was installed in the OSGi environment.

    A bundle's unique identifier has the following attributes:

    • Is unique and persistent.
    • Is a long.
    • Its value is not reused for another bundle, even after a bundle is uninstalled.
    • Does not change while a bundle remains installed.
    • Does not change when a bundle is updated.

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

 public URL getEntry(String path)
    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.

 public Enumeration getEntryPaths(String path)
    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 "/".

 public Dictionary getHeaders()
    Returns this bundle's Manifest headers and values. This method returns all the Manifest headers and values from the main section of this 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 must operate on header names in a case-insensitive manner. If a Manifest header value starts with "%", it must be localized according to the default 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 must continue to return Manifest header information while this bundle is in the UNINSTALLED state.

 public Dictionary getHeaders(String locale)
    Returns this bundle's Manifest headers and values localized to the specified locale.

    This method performs the same function as Bundle.getHeaders() except the manifest header values are localized to the specified locale.

    If a Manifest header value starts with "%", it must be localized according to the specified locale. If a locale is specified and cannot be found, then the header values must be returned using the default locale. Localizations are searched for in the following order:

      bn + "_" + Ls + "_" + Cs + "_" + Vs
      bn + "_" + Ls + "_" + Cs
      bn + "_" + Ls
      bn + "_" + Ld + "_" + Cd + "_" + Vd
      bn + "_" + Ld + "_" + Cd
      bn + "_" + Ld
        bn
    
    Where bn is this bundle's localization basename, Ls, Cs and Vs are the specified locale (language, country, variant) and Ld, Cd and Vd are the default locale (language, country, variant). If null is specified as the locale string, the header values must be localized using the default locale. If the empty string ("") is specified as the locale string, the header values must not be localized and the raw (unlocalized) header values, including any leading "%", must be returned.

    This method must continue to return Manifest header information while this bundle is in the UNINSTALLED state, however the header values must only be available in the raw and default locale values.

 public long getLastModified()
    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.

 public String getLocation()
    Returns this bundle's location identifier.

    The location identifier is the location passed to BundleContext.installBundle when a bundle is installed. The location identifier does not change while this bundle remains installed, even if this bundle is updated.

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

 public ServiceReference[] getRegisteredServices()
    Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.

    If the Java runtime supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

    The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

 public URL getResource(String name)
    Find the specified resource from this bundle. This bundle's class loader is called to search for the specified resource. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resource. If this bundle cannot be resolved, then only this bundle must be searched for the specified resource. Imported packages cannot be searched when this bundle has not been resolved. If this bundle is a fragment bundle then null is returned.
 public Enumeration getResources(String name) throws IOException
    Find the specified resources from this bundle. This bundle's class loader is called to search for the specified resources. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resources. If this bundle cannot be resolved, then only this bundle must be searched for the specified resources. Imported packages cannot be searched when a bundle has not been resolved. If this bundle is a fragment bundle then null is returned.
 public ServiceReference[] getServicesInUse()
    Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services. A bundle is considered to be using a service if its use count for that service is greater than zero.

    If the Java Runtime Environment supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

    The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

 public int getState()
    Returns this bundle's current state.

    A bundle can be in only one state at any time.

 public String getSymbolicName()
    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.

 public boolean hasPermission(Object permission)
    Determines if this bundle has the specified permissions.

    If the Java Runtime Environment does not support permissions, this method always returns true.

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

    If the Java Runtime Environment does support permissions, this bundle and all its resources including embedded JAR files, belong to the same java.security.ProtectionDomain; that is, they must share the same set of permissions.

 public Class loadClass(String name) throws ClassNotFoundException
    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.

 public  void start() throws BundleException
    Starts this bundle with no options.

    This method calls start(0).

 public  void start(int options) throws BundleException
    Starts this bundle.

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

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

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

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

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

    1. If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be started.
    2. If this bundle's state is ACTIVE then this method returns immediately.
    3. If the #START_TRANSIENT option is not set then set this bundle's autostart setting to Started with declared activation if the #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 #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 method of this bundle's BundleActivator, if one is specified, is called. If the BundleActivator is invalid or throws an exception then:
      • This bundle's state is set to STOPPING.
      • A bundle event of type BundleEvent#STOPPING is fired.
      • Any services registered by this bundle must be unregistered.
      • Any services used by this bundle must be released.
      • Any listeners registered by this bundle must be removed.
      • This bundle's state is set to RESOLVED.
      • A bundle event of type BundleEvent#STOPPED is fired.
      • A BundleException is then thrown.
    9. If this bundle's state is UNINSTALLED, because this bundle was uninstalled while the BundleActivator.start method was running, a BundleException is thrown.
    10. This bundle's state is set to ACTIVE.
    11. A bundle event of type BundleEvent#STARTED is fired.
    Preconditions
    • getState() in {INSTALLED, RESOLVED} or {INSTALLED, RESOLVED, STARTING} if this bundle has a lazy activation policy.
    Postconditions, no exceptions thrown
    • Bundle autostart setting is modified unless the #START_TRANSIENT option was set.
    • getState() in {ACTIVE} unless the lazy activation policy was used.
    • BundleActivator.start() has been called and did not throw an exception unless the lazy activation policy was used.
    Postconditions, when an exception is thrown
    • Depending on when the exception occurred, bundle autostart setting is modified unless the #START_TRANSIENT option was set.
    • getState() not in {STARTING, ACTIVE}.
 public  void stop() throws BundleException
    Stops this bundle with no options.

    This method calls stop(0).

 public  void stop(int options) throws BundleException
    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 #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 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
    • getState() in {ACTIVE}.
    Postconditions, no exceptions thrown
    • Bundle autostart setting is modified unless the #STOP_TRANSIENT option was set.
    • getState() not in {ACTIVE, STOPPING}.
    • BundleActivator.stop has been called and did not throw an exception.
    Postconditions, when an exception is thrown
    • Bundle autostart setting is modified unless the #STOP_TRANSIENT option was set.
 public  void uninstall() throws BundleException
    Uninstalls this bundle.

    This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then puts this bundle into the UNINSTALLED state. The Framework must remove any resources related to this bundle that it is able to remove.

    If this bundle has exported any packages, the Framework must continue to make these packages available to their importing bundles until the PackageAdmin.refreshPackages method has been called or the Framework is relaunched.

    The following steps are required to uninstall 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, a Framework event of type FrameworkEvent#ERROR is fired containing the exception.
    3. This bundle's state is set to UNINSTALLED.
    4. A bundle event of type BundleEvent#UNINSTALLED is fired.
    5. This bundle and any persistent storage area provided for this bundle by the Framework are removed.
    Preconditions
    • getState() not in {UNINSTALLED}.
    Postconditions, no exceptions thrown
    • getState() in {UNINSTALLED}.
    • This bundle has been uninstalled.
    Postconditions, when an exception is thrown
    • getState() not in {UNINSTALLED}.
    • This Bundle has not been uninstalled.
 public  void update() throws BundleException
    Updates this bundle.

    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, these packages must not be updated. Instead, the previous package version must remain exported until the PackageAdmin.refreshPackages method has been has been called or the Framework is relaunched.

    The following steps are required to update a bundle:

    1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.
    2. If this bundle's state is ACTIVE, STARTING or STOPPING, this bundle is stopped as described in the Bundle.stop method. If Bundle.stop throws an exception, the exception is rethrown terminating the update.
    3. The download location of the new version of this bundle is determined from either this bundle's Constants#BUNDLE_UPDATELOCATION Manifest header (if available) or this bundle's original location.
    4. The location is interpreted in an implementation dependent manner, typically as a URL, and the new version of this bundle is obtained from this location.
    5. The new version of this bundle is installed. If the Framework is unable to install the new 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.
    6. If this bundle has declared an Bundle-RequiredExecutionEnvironment header, then the listed execution environments must be verified against the installed execution environments. If they do not all match, the original version of this bundle must be restored and a BundleException must be thrown after completion of the remaining steps.
    7. This bundle's state is set to INSTALLED.
    8. If the new version of this bundle was successfully installed, a bundle event of type BundleEvent#UPDATED is fired.
    9. If this bundle's state was originally ACTIVE, the updated bundle is started as described in the Bundle.start method. If Bundle.start throws an exception, a Framework event of type FrameworkEvent#ERROR is fired containing the exception.
    Preconditions
    • getState() not in {UNINSTALLED}.
    Postconditions, no exceptions thrown
    • getState() in {INSTALLED, RESOLVED,ACTIVE}.
    • This bundle has been updated.
    Postconditions, when an exception is thrown
    • getState() in {INSTALLED, RESOLVED,ACTIVE}.
    • Original bundle is still used; no update occurred.
 public  void update(InputStream in) throws BundleException
    Updates this bundle from an InputStream.

    This method performs all the steps listed in Bundle.update(), except the new version of this bundle must be read from the supplied InputStream, rather than a URL.

    This method must always close the InputStream when it is done, even if an exception is thrown.