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
Author:
  $Id$
See Also:
  `BundleContext.getServiceObjects(ServiceReference)`, `ServiceObjects`

### Method Summary

All Methods Instance Methods Abstract Methods
`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)`