Class Bundle

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:

#UNINSTALLED #INSTALLED #RESOLVED #STARTING #STOPPING #ACTIVE

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 have active threads of execution 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.

Bundles have a natural ordering such that if two Bundles have the same #getBundleId() bundle id they are equal. A Bundle is less than another Bundle if it has a lower #getBundleId() bundle id and is greater if it has a higher bundle id.

Thread Safe

Author

$Id: 545299bc454bb01ef73a14693ffec76a13430eea $

Constructors

constructor

Methods

getBundleContext getBundleId getDataFile getEntry getEntryPaths getHeaders getLastModified getLocation getRegisteredServices getResource getResources getServicesInUse getState getSymbolicName getVersion

Constructors

constructor

Methods

getBundleContext

  • getBundleContext(): BundleContext

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

    Returns BundleContext

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

    Throws

    SecurityException If the caller does not have the appropriate AdminPermission[this,CONTEXT], and the Java Runtime Environment supports permissions.

    Since

    1.4

getBundleId

  • getBundleId(): number

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

    Returns number

    The unique identifier of this bundle.

getDataFile

  • getDataFile(filename): File

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

    Parameters

    • filename: string

      A relative name to the file to be accessed.

    Returns File

    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.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    Since

    1.6

getEntry

  • getEntry(path): URL

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

    Parameters

    • path: string

      The path name of the entry.

    Returns URL

    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.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    Since

    1.3

getEntryPaths

  • getEntryPaths(path): Enumeration<string>

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

    Parameters

    • path: string

      The path name for which to return entry paths.

    Returns Enumeration<string>

    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.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    Since

    1.3

getHeaders

  • getHeaders(): Dictionary<string, string>

  • 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. If no localization is found for a header value, the header value without the leading "%" is returned.

    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.

    Returns Dictionary<string, string>

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

    Throws

    SecurityException If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

    See

    Constants#BUNDLE_LOCALIZATION

  • getHeaders(locale): Dictionary<string, string>

  • 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. If no localization is found for a header value, the header value without the leading "%" is 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.

    Parameters

    • locale: string

      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 Dictionary<string, string>

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

    Throws

    SecurityException If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

    See

    • #getHeaders()
    • Constants#BUNDLE_LOCALIZATION

    Since

    1.3

getLastModified

  • getLastModified(): number

  • 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 UTC.

    Returns number

    The time when this bundle was last modified.

    Since

    1.3

getLocation

  • getLocation(): string

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

    Returns string

    The string representation of this bundle's location identifier.

    Throws

    SecurityException If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

getRegisteredServices

  • getRegisteredServices(): ServiceReference<any>[]

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

    Returns ServiceReference<any>[]

    An array of ServiceReference objects or null.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    See

    • ServiceRegistration
    • ServiceReference
    • ServicePermission

getResource

  • getResource(name): URL

  • Find the specified resource from this bundle's class loader.

    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.

    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.

    Parameters

    • name: string

      The name of the resource. See ClassLoader.getResource for a description of the format of a resource name.

    Returns URL

    A URL to the named resource, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    See

    • #getEntry(String)
    • #findEntries(String, String, boolean)

    Since

    1.1

getResources

  • getResources(name): Enumeration<URL>

  • Find the specified resources from this bundle's class loader.

    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.

    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.

    Parameters

    • name: string

      The name of the resource. See ClassLoader.getResources for a description of the format of a resource name.

    Returns Enumeration<URL>

    An enumeration of URLs to the named resources, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    Throws

    IOException If there is an I/O error.

    Since

    1.3

getServicesInUse

  • getServicesInUse(): ServiceReference<any>[]

  • 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 it has any unreleased service objects.

    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.

    Returns ServiceReference<any>[]

    An array of ServiceReference objects or null.

    Throws

    IllegalStateException If this bundle has been uninstalled.

    See

    • ServiceReference
    • ServicePermission

getState

getSymbolicName

  • getSymbolicName(): string

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

    Returns string

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

    Since

    1.3

getVersion

  • getVersion(): Version

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

    Returns Version

    The version of this bundle.

    Since

    1.5

Settings

Member Visibility

Theme

On This Page

constructorgetBundleContextgetBundleIdgetDataFilegetEntrygetEntryPathsgetHeadersgetLastModifiedgetLocationgetRegisteredServicesgetResourcegetResourcesgetServicesInUsegetStategetSymbolicNamegetVersion