PrototypeServiceFactory
Date: 2016-06-24

org.osgi.framework

## Interface PrototypeServiceFactory<S>

- Type Parameters:
    `S` - Type of Service
  All Superinterfaces:
    ServiceFactory<S>

      @ConsumerType
      public interface PrototypeServiceFactory<S>
      extends ServiceFactory<S>

  A factory for `prototype scope` services. The factory can provide multiple, customized service objects in the OSGi environment.

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

  When a caller uses a `ServiceObjects` to `request` a service object, the framework calls the `getService` method to return a service object customized for the requesting caller. The caller can `release` the returned service object and the framework will call the `ungetService` method with the service object.

  When a bundle uses the `BundleContext.getService(ServiceReference)` method to obtain a service object, the framework must act as if the service has `bundle scope`. That is, the framework will call the `getService` method to obtain a bundle-scoped service object which will be cached and have a use count. See `ServiceFactory`.

  A bundle can use both `ServiceObjects` and `BundleContext.getService(ServiceReference)` to obtain a service object for a service. `ServiceObjects.getService()` will always return a service object provided by a call to `getService(Bundle, ServiceRegistration)` and `BundleContext.getService(ServiceReference)` will always return the bundle-scoped service object.

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

  Since:
    1.8
  See Also:
    `BundleContext.getServiceObjects(ServiceReference)`, `ServiceObjects`

- - ### Method Summary

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

- - ### Method Detail

    - #### getService

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

      Returns a service object for a caller.

      The Framework invokes this method for each caller requesting a service object using `ServiceObjects.getService()`. The factory can then return a customized service object for the caller.

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

      Specified by:
        `getService` in interface `ServiceFactory<S>`
      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:
        `ServiceObjects.getService()`

    - #### ungetService

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

      Releases a service object customized for a caller.

      The Framework invokes this method when a service has been released by a bundle such as by calling `ServiceObjects.ungetService(Object)`. 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.

      Specified by:
        `ungetService` in interface `ServiceFactory<S>`
      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:
        `ServiceObjects.ungetService(Object)`