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

Author:
  $Id: f11fc6bee18315fb659c7987d1b66f1c9c95548a $
See Also:
  `BundleContext.getService(ServiceReference)`

### Method Summary

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