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: * Object providers represent an alternate way to locate an object provided somewhere in the
19: * {@link org.apache.tapestry.ioc.Registry}. Instead of using a just the service id to gain access
20: * to a service within the Registry, object providers in different flavors are capable of vending,
21: * or even creating, objects of disparate types from disparate sources.
22: * <p>
23: * Object providers are consulted in a strict order, and the first non-null result is taken.
24: * <p>
25: * In many cases, an object provider searches for additional annotations on the element (usually a
26: * parameter, or perhaps a field) for which a value is required.
27: * <p>
28: * A default ObjectProvider uses {@link ObjectLocator#getService(Class)}.
29: */
30: public interface ObjectProvider {
31: /**
32: * Provides an object based on an expression. The process of providing objects occurs within a
33: * particular <em>context</em>, which will typically be a service builder method, service
34: * contributor method, or service decorator method. The locator parameter provides access to the
35: * services visible <em>to that context</em>.
36: *
37: * @param objectType
38: * the expected object type
39: * @param annotationProvider
40: * provides access to annotations (typically, the field or parameter to which an
41: * injection-related annotation is attached); annotations on the field or parameter
42: * may also be used when resolving the desired object
43: * @param locator
44: * locator for the <em>context</em> in which the provider is being used
45: * @param <T>
46: * @return the requested object, or null if this object provider can not supply an object
47: * @throws RuntimeException
48: * if the expression can not be evaluated, or the type of object identified is not
49: * assignable to the type specified by the objectType parameter
50: */
51: <T> T provide(Class<T> objectType,
52: AnnotationProvider annotationProvider, ObjectLocator locator);
53: }
|