ComponentContext
Date: 2016-06-25

org.osgi.service.component

## Interface ComponentContext

-     @ProviderType
      public interface ComponentContext

  A Component Context object is used by a component instance to interact with its execution context including locating services by reference name. Each component instance has a unique Component Context.

  A component instance may obtain its Component Context object through its activate, modified, and deactivate methods.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `disableComponent(java.lang.String name)` Disables the specified component name.
    `void` | `enableComponent(java.lang.String name)` Enables the specified component name.
    `org.osgi.framework.BundleContext` | `getBundleContext()` Returns the `BundleContext` of the bundle which contains this component.
    `ComponentInstance` | `getComponentInstance()` Returns the Component Instance object for the component instance associated with this Component Context.
    `java.util.Dictionary<java.lang.String,java.lang.Object>` | `getProperties()` Returns the component properties for this Component Context.
    `org.osgi.framework.ServiceReference<?>` | `getServiceReference()` If the component instance is registered as a service using the `service` element, then this method returns the service reference of the service provided by this component instance.
    `org.osgi.framework.Bundle` | `getUsingBundle()` If the component instance is registered as a service using the `servicescope="bundle"` or `servicescope="prototype"` attribute, then this method returns the bundle using the service provided by the component instance.
    `java.lang.Object` | `locateService(java.lang.String name)` Returns the service object for the specified reference name.
    `<S> S` | `locateService(java.lang.String name, org.osgi.framework.ServiceReference<S> reference)` Returns the service object for the specified reference name and `ServiceReference`.
    `java.lang.Object[]` | `locateServices(java.lang.String name)` Returns the service objects for the specified reference name.

- - ### Method Detail

    - #### getProperties

          java.util.Dictionary<java.lang.String,java.lang.Object> getProperties()

      Returns the component properties for this Component Context.
      Returns:
        The properties for this Component Context. The Dictionary is read only and cannot be modified.

    - #### locateService

          java.lang.Object locateService(java.lang.String name)

      Returns the service object for the specified reference name.

      If the cardinality of the reference is `0..n` or `1..n` and multiple services are bound to the reference, 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:
        `name` - The name of a reference as specified in a `reference` element in this component's description.
      Returns:
        A service object for the referenced service or `null` if the reference cardinality is `0..1` or `0..n` and no bound service is available.
      Throws:
        `ComponentException` - If Service Component Runtime catches an exception while activating the bound service.

    - #### locateService

          <S> S locateService(java.lang.String name,
                            org.osgi.framework.ServiceReference<S> reference)

      Returns the service object for the specified reference name and `ServiceReference`.
      Type Parameters:
        `S` - Type of Service.
      Parameters:
        `name` - The name of a reference as specified in a `reference` element in this component's description.
        `reference` - The `ServiceReference` to a bound service. This must be a `ServiceReference` provided to the component via the bind or unbind method for the specified reference name.
      Returns:
        A service object for the referenced service or `null` if the specified `ServiceReference` is not a bound service for the specified reference name.
      Throws:
        `ComponentException` - If Service Component Runtime catches an exception while activating the bound service.

    - #### locateServices

          java.lang.Object[] locateServices(java.lang.String name)

      Returns the service objects for the specified reference name.
      Parameters:
        `name` - The name of a reference as specified in a `reference` element in this component's description.
      Returns:
        An array of service objects for the referenced service or `null` if the reference cardinality is `0..1` or `0..n` and no bound service is available. If the reference cardinality is `0..1` or `1..1` and a bound service is available, the array will have exactly one element.
      Throws:
        `ComponentException` - If Service Component Runtime catches an exception while activating a bound service.

    - #### getBundleContext

          org.osgi.framework.BundleContext getBundleContext()

      Returns the `BundleContext` of the bundle which contains this component.
      Returns:
        The `BundleContext` of the bundle containing this component.

    - #### getUsingBundle

          org.osgi.framework.Bundle getUsingBundle()

      If the component instance is registered as a service using the `servicescope="bundle"` or `servicescope="prototype"` attribute, then this method returns the bundle using the service provided by the component instance.

      This method will return `null` if:

      - The component instance is not a service, then no bundle can be using it as a service.
      - The component instance is a service but did not specify the `servicescope="bundle"` or `servicescope="prototype"` attribute, then all bundles using the service provided by the component instance will share the same component instance.
      - The service provided by the component instance is not currently being used by any bundle.
      Returns:
        The bundle using the component instance as a service or `null`.

    - #### getComponentInstance

          ComponentInstance getComponentInstance()

      Returns the Component Instance object for the component instance associated with this Component Context.
      Returns:
        The Component Instance object for the component instance.

    - #### enableComponent

          void enableComponent(java.lang.String name)

      Enables the specified component name. The specified component name must be in the same bundle as this component.

      This method must return after changing the enabled state of the specified component name. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

      Parameters:
        `name` - The name of a component or `null` to indicate all components in the bundle.

    - #### disableComponent

          void disableComponent(java.lang.String name)

      Disables the specified component name. The specified component name must be in the same bundle as this component.

      This method must return after changing the enabled state of the specified component name. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

      Parameters:
        `name` - The name of a component.

    - #### getServiceReference

          org.osgi.framework.ServiceReference<?> getServiceReference()

      If the component instance is registered as a service using the `service` element, then this method returns the service reference of the service provided by this component instance.

      This method will return `null` if the component instance is not registered as a service.

      Returns:
        The `ServiceReference` object for the component instance or `null` if the component instance is not registered as a service.