org.apache.tapestry.ioc
Interface ObjectLocator

All Known Subinterfaces:

InternalRegistry, Registry, ServiceBuilderResources, ServiceResources

All Known Implementing Classes:

IOCInternalTestCase, ObjectLocatorImpl, RegistryImpl, RegistryWrapper, ServiceResourcesImpl

public interface ObjectLocator

Defines an object which can provide access to services defined within a Registry, or to objects or object instances available by other means. Services are accessed via service id, or (when appropriate) by just service interface. The Registry itself implements this interface, as does ServiceResources.

Method Summary

<T> T	autobuild(Class<T> clazz) Autobuilds a class by finding the public constructor with the most parameters.
<T> T	getObject(Class<T> objectType, AnnotationProvider annotationProvider) Obtains an object indirectly, using an ObjectProvider identified by the prefix of the reference.
<T> T	getService(Class<T> serviceInterface) Locates a service given just a service interface.
<T> T	getService(String serviceId, Class<T> serviceInterface) Obtains a service via its unique service id.
<T> T	proxy(Class<T> interfaceClass, Class<? extends T> implementationClass) Creates a proxy.

Method Detail

getService

<T> T getService(String serviceId,
                 Class<T> serviceInterface)

Obtains a service via its unique service id. Returns the service's proxy. The service proxy implements the same interface as the actual service, and is used to instantiate the actual service only as needed (this is transparent to the application).

Type Parameters:

T -

Parameters:

serviceId - unique Service id used to locate the service object (may contain symbols, which will be expanded), case is ignored

serviceInterface - the interface implemented by the service (or an interface extended by the service interface)

Returns:

the service instance

Throws:

RuntimeException - if the service is not defined, or if an error occurs instantiating it

getService

<T> T getService(Class<T> serviceInterface)

Locates a service given just a service interface. A single service must implement the service interface (which can be hard to guarantee). The search takes into account inheritance of the service interface (not the service implementation), which may result in a failure due to extra matches.

Type Parameters:

T -

Parameters:

serviceInterface - the interface the service implements

Returns:

the service's proxy

Throws:

RuntimeException - if the service does not exist (this is considered programmer error), or multiple services directly implement, or extend from, the service interface

getObject

<T> T getObject(Class<T> objectType,
                AnnotationProvider annotationProvider)

Obtains an object indirectly, using an ObjectProvider identified by the prefix of the reference.

Type Parameters:

T -

Parameters:

objectType - the type of object to be returned

annotationProvider - provides access to annotations on the field or parameter for which a value is to be obtained, which may be utilized in selecting an appropriate object, use null when annotations are not available (in which case, selection will be based only on the object type)

Returns:

the requested object

See Also:

ObjectProvider

autobuild

<T> T autobuild(Class<T> clazz)

Autobuilds a class by finding the public constructor with the most parameters. Services and resources will be injected into the parameters of the constructor.

Type Parameters:

T -

Parameters:

clazz - the type of object to instantiate

Returns:

the instantiated instance

Throws:

RuntimeException - if the autobuild fails

See Also:

MasterObjectProvider

proxy

<T> T proxy(Class<T> interfaceClass,
            Class<? extends T> implementationClass)

Creates a proxy. The proxy will defer invocation of autobuild(Class) until just-in-time (that is, first method invocation). In a limited number of cases, it is necessary to use such a proxy to prevent service construction cycles, particularly when contributing (directly or indirectly) to the MasterObjectProvider (which is itself at the heart of autobuilding).

Type Parameters:

T -

Parameters:

interfaceClass - the interface implemented by the proxy

implementationClass - a concrete class that implements the interface

Returns:

a proxy