Package 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: 12129fe6e66b1c9488f3cca84ac228f9baaea083 $

See Also:

BundleContext.getServiceObjects(ServiceReference), ServiceObjects

Method Summary

Modifier and Type	Method	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)