ComponentServiceObjects
Date: 2016-06-25

org.osgi.service.component

## Interface ComponentServiceObjects<S>

- Type Parameters:
    `S` - Type of Service

      @ProviderType
      public interface ComponentServiceObjects<S>

  Allows multiple service objects for a service to be obtained.

  A component instance can receive a `ComponentServiceObjects` object via a reference that is typed `ComponentServiceObjects`.

  For services with `prototype` scope, multiple service objects for the service can be obtained. For services with `singleton` or `bundle` scope, only one, use-counted service object is available.

  Any unreleased service objects obtained from this `ComponentServiceObjects` object are automatically released by Service Component Runtime when the service becomes unbound.

  Since:
    1.3
  See Also:
    `ServiceObjects`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `S` | `getService()` Returns a service object for the `associated` service.
    `org.osgi.framework.ServiceReference<S>` | `getServiceReference()` Returns the `ServiceReference` for the service associated with this `ComponentServiceObjects` object.
    `void` | `ungetService(S service)` Releases a service object for the `associated` service.

- - ### Method Detail

    - #### getService

          S getService()

      Returns a service object for the `associated` service.

      This method will always return `null` when the associated service has been become unbound.

      Returns:
        A service object for the associated service or `null` if the service is unbound, the customized 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.IllegalStateException` - If the associated service has been become unbound.
      See Also:
        `ungetService(Object)`

    - #### ungetService

          void ungetService(S service)

      Releases a service object for the `associated` service.

      The specified service object must no longer be used and all references to it should be destroyed after calling this method.

      Parameters:
        `service` - A service object previously provided by this `ComponentServiceObjects` object.
      Throws:
        `java.lang.IllegalStateException` - If the associated service has been become unbound.
        `java.lang.IllegalArgumentException` - If the specified service object was not provided by this `ComponentServiceObjects` object.
      See Also:
        `getService()`

    - #### getServiceReference

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

      Returns the `ServiceReference` for the service associated with this `ComponentServiceObjects` object.
      Returns:
        The `ServiceReference` for the service associated with this `ComponentServiceObjects` object.