01: // Copyright 2006, 2007 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // Unless required by applicable law or agreed to in writing, software
10: // distributed under the License is distributed on an "AS IS" BASIS,
11: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: // See the License for the specific language governing permissions and
13: // limitations under the License.
14:
15: package org.apache.tapestry.ioc;
16:
17: /**
18: * Defines an object which can provide access to services defined within a
19: * {@link org.apache.tapestry.ioc.Registry}, or to objects or object instances available by other
20: * means. Services are accessed via service id, or (when appropriate) by just service interface. The
21: * Registry itself implements this interface, as does
22: * {@link org.apache.tapestry.ioc.ServiceResources}.
23: */
24: public interface ObjectLocator {
25:
26: /**
27: * Obtains a service via its unique service id. Returns the service's proxy. The service proxy
28: * implements the same interface as the actual service, and is used to instantiate the actual
29: * service only as needed (this is transparent to the application).
30: *
31: * @param <T>
32: * @param serviceId
33: * unique ervice id used to locate the service object (may contain <em>symbols</em>,
34: * which will be expanded), case is ignored
35: * @param serviceInterface
36: * the interface implemented by the service (or an interface extended by the service
37: * interface)
38: * @return the service instance
39: * @throws RuntimeException
40: * if the service is not defined, or if an error occurs instantiating it
41: */
42: <T> T getService(String serviceId, Class<T> serviceInterface);
43:
44: /**
45: * Locates a service given just a service interface. A single service must implement the service
46: * interface (which can be hard to guarantee). The search takes into account inheritance of the
47: * service interface (not the service <em>implementation</em>), which may result in a failure
48: * due to extra matches.
49: *
50: * @param <T>
51: * @param serviceInterface
52: * the interface the service implements
53: * @return the service's proxy
54: * @throws RuntimeException
55: * if the service does not exist (this is considered programmer error), or multiple
56: * services directly implement, or extend from, the service interface
57: */
58: <T> T getService(Class<T> serviceInterface);
59:
60: /**
61: * Obtains an object indirectly, using an {@link ObjectProvider} identified by the prefix of the
62: * reference.
63: *
64: * @param objectType
65: * the type of object to be returned
66: * @param annotationProvider
67: * provides access to annotations on the field or parameter for which a value is to
68: * be obtained, which may be utilized in selecting an appropriate object, use
69: * <strong>null</strong> when annotations are not available (in which case,
70: * selection will be based only on the object type)
71: * @param <T>
72: * @return the requested object
73: * @see ObjectProvider
74: */
75: <T> T getObject(Class<T> objectType,
76: AnnotationProvider annotationProvider);
77:
78: /**
79: * Autobuilds a class by finding the public constructor with the most parameters. Services and
80: * resources will be injected into the parameters of the constructor.
81: *
82: * @param <T>
83: * @param clazz
84: * the type of object to instantiate
85: * @return the instantiated instance
86: * @throws RuntimeException
87: * if the autobuild fails
88: */
89: <T> T autobuild(Class<T> clazz);
90: }
|