ServiceComponentRuntime
Date: 2016-06-25

org.osgi.service.component.runtime

## Interface ServiceComponentRuntime

-     @ProviderType
      public interface ServiceComponentRuntime

  The `ServiceComponentRuntime` service represents the Declarative Services actor, known as Service Component Runtime (SCR), that manages the service components and their life cycle. The `ServiceComponentRuntime` service allows introspection of the components managed by Service Component Runtime.

  This service differentiates between a `ComponentDescriptionDTO` and a `ComponentConfigurationDTO`. A `ComponentDescriptionDTO` is a representation of a declared component description. A `ComponentConfigurationDTO` is a representation of an actual instance of a declared component description parameterized by component properties.

  Access to this service requires the `ServicePermission[ServiceComponentRuntime, GET]` permission. It is intended that only administrative bundles should be granted this permission to limit access to the potentially intrusive methods provided by this service.

  Since:
    1.3

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Promise<java.lang.Void>` | `disableComponent(ComponentDescriptionDTO description)` Disables the specified component description.
    `Promise<java.lang.Void>` | `enableComponent(ComponentDescriptionDTO description)` Enables the specified component description.
    `java.util.Collection<ComponentConfigurationDTO>` | `getComponentConfigurationDTOs(ComponentDescriptionDTO description)` Returns the component configurations for the specified component description.
    `ComponentDescriptionDTO` | `getComponentDescriptionDTO(org.osgi.framework.Bundle bundle, java.lang.String name)` Returns the `ComponentDescriptionDTO` declared with the specified name by the specified bundle.
    `java.util.Collection<ComponentDescriptionDTO>` | `getComponentDescriptionDTOs(org.osgi.framework.Bundle... bundles)` Returns the component descriptions declared by the specified active bundles.
    `boolean` | `isComponentEnabled(ComponentDescriptionDTO description)` Returns whether the specified component description is currently enabled.

- - ### Method Detail

    - #### getComponentDescriptionDTOs

          java.util.Collection<ComponentDescriptionDTO> getComponentDescriptionDTOs(org.osgi.framework.Bundle... bundles)

      Returns the component descriptions declared by the specified active bundles.

      Only component descriptions from active bundles are returned. If the specified bundles have no declared components or are not active, an empty collection is returned.

      Parameters:
        `bundles` - The bundles whose declared component descriptions are to be returned. Specifying no bundles, or the equivalent of an empty `Bundle` array, will return the declared component descriptions from all active bundles.
      Returns:
        The declared component descriptions of the specified active `bundles`. An empty collection is returned if there are no component descriptions for the specified active bundles.

    - #### getComponentDescriptionDTO

          ComponentDescriptionDTO getComponentDescriptionDTO(org.osgi.framework.Bundle bundle,
                                                           java.lang.String name)

      Returns the `ComponentDescriptionDTO` declared with the specified name by the specified bundle.

      Only component descriptions from active bundles are returned. `null` if no such component is declared by the given `bundle` or the bundle is not active.

      Parameters:
        `bundle` - The bundle declaring the component description. Must not be `null`.
        `name` - The name of the component description. Must not be `null`.
      Returns:
        The declared component description or `null` if the specified bundle is not active or does not declare a component description with the specified name.

    - #### getComponentConfigurationDTOs

          java.util.Collection<ComponentConfigurationDTO> getComponentConfigurationDTOs(ComponentDescriptionDTO description)

      Returns the component configurations for the specified component description.
      Parameters:
        `description` - The component description. Must not be `null`.
      Returns:
        A collection containing a snapshot of the current component configurations for the specified component description. An empty collection is returned if there are none.

    - #### isComponentEnabled

          boolean isComponentEnabled(ComponentDescriptionDTO description)

      Returns whether the specified component description is currently enabled.

      The enabled state of a component description is initially set by the `enabled` attribute of the component description.

      Parameters:
        `description` - The component description. Must not be `null`.
      Returns:
        `true` if the specified component description is currently enabled. Otherwise, `false`.
      See Also:
        `enableComponent(ComponentDescriptionDTO)`, `disableComponent(ComponentDescriptionDTO)`, `ComponentContext.disableComponent(String)`, `ComponentContext.enableComponent(String)`

    - #### enableComponent

          Promise<java.lang.Void> enableComponent(ComponentDescriptionDTO description)

      Enables the specified component description.

      If the specified component description is currently enabled, this method has no effect.

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

      Parameters:
        `description` - The component description to enable. Must not be `null`.
      Returns:
        A promise that will be resolved when the actions that result from changing the enabled state of the specified component have completed.
      See Also:
        `isComponentEnabled(ComponentDescriptionDTO)`

    - #### disableComponent

          Promise<java.lang.Void> disableComponent(ComponentDescriptionDTO description)

      Disables the specified component description.

      If the specified component description is currently disabled, this method has no effect.

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

      Parameters:
        `description` - The component description to disable. Must not be `null`.
      Returns:
        A promise that will be resolved when the actions that result from changing the enabled state of the specified component have completed.
      See Also:
        `isComponentEnabled(ComponentDescriptionDTO)`