Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.osgi.framework
Interface BundleContext

public interface BundleContext

A bundle's execution context within the Framework. The context is used to grant access to other methods so that this bundle can interact with the Framework.

`BundleContext` methods allow a bundle to:

- Subscribe to events published by the Framework.
- Register service objects with the Framework service registry.
- Retrieve `ServiceReferences` from the Framework service registry.
- Get and release service objects for a referenced service.
- Install new bundles in the Framework.
- Get the list of bundles installed in the Framework.
- Get the `Bundle`object for a bundle.
- Create `File` objects for files in a persistent storage area provided for the bundle by the Framework.

A `BundleContext` object will be created and provided to this bundle when it is started using the `BundleActivator.start(org.osgi.framework.BundleContext)`method. The same `BundleContext` object will be passed to this bundle when it is stopped using the `BundleActivator.stop(org.osgi.framework.BundleContext)`method. `BundleContext` is generally for the private use of this bundle and is not meant to be shared with other bundles in the OSGi environment. `BundleContext` is used when resolving `ServiceListener` and `EventListener` objects.

The `BundleContext` object is only valid during an execution instance of this bundle; that is, during the period from when this bundle is called by `BundleActivator.start` until after this bundle is called and returns from `BundleActivator.stop` (or if `BundleActivator.start` terminates with an exception). If the `BundleContext` object is used subsequently, an `IllegalStateException` must be thrown. When this bundle is restarted, a new `BundleContext` object must be created.

The Framework is the only entity that can create `BundleContext` objects and they are only valid within the Framework that created them.

Method Summary
`void` | `addBundleListener(BundleListener listener)` Adds the specified `BundleListener` object to this context bundle's list of listeners if not already present.
`void` | `addFrameworkListener(FrameworkListener listener)` Adds the specified `FrameworkListener` object to this context bundle's list of listeners if not already present.
`void` | `addServiceListener(ServiceListener listener)` Adds the specified `ServiceListener` object to this context bundle's list of listeners.
`void` | `addServiceListener(ServiceListener listener, java.lang.String filter)` Adds the specified `ServiceListener` object with the specified `filter` to this context bundle's list of listeners.
`Filter` | `createFilter(java.lang.String filter)` Creates a `Filter` object.
`Bundle` | `getBundle()` Returns the `Bundle` object for this context bundle.
`Bundle` | `getBundle(long id)` Returns the bundle with the specified identifier.
`Bundle[]` | `getBundles()` Returns a list of all installed bundles.
`java.io.File` | `getDataFile(java.lang.String filename)` Creates a `File` object for a file in the persistent storage area provided for the bundle by the Framework.
`java.lang.String` | `getProperty(java.lang.String key)` Returns the value of the specified property.
`java.lang.Object` | `getService(ServiceReference reference)` Returns the specified service object for a service.
`ServiceReference` | `getServiceReference(java.lang.String clazz)` Returns a `ServiceReference` object for a service that implements, and was registered under, the specified class.
`ServiceReference[]` | `getServiceReferences(java.lang.String clazz, java.lang.String filter)` Returns a list of `ServiceReference` objects.
`Bundle` | `installBundle(java.lang.String location)` Installs the bundle from the specified location string.
`Bundle` | `installBundle(java.lang.String location, java.io.InputStream input)` Installs the bundle from the specified `InputStream` object.
`ServiceRegistration` | `registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties)` Registers the specified service object with the specified properties under the specified class names into the Framework.
`ServiceRegistration` | `registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties)` Registers the specified service object with the specified properties under the specified class name with the Framework.
`void` | `removeBundleListener(BundleListener listener)` Removes the specified `BundleListener` object from this context bundle's list of listeners.
`void` | `removeFrameworkListener(FrameworkListener listener)` Removes the specified `FrameworkListener` object from this context bundle's list of listeners.
`void` | `removeServiceListener(ServiceListener listener)` Removes the specified `ServiceListener` object from this context bundle's list of listeners.
`boolean` | `ungetService(ServiceReference reference)` Releases the service object referenced by the specified `ServiceReference` object.

Method Detail

### getProperty

    public java.lang.String getProperty(java.lang.String key)

  Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns `null` if the property is not found.

  The Framework defines the following standard property keys:

  - `Constants.FRAMEWORK_VERSION` - The OSGi Framework version.
  - `Constants.FRAMEWORK_VENDOR` - The Framework implementation vendor.
  - `Constants.FRAMEWORK_LANGUAGE` - The language being used. See ISO 639 for possible values.
  - `Constants.FRAMEWORK_OS_NAME` - The host computer operating system.
  - `Constants.FRAMEWORK_OS_VERSION` - The host computer operating system version number.
  - `Constants.FRAMEWORK_PROCESSOR` - The host computer processor name.

  All bundles must have permission to read these properties.

  Note: The last four standard properties are used by the `Constants.BUNDLE_NATIVECODE` `Manifest` header's matching algorithm for selecting native language code.

  Parameters:
    `key` - The name of the requested property.
  Returns:
    The value of the requested property, or `null` if the property is undefined.
  Throws:
    `java.lang.SecurityException` - If the caller does not have the appropriate `PropertyPermission` to read the property, and the Java Runtime Environment supports permissions.

### getBundle

    public Bundle getBundle()

  Returns the `Bundle` object for this context bundle.

  The context bundle is defined as the bundle that was assigned this `BundleContext` in its `BundleActivator`.

  Returns:
    The context bundle's `Bundle` object.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.

### installBundle

    public Bundle installBundle(java.lang.String location)
                         throws BundleException

  Installs the bundle from the specified location string. A bundle is obtained from `location` as interpreted by the Framework in an implementation dependent manner.

  Every installed bundle is uniquely identified by its location string, typically in the form of a URL.

  The following steps are required to install a bundle:

  1. If a bundle containing the same location string is already installed, the `Bundle` object for that bundle is returned.
  2. The bundle's content is read from the location string. If this fails, a `BundleException`is thrown.
  3. The bundle's `Bundle-NativeCode` dependencies are resolved. If this fails, a `BundleException` is thrown.
  4. The bundle's associated resources are allocated. The associated resources minimally consist of a unique identifier, and a persistent storage area if the platform has file system support. If this step fails, a `BundleException` is thrown.
  5. If the bundle has declared an Bundle-RequiredExecutionEnvironment header, then the listed execution environments must be verified against the installed execution environments. If they are not all present, a `BundleException` must be thrown.
  6. The bundle's state is set to `INSTALLED`.
  7. A bundle event of type `BundleEvent.INSTALLED`is broadcast.
  8. The `Bundle` object for the newly installed bundle is returned.
  Postconditions, no exceptions thrown
  - `getState()` in {`INSTALLED`}, `RESOLVED`}.
  - Bundle has a unique ID.
  Postconditions, when an exception is thrown
  - Bundle is not installed and no trace of the bundle exists.
  Parameters:
    `location` - The location identifier of the bundle to install.
  Returns:
    The `Bundle` object of the installed bundle.
  Throws:
    `BundleException` - If the installation failed.
    `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission`, and the Java Runtime Environment supports permissions.

### installBundle

    public Bundle installBundle(java.lang.String location,
                                java.io.InputStream input)
                         throws BundleException

  Installs the bundle from the specified `InputStream` object.

  This method performs all of the steps listed in `BundleContext.installBundle(String location)`, except that the bundle's content will be read from the `InputStream` object. The location identifier string specified will be used as the identity of the bundle.

  This method must always close the `InputStream` object, even if an exception is thrown.

  Parameters:
    `location` - The location identifier of the bundle to install.
    `in` - The `InputStream` object from which this bundle will be read.
  Returns:
    The `Bundle` object of the installed bundle.
  Throws:
    `BundleException` - If the provided stream cannot be read or the installation failed.
    `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission`, and the Java Runtime Environment supports permissions.
  See Also:
    `installBundle(java.lang.String)`

### getBundle

    public Bundle getBundle(long id)

  Returns the bundle with the specified identifier.
  Parameters:
    `id` - The identifier of the bundle to retrieve.
  Returns:
    A `Bundle` object, or `null` if the identifier does not match any installed bundle.

### getBundles

    public Bundle[] getBundles()

  Returns a list of all installed bundles.

  This method returns a list of all bundles installed in the OSGi environment at the time of the call to this method. However, as the Framework is a very dynamic environment, bundles can be installed or uninstalled at anytime.

  Returns:
    An array of `Bundle` objects; one object per installed bundle.

### addServiceListener

    public void addServiceListener(ServiceListener listener,
                                   java.lang.String filter)
                            throws InvalidSyntaxException

  Adds the specified `ServiceListener` object with the specified `filter` to this context bundle's list of listeners.

  See `getBundle()`for a definition of context bundle, and `Filter`for a description of the filter syntax. `ServiceListener` objects are notified when a service has a lifecycle state change.

  If this context bundle's list of listeners already contains a listener `l` such that `(l==listener)`, this method replaces that listener's filter (which may be `null`) with the specified one (which may be `null`).

  The listener is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the `Constants.OBJECTCLASS`property. If `filter` is `null`, all services are considered to match the filter.

  When using a `filter`, it is possible that the `ServiceEvent`s for the complete life cycle of a service will not be delivered to the listener. For example, if the `filter` only matches when the property `x` has the value `1`, the listener will not be called if the service is registered with the property `x` not set to the value `1`. Subsequently, when the service is modified setting property `x` to the value `1`, the filter will match and the listener will be called with a `ServiceEvent` of type `MODIFIED`. Thus, the listener will not be called with a `ServiceEvent` of type `REGISTERED`.

  If the Java Runtime Environment supports permissions, the `ServiceListener` object will be notified of a service event only if the bundle that is registering it has the `ServicePermission` to get the service using at least one of the named classes the service was registered under.

  Parameters:
    `listener` - The `ServiceListener` object to be added.
    `filter` - The filter criteria.
  Throws:
    `InvalidSyntaxException` - If `filter` contains an invalid filter string which cannot be parsed.
    `java.lang.IllegalStateException` - If this context bundle has stopped.
  See Also:
    `ServiceEvent`, `ServiceListener`, `ServicePermission`

### addServiceListener

    public void addServiceListener(ServiceListener listener)

  Adds the specified `ServiceListener` object to this context bundle's list of listeners.

  This method is the same as calling `BundleContext.addServiceListener(ServiceListener listener, String filter)` with `filter` set to `null`.

  Parameters:
    `listener` - The `ServiceListener` object to be added.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.
  See Also:
    `addServiceListener(ServiceListener, String)`

### removeServiceListener

    public void removeServiceListener(ServiceListener listener)

  Removes the specified `ServiceListener` object from this context bundle's list of listeners. See `getBundle()`for a definition of context bundle.

  If `listener` is not contained in this context bundle's list of listeners, this method does nothing.

  Parameters:
    `listener` - The `ServiceListener` to be removed.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.

### addBundleListener

    public void addBundleListener(BundleListener listener)

  Adds the specified `BundleListener` object to this context bundle's list of listeners if not already present. See `getBundle()`for a definition of context bundle. BundleListener objects are notified when a bundle has a lifecycle state change.

  If this context bundle's list of listeners already contains a listener `l` such that `(l==listener)`, this method does nothing.

  Parameters:
    `listener` - The `BundleListener` to be added.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.
  See Also:
    `BundleEvent`, `BundleListener`

### removeBundleListener

    public void removeBundleListener(BundleListener listener)

  Removes the specified `BundleListener` object from this context bundle's list of listeners. See `getBundle()`for a definition of context bundle.

  If `listener` is not contained in this context bundle's list of listeners, this method does nothing.

  Parameters:
    `listener` - The `BundleListener` object to be removed.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.

### addFrameworkListener

    public void addFrameworkListener(FrameworkListener listener)

  Adds the specified `FrameworkListener` object to this context bundle's list of listeners if not already present. See `getBundle()`for a definition of context bundle. FrameworkListeners are notified of general Framework events.

  If this context bundle's list of listeners already contains a listener `l` such that `(l==listener)`, this method does nothing.

  Parameters:
    `listener` - The `FrameworkListener` object to be added.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.
  See Also:
    `FrameworkEvent`, `FrameworkListener`

### removeFrameworkListener

    public void removeFrameworkListener(FrameworkListener listener)

  Removes the specified `FrameworkListener` object from this context bundle's list of listeners. See `getBundle()`for a definition of context bundle.

  If `listener` is not contained in this context bundle's list of listeners, this method does nothing.

  Parameters:
    `listener` - The `FrameworkListener` object to be removed.
  Throws:
    `java.lang.IllegalStateException` - If this context bundle has stopped.

### registerService

    public ServiceRegistration registerService(java.lang.String[] clazzes,
                                               java.lang.Object service,
                                               java.util.Dictionary properties)

  Registers the specified service object with the specified properties under the specified class names into the Framework. A `ServiceRegistration` object is returned. The `ServiceRegistration` object is for the private use of the bundle registering the service and should not be shared with other bundles. The registering bundle is defined to be the context bundle. See `getBundle()`for a definition of context bundle. Other bundles can locate the service by using either the `getServiceReferences(java.lang.String, java.lang.String)`or `getServiceReference(java.lang.String)`method.

  A bundle can register a service object that implements the `ServiceFactory`interface to have more flexibility in providing service objects to other bundles.

  The following steps are required to register a service:

  1. If `service` is not a `ServiceFactory`, an `IllegalArgumentException` is thrown if `service` is not an `instanceof` all the classes named.
  2. The Framework adds these service properties to the specified `Dictionary` (which may be `null`): a property named `Constants.SERVICE_ID`identifying the registration number of the service, and a property named `Constants.OBJECTCLASS`containing all the specified classes. If any of these properties have already been specified by the registering bundle, their values will be overwritten by the Framework.
  3. The service is added to the Framework service registry and may now be used by other bundles.
  4. A service event of type `ServiceEvent.REGISTERED`is synchronously sent.
  5. A `ServiceRegistration` object for this registration is returned.
  Parameters:
    `clazzes` - The class names under which the service can be located. The class names in this array will be stored in the service's properties under the key `Constants.OBJECTCLASS`.
    `service` - The service object or a `ServiceFactory` object.
    `properties` - The properties for this service. The keys in the properties object must all be `String` objects. See `Constants`for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties the `ServiceRegistration.setProperties(java.util.Dictionary)`method must be called. `properties` may be `null` if the service has no properties.
  Returns:
    A `ServiceRegistration` object for use by the bundle registering the service to update the service's properties or to unregister the service.
  Throws:
    `java.lang.IllegalArgumentException` - If one of the following is true:
    - `service` is `null`.
    - `service` is not a `ServiceFactory` object and is not an instance of all the named classes in `clazzes`.
    - `properties` contains case variants of the same key name.
    `java.lang.SecurityException` - If the caller does not have the `ServicePermission` to register the service for all the named classes and the Java Runtime Environment supports permissions.
    `java.lang.IllegalStateException` - If this context bundle was stopped.
  See Also:
    `ServiceRegistration`, `ServiceFactory`

### registerService

    public ServiceRegistration registerService(java.lang.String clazz,
                                               java.lang.Object service,
                                               java.util.Dictionary properties)

  Registers the specified service object with the specified properties under the specified class name with the Framework.

  This method is otherwise identical to `registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)`and is provided as a convenience when `service` will only be registered under a single class name. Note that even in this case the value of the service's `Constants.OBJECTCLASS`property will be an array of strings, rather than just a single string.

  See Also:
    `registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)`

### getServiceReferences

    public ServiceReference[] getServiceReferences(java.lang.String clazz,
                                                   java.lang.String filter)
                                            throws InvalidSyntaxException

  Returns a list of `ServiceReference` objects. This method returns a list of `ServiceReference` objects for services which implement and were registered under the specified class and match the specified filter criteria.

  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.

  `filter` is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See `Filter`for a description of the filter string syntax.

  If `filter` is `null`, all registered services are considered to match the filter.

  If `filter` cannot be parsed, an `InvalidSyntaxException`will be thrown with a human readable message where the filter became unparsable.

  The following steps are required to select a service:

  1. If the Java Runtime Environment supports permissions, the caller is checked for the `ServicePermission` to get the service with the specified class. If the caller does not have the correct permission, `null` is returned.
  2. If the filter string is not `null`, the filter string is parsed and the set of registered services which satisfy the filter is produced. If the filter string is `null`, then all registered services are considered to satisfy the filter.
  3. If `clazz` is not `null`, the set is further reduced to those services which are an `instanceof` and were registered under the specified class. The complete list of classes of which a service is an instance and which were specified when the service was registered is available from the service's `Constants.OBJECTCLASS`property.
  4. An array of `ServiceReference` to the selected services is returned.
  Parameters:
    `clazz` - The class name with which the service was registered, or `null` for all services.
    `filter` - The filter criteria.
  Returns:
    An array of `ServiceReference` objects, or `null` if no services are registered which satisfy the search.
  Throws:
    `InvalidSyntaxException` - If `filter` contains an invalid filter string which cannot be parsed.

### getServiceReference

    public ServiceReference getServiceReference(java.lang.String clazz)

  Returns a `ServiceReference` object for a service that implements, and was registered under, the specified class.

  This `ServiceReference` object 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.

  This method is the same as calling `getServiceReferences(java.lang.String, java.lang.String)`with a `null` filter string. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

  If multiple such services exist, the service with the highest ranking (as specified in its `Constants.SERVICE_RANKING`property) is returned.

  If there is a tie in ranking, the service with the lowest service ID (as specified in its `Constants.SERVICE_ID`property); that is, the service that was registered first is returned.

  Parameters:
    `clazz` - The class name with which the service was registered.
  Returns:
    A `ServiceReference` object, or `null` if no services are registered which implement the named class.
  See Also:
    `getServiceReferences(java.lang.String, java.lang.String)`

### getService

    public java.lang.Object getService(ServiceReference reference)

  Returns the specified service object for a service.

  A bundle's use of a service is tracked by the bundle's use count of that service. Each time a service's service object is returned by `getService(org.osgi.framework.ServiceReference)`the context bundle's use count for that service is incremented by one. Each time the service is released by `ungetService(org.osgi.framework.ServiceReference)`the context bundle's use count for that service is decremented by one.

  When a bundle's use count for a service drops to zero, the bundle should no longer use that service. See `getBundle()`for a definition of context bundle.

  This method will always return `null` when the service associated with this `reference` has been unregistered.

  The following steps are required to get the service object:

  1. If the service has been unregistered, `null` is returned.
  2. The context bundle's use count for this service is incremented by one.
  3. If the context bundle's use count for the service is currently one and the service was registered with an object implementing the `ServiceFactory` interface, the `ServiceFactory.getService(org.osgi.framework.Bundle, org.osgi.framework.ServiceRegistration)`method is called to create a service object for the context bundle. This service object is cached by the Framework. While the context bundle's use count for the service is greater than zero, subsequent calls to get the services's service object for the context bundle will return the cached service object.
     If the service object returned by the `ServiceFactory` object is not an `instanceof` all the classes named when the service was registered or the `ServiceFactory` object throws an exception, `null` is returned and a Framework event of type `FrameworkEvent.ERROR`is broadcast.
  4. The service object for the service is returned.
  Parameters:
    `reference` - A reference to the service.
  Returns:
    A service object for the service associated with `reference`, or `null` if the service is not registered or does not implement the classes under which it was registered in the case of a Service Factory.
  Throws:
    `java.lang.SecurityException` - If the caller does not have the `ServicePermission` to get the service using at least one of the named classes the service was registered under, and the Java Runtime Environment supports permissions.
    `java.lang.IllegalStateException` - If the context bundle has stopped.
  See Also:
    `ungetService(org.osgi.framework.ServiceReference)`, `ServiceFactory`

### ungetService

    public boolean ungetService(ServiceReference reference)

  Releases the service object referenced by the specified `ServiceReference` object. If the context bundle's use count for the service is zero, this method returns `false`. Otherwise, the context bundle's use count for the service is decremented by one. See `getBundle()`for a definition of context bundle.

  The service's service object should no longer be used and all references to it should be destroyed when a bundle's use count for the service drops to zero.

  The following steps are required to unget the service object:

  1. If the context bundle's use count for the service is zero or the service has been unregistered, `false` is returned.
  2. The context bundle's use count for this service is decremented by one.
  3. If the context bundle's use count for the service is currently zero and the service was registered with a `ServiceFactory` object, the `ServiceFactory.ungetService(org.osgi.framework.Bundle, org.osgi.framework.ServiceRegistration, java.lang.Object)`method is called to release the service object for the context bundle.
  4. `true` is returned.
  Parameters:
    `reference` - A reference to the service to be released.
  Returns:
    `false` if the context bundle's use count for the service is zero or if the service has been unregistered; `true` otherwise.
  Throws:
    `java.lang.IllegalStateException` - If the context bundle has stopped.
  See Also:
    `getService(org.osgi.framework.ServiceReference)`, `ServiceFactory`

### getDataFile

    public java.io.File getDataFile(java.lang.String filename)

  Creates a `File` object for a file in the persistent storage area provided for the bundle by the Framework. This method will return `null` if the platform does not have file system support.

  A `File` object for the base directory of the persistent storage area provided for the context bundle by the Framework can be obtained by calling this method with an empty string (" ") as `filename`. See `getBundle()`for a definition of context bundle.

  If the Java Runtime Environment supports permissions, the Framework will ensure that the bundle has the `java.io.FilePermission` with actions `read`, `write`, `delete` for all files (recursively) in the persistent storage area provided for the context 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.
  Throws:
    `java.lang.IllegalStateException` - If the context bundle has stopped.

### createFilter

    public Filter createFilter(java.lang.String filter)
                        throws InvalidSyntaxException

  Creates a `Filter` object. This `Filter` object may be used to match a `ServiceReference` object or a `Dictionary` object. See `Filter`for a description of the filter string syntax.

  If the filter cannot be parsed, an `InvalidSyntaxException`will be thrown with a human readable message where the filter became unparsable.

  Parameters:
    `filter` - The filter string.
  Returns:
    A `Filter` object encapsulating the filter string.
  Throws:
    `InvalidSyntaxException` - If `filter` contains an invalid filter string that cannot be parsed.
    `NullPointerException` - If `filter` is null.
  Since:
    1.1

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.