BundleContext
Date: 2016-06-24

org.osgi.framework

## Interface BundleContext

- All Superinterfaces:
    BundleReference

      @ProviderType
      public interface BundleContext
      extends BundleReference

  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 for a bundle when the bundle is started. The `Bundle` object associated with a `BundleContext` object is called the context bundle.

  The `BundleContext` object will be passed to the `BundleActivator.start(BundleContext)` method during activation of the context bundle. The same `BundleContext` object will be passed to the `BundleActivator.stop(BundleContext)` method when the context bundle is stopped. A `BundleContext` object is generally for the private use of its associated bundle and is not meant to be shared with other bundles in the OSGi environment.

  The `BundleContext` object is only valid during the execution of its context bundle; that is, during the period from when the context bundle is in the `STARTING`, `STOPPING`, and `ACTIVE` bundle states. However, the `BundleContext` object becomes invalid after `BundleActivator.stop(BundleContext)` returns (if the bundle has a Bundle Activator). The `BundleContext` object becomes invalid before disposing of any remaining registered services and releasing any remaining services in use. Since those activities can result in other bundles being called (for example, `ServiceListener`s for `ServiceEvent.UNREGISTERING` events and `ServiceFactory`s for unget operations), those other bundles can observe the stopping bundle in the `STOPPING` state but with an invalid `BundleContext` object. If the `BundleContext` object is used after it has become invalid, an `IllegalStateException` must be thrown. The `BundleContext` object must never be reused after its context bundle is stopped.

  Two `BundleContext` objects are equal if they both refer to the same execution context of a bundle. The Framework is the only entity that can create `BundleContext` objects and they are only valid within the Framework that created them.

  A `Bundle` can be `adapted` to its `BundleContext`. In order for this to succeed, the caller must have the appropriate `AdminPermission[bundle,CONTEXT]` if the Java Runtime Environment supports permissions.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBundleListener(BundleListener listener)` Adds the specified `BundleListener` object to the context bundle's list of listeners if not already present.
    `void` | `addFrameworkListener(FrameworkListener listener)` Adds the specified `FrameworkListener` object to the context bundle's list of listeners if not already present.
    `void` | `addServiceListener(ServiceListener listener)` Adds the specified `ServiceListener` object to the context bundle's list of listeners.
    `void` | `addServiceListener(ServiceListener listener, java.lang.String filter)` Adds the specified `ServiceListener` object with the specified `filter` to the context bundle's list of listeners.
    `Filter` | `createFilter(java.lang.String filter)` Creates a `Filter` object.
    `ServiceReference<?>[]` | `getAllServiceReferences(java.lang.String clazz, java.lang.String filter)` Returns an array of `ServiceReference` objects.
    `Bundle` | `getBundle()` Returns the `Bundle` object associated with this `BundleContext`.
    `Bundle` | `getBundle(long id)` Returns the bundle with the specified identifier.
    `Bundle` | `getBundle(java.lang.String location)` Returns the bundle with the specified location.
    `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.
    `<S> S` | `getService(ServiceReference<S> reference)` Returns the service object for the service referenced by the specified `ServiceReference` object.
    `<S> ServiceObjects<S>` | `getServiceObjects(ServiceReference<S> reference)` Returns the `ServiceObjects` object for the service referenced by the specified `ServiceReference` object.
    `<S> ServiceReference<S>` | `getServiceReference(java.lang.Class<S> clazz)` Returns a `ServiceReference` object for a service that implements and was registered under the name of the specified class.
    `ServiceReference<?>` | `getServiceReference(java.lang.String clazz)` Returns a `ServiceReference` object for a service that implements and was registered under the specified class.
    `<S> java.util.Collection<ServiceReference<S>>` | `getServiceReferences(java.lang.Class<S> clazz, java.lang.String filter)` Returns a collection of `ServiceReference` objects.
    `ServiceReference<?>[]` | `getServiceReferences(java.lang.String clazz, java.lang.String filter)` Returns an array of `ServiceReference` objects.
    `Bundle` | `installBundle(java.lang.String location)` Installs a bundle from the specified `location` identifier.
    `Bundle` | `installBundle(java.lang.String location, java.io.InputStream input)` Installs a bundle from the specified `InputStream` object.
    `<S> ServiceRegistration<S>` | `registerService(java.lang.Class<S> clazz, S service, java.util.Dictionary<java.lang.String,?> properties)` Registers the specified service object with the specified properties under the name of the specified class with the Framework.
    `<S> ServiceRegistration<S>` | `registerService(java.lang.Class<S> clazz, ServiceFactory<S> factory, java.util.Dictionary<java.lang.String,?> properties)` Registers the specified service factory object with the specified properties under the name of the specified class with the Framework.
    `ServiceRegistration<?>` | `registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary<java.lang.String,?> 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<java.lang.String,?> 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 the context bundle's list of listeners.
    `void` | `removeFrameworkListener(FrameworkListener listener)` Removes the specified `FrameworkListener` object from the context bundle's list of listeners.
    `void` | `removeServiceListener(ServiceListener listener)` Removes the specified `ServiceListener` object from the context bundle's list of listeners.
    `boolean` | `ungetService(ServiceReference<?> reference)` Releases the service object for the service referenced by the specified `ServiceReference` object.

- - ### Method Detail

    - #### getProperty

          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.

      All bundles must have permission to read properties whose names start with "org.osgi.".

      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

          Bundle getBundle()

      Returns the `Bundle` object associated with this `BundleContext`. This bundle is called the context bundle.
      Specified by:
        `getBundle` in interface `BundleReference`
      Returns:
        The `Bundle` object associated with this `BundleContext`.
      Throws:
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.

    - #### installBundle

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

      Installs a bundle from the specified `InputStream` object.

      If the specified `InputStream` is `null`, the Framework must create the `InputStream` from which to read the bundle by interpreting, in an implementation dependent manner, the specified `location`.

      The specified `location` identifier will be used as the identity of the bundle. Every installed bundle is uniquely identified by its location identifier which is typically in the form of a URL.

      The following steps are required to install a bundle:

      1. If a bundle containing the same location identifier is already installed, the `Bundle` object for that bundle is returned.
      2. The bundle's content is read from the input stream. If this fails, a `BundleException` is thrown.
      3. 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.
      4. The bundle's state is set to `INSTALLED`.
      5. A bundle event of type `BundleEvent.INSTALLED` is fired.
      6. The `Bundle` object for the newly or previously 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. If there was an existing bundle for the specified location, then that bundle must still be in the state it was prior to calling this method.
      Parameters:
        `location` - The location identifier of the bundle to install.
        `input` - The `InputStream` object from which this bundle will be read or `null` to indicate the Framework must create the input stream from the specified location identifier. The input stream must always be closed when this method completes, even if an exception is thrown.
      Returns:
        The `Bundle` object of the installed bundle.
      Throws:
        `BundleException` - If the installation failed. BundleException types thrown by this method include: `BundleException.READ_ERROR` , `BundleException.DUPLICATE_BUNDLE_ERROR`, `BundleException.MANIFEST_ERROR`, and `BundleException.REJECTED_BY_HOOK`.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[installed bundle,LIFECYCLE]`, and the Java Runtime Environment supports permissions.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.

    - #### installBundle

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

      Installs a bundle from the specified `location` identifier.

      This method performs the same function as calling `installBundle(String,InputStream)` with the specified `location` identifier and a `null` InputStream.

      Parameters:
        `location` - The location identifier of the bundle to install.
      Returns:
        The `Bundle` object of the installed bundle.
      Throws:
        `BundleException` - If the installation failed. BundleException types thrown by this method include: `BundleException.READ_ERROR` , `BundleException.DUPLICATE_BUNDLE_ERROR`, `BundleException.MANIFEST_ERROR`, and `BundleException.REJECTED_BY_HOOK`.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[installed bundle,LIFECYCLE]`, and the Java Runtime Environment supports permissions.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      See Also:
        `installBundle(String, InputStream)`

    - #### getBundle

          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

          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, since 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

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

      Adds the specified `ServiceListener` object with the specified `filter` to the context bundle's list of listeners. See `Filter` for a description of the filter syntax. `ServiceListener` objects are notified when a service has a lifecycle state change.

      If the context bundle's list of listeners already contains a listener `l` such that `(l==listener)`, then 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 lifecycle 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 that cannot be parsed.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      See Also:
        `ServiceEvent`, `ServiceListener`, `ServicePermission`

    - #### addServiceListener

          void addServiceListener(ServiceListener listener)

      Adds the specified `ServiceListener` object to the 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 BundleContext is no longer valid.
      See Also:
        `addServiceListener(ServiceListener, String)`

    - #### removeServiceListener

          void removeServiceListener(ServiceListener listener)

      Removes the specified `ServiceListener` object from the context bundle's list of listeners.

      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 BundleContext is no longer valid.

    - #### addBundleListener

          void addBundleListener(BundleListener listener)

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

      If the 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 BundleContext is no longer valid.
        `java.lang.SecurityException` - If listener is a `SynchronousBundleListener` and the caller does not have the appropriate `AdminPermission[context bundle,LISTENER]`, and the Java Runtime Environment supports permissions.
      See Also:
        `BundleEvent`, `BundleListener`

    - #### removeBundleListener

          void removeBundleListener(BundleListener listener)

      Removes the specified `BundleListener` object from the context bundle's list of listeners.

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

      Parameters:
        `listener` - The `BundleListener` object to be removed.
      Throws:
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
        `java.lang.SecurityException` - If listener is a `SynchronousBundleListener` and the caller does not have the appropriate `AdminPermission[context bundle,LISTENER]`, and the Java Runtime Environment supports permissions.

    - #### addFrameworkListener

          void addFrameworkListener(FrameworkListener listener)

      Adds the specified `FrameworkListener` object to the context bundle's list of listeners if not already present. FrameworkListeners are notified of general Framework events.

      If the 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 BundleContext is no longer valid.
      See Also:
        `FrameworkEvent`, `FrameworkListener`

    - #### removeFrameworkListener

          void removeFrameworkListener(FrameworkListener listener)

      Removes the specified `FrameworkListener` object from the context bundle's list of listeners.

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

      Parameters:
        `listener` - The `FrameworkListener` object to be removed.
      Throws:
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.

    - #### registerService

          ServiceRegistration<?> registerService(java.lang.String[] clazzes,
                                               java.lang.Object service,
                                               java.util.Dictionary<java.lang.String,?> 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. Other bundles can locate the service by using one of the `getServiceReferences(Class, String)`, `getServiceReferences(String, String)`, `getServiceReference(Class)` or `getServiceReference(String)` methods.

      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` does not implement `ServiceFactory`, an `IllegalArgumentException` is thrown if `service` is not an `instanceof` all the specified class names.
      2. The Framework adds the following service properties to the service properties from the specified `Dictionary` (which may be `null`):
         - A property named `Constants.SERVICE_ID` identifying the registration number of the service
         - A property named `Constants.OBJECTCLASS` containing all the specified classes.
         - A property named `Constants.SERVICE_SCOPE` identifying the scope of the service.
         - A property named `Constants.SERVICE_BUNDLEID` identifying the the context bundle.
         Properties with these names in the specified `Dictionary` will be ignored.
      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 fired.
      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 an object implementing `ServiceFactory`.
        `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(Dictionary)` method must be called. The set of 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` does not implement `ServiceFactory` and is not an instance of all the specified classes.
        - `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 BundleContext is no longer valid.
      See Also:
        `ServiceRegistration`, `PrototypeServiceFactory`, `ServiceFactory`

    - #### registerService

          ServiceRegistration<?> registerService(java.lang.String clazz,
                                               java.lang.Object service,
                                               java.util.Dictionary<java.lang.String,?> 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(String[], Object, 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 string, rather than just a single string.

      Parameters:
        `clazz` - The class name under which the service can be located.
        `service` - The service object or an object implementing `ServiceFactory`.
        `properties` - The properties for this service.
      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.IllegalStateException` - If this BundleContext is no longer valid.
      See Also:
        `registerService(String[], Object, Dictionary)`

    - #### registerService

          <S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz,
                                                   S service,
                                                   java.util.Dictionary<java.lang.String,?> properties)

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

      This method is otherwise identical to `registerService(String, Object, Dictionary)` and is provided to return a type safe `ServiceRegistration`.

      Type Parameters:
        `S` - Type of Service.
      Parameters:
        `clazz` - The class under whose name the service can be located.
        `service` - The service object or an object implementing `ServiceFactory`.
        `properties` - The properties for this service.
      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.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.6
      See Also:
        `registerService(String, Object, Dictionary)`

    - #### registerService

          <S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz,
                                                   ServiceFactory<S> factory,
                                                   java.util.Dictionary<java.lang.String,?> properties)

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

      This method is otherwise identical to `registerService(Class, Object, Dictionary)` and is provided to return a type safe `ServiceRegistration` when registering a `ServiceFactory`.

      Type Parameters:
        `S` - Type of Service.
      Parameters:
        `clazz` - The class under whose name the service can be located.
        `factory` - The `ServiceFactory` object.
        `properties` - The properties for this service.
      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.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.8
      See Also:
        `registerService(Class, Object, Dictionary)`

    - #### getServiceReferences

          ServiceReference<?>[] getServiceReferences(java.lang.String clazz,
                                                   java.lang.String filter)
                                                     throws InvalidSyntaxException

      Returns an array of `ServiceReference` objects. The returned array of `ServiceReference` objects contains services that were registered under the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in `ServiceReference.isAssignableTo(Bundle, String)`.

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

      The specified `filter` expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See `Filter` for a description of the filter syntax. If the specified `filter` is `null`, all registered services are considered to match the filter. If the specified `filter` expression cannot be parsed, an `InvalidSyntaxException` will be thrown with a human readable message where the filter became unparsable.

      The result is an array of `ServiceReference` objects for all services that meet all of the following conditions:

      - If the specified class name, `clazz`, is not `null`, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's `objectClass` property.
      - If the specified `filter` is not `null`, the filter expression must match the service.
      - If the Java Runtime Environment supports permissions, the caller must have `ServicePermission` with the `GET` action for at least one of the class names under which the service was registered.
      - For each class name with which the service was registered, calling `ServiceReference.isAssignableTo(Bundle, String)` with the context bundle and the class name on the service's `ServiceReference` object must return `true`
      Parameters:
        `clazz` - The class name with which the service was registered or `null` for all services.
        `filter` - The filter expression or `null` for all services.
      Returns:
        An array of `ServiceReference` objects or `null` if no services are registered which satisfy the search.
      Throws:
        `InvalidSyntaxException` - If the specified `filter` contains an invalid filter expression that cannot be parsed.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.

    - #### getAllServiceReferences

          ServiceReference<?>[] getAllServiceReferences(java.lang.String clazz,
                                                      java.lang.String filter)
                                                        throws InvalidSyntaxException

      Returns an array of `ServiceReference` objects. The returned array of `ServiceReference` objects contains services that were registered under the specified class and match the specified filter expression.

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

      The specified `filter` expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See `Filter` for a description of the filter syntax. If the specified `filter` is `null`, all registered services are considered to match the filter. If the specified `filter` expression cannot be parsed, an `InvalidSyntaxException` will be thrown with a human readable message where the filter became unparsable.

      The result is an array of `ServiceReference` objects for all services that meet all of the following conditions:

      - If the specified class name, `clazz`, is not `null`, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's `objectClass` property.
      - If the specified `filter` is not `null`, the filter expression must match the service.
      - If the Java Runtime Environment supports permissions, the caller must have `ServicePermission` with the `GET` action for at least one of the class names under which the service was registered.
      Parameters:
        `clazz` - The class name with which the service was registered or `null` for all services.
        `filter` - The filter expression or `null` for all services.
      Returns:
        An array of `ServiceReference` objects or `null` if no services are registered which satisfy the search.
      Throws:
        `InvalidSyntaxException` - If the specified `filter` contains an invalid filter expression that cannot be parsed.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.3

    - #### getServiceReference

          ServiceReference<?> getServiceReference(java.lang.String clazz)

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

      The returned `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 any time.

      This method is the same as calling `getServiceReferences(String, String)` with a `null` filter expression and then finding the reference with the highest priority. 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 priority is selected. This priority is defined as the service reference 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.
      Throws:
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      See Also:
        `getServiceReferences(String, String)`

    - #### getServiceReference

          <S> ServiceReference<S> getServiceReference(java.lang.Class<S> clazz)

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

      The returned `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 any time.

      This method is the same as calling `getServiceReferences(Class, String)` with a `null` filter expression. 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.

      Type Parameters:
        `S` - Type of Service.
      Parameters:
        `clazz` - The class under whose name the service was registered. Must not be `null`.
      Returns:
        A `ServiceReference` object, or `null` if no services are registered which implement the specified class.
      Throws:
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.6
      See Also:
        `getServiceReferences(Class, String)`

    - #### getServiceReferences

          <S> java.util.Collection<ServiceReference<S>> getServiceReferences(java.lang.Class<S> clazz,
                                                                           java.lang.String filter)
                                                                         throws InvalidSyntaxException

      Returns a collection of `ServiceReference` objects. The returned collection of `ServiceReference` objects contains services that were registered under the name of the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in `ServiceReference.isAssignableTo(Bundle, String)`.

      The collection is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

      The specified `filter` expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See `Filter` for a description of the filter syntax. If the specified `filter` is `null`, all registered services are considered to match the filter. If the specified `filter` expression cannot be parsed, an `InvalidSyntaxException` will be thrown with a human readable message where the filter became unparsable.

      The result is a collection of `ServiceReference` objects for all services that meet all of the following conditions:

      - The service must have been registered with the name of the specified class. The complete list of class names with which a service was registered is available from the service's `objectClass` property.
      - If the specified `filter` is not `null`, the filter expression must match the service.
      - If the Java Runtime Environment supports permissions, the caller must have `ServicePermission` with the `GET` action for at least one of the class names under which the service was registered.
      - For each class name with which the service was registered, calling `ServiceReference.isAssignableTo(Bundle, String)` with the context bundle and the class name on the service's `ServiceReference` object must return `true`
      Type Parameters:
        `S` - Type of Service
      Parameters:
        `clazz` - The class under whose name the service was registered. Must not be `null`.
        `filter` - The filter expression or `null` for all services.
      Returns:
        A collection of `ServiceReference` objects. May be empty if no services are registered which satisfy the search.
      Throws:
        `InvalidSyntaxException` - If the specified `filter` contains an invalid filter expression that cannot be parsed.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.6

    - #### getService

          <S> S getService(ServiceReference<S> reference)

      Returns the service object for the service referenced by the specified `ServiceReference` object.

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

      When a bundle's use count for the service drops to zero, the bundle should no longer use the service object.

      This method will always return `null` when the service associated with the specified `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. If the context bundle's use count for the service is currently zero and the service has `bundle` or `prototype` scope, the `ServiceFactory.getService(Bundle, ServiceRegistration)` method is called to supply the service object for the context bundle. If the service object returned by the `ServiceFactory` object is `null`, not an `instanceof` all the classes named when the service was registered or the `ServiceFactory` object throws an exception or will be recursively called for the context bundle, `null` is returned and a Framework event of type `FrameworkEvent.ERROR` containing a `ServiceException` describing the error is fired. The supplied 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 service object for the context bundle will return the cached service object.
      3. The context bundle's use count for the service is incremented by one.
      4. The service object for the service is returned.
      Type Parameters:
        `S` - Type of Service.
      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, the service object returned by a `ServiceFactory` does not implement the classes under which it was registered or the `ServiceFactory` threw an exception.
      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 this BundleContext is no longer valid.
        `java.lang.IllegalArgumentException` - If the specified `ServiceReference` was not created by the same framework instance as this `BundleContext`.
      See Also:
        `ungetService(ServiceReference)`, `ServiceFactory`

    - #### ungetService

          boolean ungetService(ServiceReference<?> reference)

      Releases the service object for the service 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.

      The service object must 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 release 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 the service is decremented by one.
      3. If the context bundle's use count for the service is now zero and the service has `bundle` or `prototype` scope, the `ServiceFactory.ungetService(Bundle, ServiceRegistration, 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 this BundleContext is no longer valid.
        `java.lang.IllegalArgumentException` - If the specified `ServiceReference` was not created by the same framework instance as this `BundleContext`.
      See Also:
        `getService(ServiceReference)`, `ServiceFactory`

    - #### getServiceObjects

          <S> ServiceObjects<S> getServiceObjects(ServiceReference<S> reference)

      Returns the `ServiceObjects` object for the service referenced by the specified `ServiceReference` object.

      The `ServiceObjects` object can be used to obtain multiple service objects for services with `prototype` scope.

      For services with `singleton` or `bundle` scope, the `ServiceObjects.getService()` method behaves the same as the `getService(ServiceReference)` method and the `ServiceObjects.ungetService(Object)` method behaves the same as the `ungetService(ServiceReference)` method. That is, only one, use-counted service object is available from the `ServiceObjects` object.

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

      Type Parameters:
        `S` - Type of Service.
      Parameters:
        `reference` - A reference to the service.
      Returns:
        A `ServiceObjects` object for the service associated with the specified `reference` or `null` if the service is not registered.
      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 this BundleContext is no longer valid.
        `java.lang.IllegalArgumentException` - If the specified `ServiceReference` was not created by the same framework instance as this `BundleContext`.
      Since:
        1.8
      See Also:
        `PrototypeServiceFactory`

    - #### getDataFile

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

      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 this BundleContext is no longer valid.

    - #### createFilter

          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.

      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.
        `java.lang.NullPointerException` - If `filter` is null.
        `java.lang.IllegalStateException` - If this BundleContext is no longer valid.
      Since:
        1.1
      See Also:
        "Framework specification for a description of the filter string syntax.", `FrameworkUtil.createFilter(String)`

    - #### getBundle

          Bundle getBundle(java.lang.String location)

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