org.jboss.gravia.runtime

Interface ServiceFactory<S>

Type Parameters:

S - Type of Service

public interface ServiceFactory<S>

Allows services to provide customized service objects.

When registering a service, a ServiceFactory object can be used instead of a service object, so that the module developer can gain control of the specific service object granted to a module that is using the service.

When this happens, the ModuleContext.getService(ServiceReference) method calls the ServiceFactory.getService method to create a service object specifically for the requesting module. The service object returned by the ServiceFactory is cached by the Runtime until the module releases its use of the service.

When the module's use count for the service is decremented to zero (including the module stopping or the service being unregistered), the ServiceFactory.ungetService method is called.

ServiceFactory objects are only used by the Runtime and are not made available to other modules in the environment. The Runtime may concurrently call a ServiceFactory.

Since:

27-Sep-2013

Author:

thomas.diesler@jboss.com

See Also:

ModuleContext.getService(ServiceReference)

Thread Safety: Thread Safe

Method Summary

Methods

Modifier and Type	Method and Description
S	getService(Module module, ServiceRegistration<S> registration) Creates a new service object.
void	ungetService(Module module, ServiceRegistration<S> registration, S service) Releases a service object.

Method Detail

getService

S getService(Module module,
           ServiceRegistration<S> registration)

Creates a new service object.

The Runtime invokes this method the first time the specified module requests a service object using the ModuleContext.getService(ServiceReference) method. The service factory can then return a specific service object for each module.

The Runtime 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, null is returned to the module.

The Runtime caches the valid service object and will return the same service object on any future call to ModuleContext.getService for the specified module. This means the Runtime must not allow this method to be concurrently called for the specified module.

Parameters:

module - The module 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:

ModuleContext.getService(ServiceReference)

ungetService

void ungetService(Module module,
                ServiceRegistration<S> registration,
                S service)

Releases a service object.

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

Parameters:

module - The module 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:

ModuleContext.ungetService(ServiceReference)