ServiceFactory
Date: 2016-06-24

org.osgi.framework

## Interface ServiceFactory<S>

- Type Parameters:
    `S` - Type of Service
  All Known Subinterfaces:
    PrototypeServiceFactory<S>

      @ConsumerType
      public interface ServiceFactory<S>

  A factory for `bundle scope` services. The factory can provide service objects customized for each bundle in the OSGi environment.

  When registering a service, a `ServiceFactory` object can be used instead of a service object, so that the bundle developer can create a customized service object for each bundle that is using the service.

  When a bundle `requests` the service object, the framework calls the `getService` method to return a service object customized for the requesting bundle. The returned service object is cached by the Framework for subsequent calls to `BundleContext.getService(ServiceReference)` until the bundle releases its use of the service.

  When the bundle's use count for the service is `decremented` to zero (including the bundle stopping or the service being unregistered), the framework will call the `ungetService` method.

  `ServiceFactory` objects are only used by the Framework and are not made available to other bundles in the OSGi environment. The Framework may concurrently call a `ServiceFactory`.

  See Also:
    `BundleContext.getService(ServiceReference)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `S` | `getService(Bundle bundle, ServiceRegistration<S> registration)` Returns a service object for a bundle.
    `void` | `ungetService(Bundle bundle, ServiceRegistration<S> registration, S service)` Releases a service object customized for a bundle.

- - ### Method Detail

    - #### getService

          S getService(Bundle bundle,
                     ServiceRegistration<S> registration)

      Returns a service object for a bundle.

      The Framework invokes this method the first time the specified `bundle` requests a service object using the `BundleContext.getService(ServiceReference)` method. The factory can then return a customized service object for each bundle.

      The Framework must check that the returned service object is valid. If the returned service object is `null` or is not an `instanceof` all the classes named when the service was registered, a framework event of type `FrameworkEvent.ERROR` is fired containing a service exception of type `ServiceException.FACTORY_ERROR` and `null` is returned to the bundle. If this method throws an exception, a framework event of type `FrameworkEvent.ERROR` is fired containing a service exception of type `ServiceException.FACTORY_EXCEPTION` with the thrown exception as the cause and `null` is returned to the bundle. If this method is recursively called for the specified bundle, a framework event of type `FrameworkEvent.ERROR` is fired containing a service exception of type `ServiceException.FACTORY_RECURSION` and `null` is returned to the bundle.

      The Framework caches the valid service object and will return the same service object on any future call to `BundleContext.getService(ServiceReference)` for the specified bundle. This means the Framework must not allow this method to be concurrently called for the specified bundle.

      Parameters:
        `bundle` - The bundle requesting the service.
        `registration` - The `ServiceRegistration` object for the requested service.
      Returns:
        A service object that must be an instance of all the classes named when the service was registered.
      See Also:
        `BundleContext.getService(ServiceReference)`

    - #### ungetService

          void ungetService(Bundle bundle,
                          ServiceRegistration<S> registration,
                          S service)

      Releases a service object customized for a bundle.

      The Framework invokes this method when a service has been released by a bundle. The service object may then be destroyed.

      If this method throws an exception, a framework event of type `FrameworkEvent.ERROR` is fired containing a service exception of type `ServiceException.FACTORY_EXCEPTION` with the thrown exception as the cause.

      Parameters:
        `bundle` - The bundle releasing the service.
        `registration` - The `ServiceRegistration` object for the service being released.
        `service` - The service object returned by a previous call to the `getService` method.
      See Also:
        `BundleContext.ungetService(ServiceReference)`