001// Copyright 2006, 2007, 2010, 2011, 2014 The Apache Software Foundation 002// 003// Licensed under the Apache License, Version 2.0 (the "License"); 004// you may not use this file except in compliance with the License. 005// You may obtain a copy of the License at 006// 007// http://www.apache.org/licenses/LICENSE-2.0 008// 009// Unless required by applicable law or agreed to in writing, software 010// distributed under the License is distributed on an "AS IS" BASIS, 011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 012// See the License for the specific language governing permissions and 013// limitations under the License. 014 015package org.apache.tapestry5.ioc; 016 017import org.apache.tapestry5.ioc.annotations.Inject; 018 019import java.lang.annotation.Annotation; 020 021/** 022 * Defines an object which can provide access to services defined within a {@link org.apache.tapestry5.ioc.Registry}, or 023 * to objects or object instances available by other means. Services are accessed via service id, or 024 * (when appropriate) 025 * by just service interface. The Registry itself implements this interface, as does 026 * {@link org.apache.tapestry5.ioc.ServiceResources}. 027 */ 028public interface ObjectLocator 029{ 030 /** 031 * Obtains a service via its unique service id. Returns the service's proxy. The service proxy 032 * implements the same 033 * interface as the actual service, and is used to instantiate the actual service only as needed 034 * (this is 035 * transparent to the application). 036 * 037 * @param <T> 038 * @param serviceId unique Service id used to locate the service object (may contain <em>symbols</em>, 039 * which 040 * will be expanded), case is ignored 041 * @param serviceInterface the interface implemented by the service (or an interface extended by the service 042 * interface) 043 * @return the service instance 044 * @throws RuntimeException if the service is not defined, or if an error occurs instantiating it 045 */ 046 <T> T getService(String serviceId, Class<T> serviceInterface); 047 048 /** 049 * Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service 050 * interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface 051 * (not the service <em>implementation</em>), which may result in a failure due to extra 052 * matches. 053 * 054 * @param serviceInterface the interface the service implements 055 * @return the service's proxy 056 * @throws RuntimeException if the service does not exist (this is considered programmer error), or multiple 057 * services directly implement, or extend from, the service interface 058 * @see org.apache.tapestry5.ioc.annotations.Marker 059 */ 060 <T> T getService(Class<T> serviceInterface); 061 062 /** 063 * Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service 064 * interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface 065 * (not the service <em>implementation</em>), which may result in a failure due to extra 066 * matches. The ability to specify marker annotation types was added in 5.3 067 * 068 * @param serviceInterface the interface the service implements 069 * @param markerTypes Markers used to select a specific service that implements the interface 070 * @return the service's proxy 071 * @throws RuntimeException if the service does not exist (this is considered programmer error), or multiple 072 * services directly implement, or extend from, the service interface 073 * @see org.apache.tapestry5.ioc.annotations.Marker 074 * @since 5.3 075 */ 076 <T> T getService(Class<T> serviceInterface, Class<? extends Annotation>... markerTypes); 077 078 /** 079 * Obtains an object indirectly, using the {@link org.apache.tapestry5.ioc.services.MasterObjectProvider} service. 080 * 081 * @param objectType the type of object to be returned 082 * @param annotationProvider provides access to annotations on the field or parameter for which a value is to 083 * be 084 * obtained, which may be utilized in selecting an appropriate object, use 085 * <strong>null</strong> when annotations are not available (in which case, selection 086 * will 087 * be based only on the object type) 088 * @param <T> 089 * @return the requested object 090 * @see ObjectProvider 091 */ 092 <T> T getObject(Class<T> objectType, AnnotationProvider annotationProvider); 093 094 /** 095 * Autobuilds a class by finding the public constructor with the most parameters. Services and other resources or 096 * dependencies will be injected into the parameters of the constructor and into private fields marked with the 097 * {@link Inject} annotation. There are two cases: constructing a service implementation, and constructing 098 * an arbitrary object. In the former case, many <em>service resources</em> are also available for injection, not 099 * just dependencies or objects provided via 100 * {@link MasterObjectProvider#provide(Class, AnnotationProvider, ObjectLocator, boolean)}. 101 * 102 * @param <T> 103 * @param clazz the type of object to instantiate 104 * @return the instantiated instance 105 * @throws RuntimeException if the autobuild fails 106 * @see MasterObjectProvider 107 */ 108 <T> T autobuild(Class<T> clazz); 109 110 /** 111 * Preferred version of {@link #autobuild(Class)} that tracks the operation using 112 * {@link OperationTracker#invoke(String, Invokable)}. 113 * 114 * @param <T> 115 * @param description description used with {@link OperationTracker} 116 * @param clazz the type of object to instantiate 117 * @return the instantiated instance 118 * @throws RuntimeException if the autobuild fails 119 * @see MasterObjectProvider 120 * @since 5.2.0 121 */ 122 <T> T autobuild(String description, Class<T> clazz); 123 124 /** 125 * Creates a proxy. The proxy will defer invocation of {@link #autobuild(Class)} until 126 * just-in-time (that is, first method invocation). In a limited number of cases, it is necessary to use such a 127 * proxy to prevent service construction cycles, particularly when contributing (directly or indirectly) to the 128 * {@link org.apache.tapestry5.ioc.services.MasterObjectProvider} (which is itself at the heart 129 * of autobuilding). 130 * <p/> 131 * If the class file for the class is a file on the file system (not a file packaged in a JAR), then the proxy will 132 * <em>autoreload</em>: changing the class file will result in the new class being reloaded and re-instantiated 133 * (with dependencies). 134 * 135 * @param <T> 136 * @param interfaceClass the interface implemented by the proxy 137 * @param implementationClass a concrete class that implements the interface 138 * @return a proxy 139 * @see #autobuild(Class) 140 */ 141 <T> T proxy(Class<T> interfaceClass, Class<? extends T> implementationClass); 142}