1 /** 2 * Copyright (C) 2009 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.inject.spi; 18 19 import com.google.inject.Key; 20 import com.google.inject.MembersInjector; 21 import com.google.inject.Provider; 22 import com.google.inject.TypeLiteral; 23 import com.google.inject.matcher.Matcher; 24 25 import java.lang.reflect.Method; 26 27 /** 28 * Context of an injectable type encounter. Enables reporting errors, registering injection 29 * listeners and binding method interceptors for injectable type {@code I}. It is an error to use 30 * an encounter after the {@link TypeListener#hear(TypeLiteral, TypeEncounter) hear()} method has 31 * returned. 32 * 33 * @param <I> the injectable type encountered 34 * @since 2.0 35 */ 36 public interface TypeEncounter<I> { 37 38 /** 39 * Records an error message for type {@code I} which will be presented to the user at a later 40 * time. Unlike throwing an exception, this enable us to continue configuring the Injector and 41 * discover more errors. Uses {@link String#format(String, Object[])} to insert the arguments 42 * into the message. 43 */ addError(String message, Object... arguments)44 void addError(String message, Object... arguments); 45 46 /** 47 * Records an exception for type {@code I}, the full details of which will be logged, and the 48 * message of which will be presented to the user at a later time. If your type listener calls 49 * something that you worry may fail, you should catch the exception and pass it to this method. 50 */ addError(Throwable t)51 void addError(Throwable t); 52 53 /** 54 * Records an error message to be presented to the user at a later time. 55 */ addError(Message message)56 void addError(Message message); 57 58 /** 59 * Returns the provider used to obtain instances for the given injection key. The returned 60 * provider will not be valid until the injector has been created. The provider will throw an 61 * {@code IllegalStateException} if you try to use it beforehand. 62 */ getProvider(Key<T> key)63 <T> Provider<T> getProvider(Key<T> key); 64 65 /** 66 * Returns the provider used to obtain instances for the given injection type. The returned 67 * provider will not be valid until the injector has been created. The provider will throw an 68 * {@code IllegalStateException} if you try to use it beforehand. 69 */ getProvider(Class<T> type)70 <T> Provider<T> getProvider(Class<T> type); 71 72 /** 73 * Returns the members injector used to inject dependencies into methods and fields on instances 74 * of the given type {@code T}. The returned members injector will not be valid until the main 75 * injector has been created. The members injector will throw an {@code IllegalStateException} 76 * if you try to use it beforehand. 77 * 78 * @param typeLiteral type to get members injector for 79 */ getMembersInjector(TypeLiteral<T> typeLiteral)80 <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> typeLiteral); 81 82 /** 83 * Returns the members injector used to inject dependencies into methods and fields on instances 84 * of the given type {@code T}. The returned members injector will not be valid until the main 85 * injector has been created. The members injector will throw an {@code IllegalStateException} 86 * if you try to use it beforehand. 87 * 88 * @param type type to get members injector for 89 */ getMembersInjector(Class<T> type)90 <T> MembersInjector<T> getMembersInjector(Class<T> type); 91 92 /** 93 * Registers a members injector for type {@code I}. Guice will use the members injector after its 94 * performed its own injections on an instance of {@code I}. 95 */ register(MembersInjector<? super I> membersInjector)96 void register(MembersInjector<? super I> membersInjector); 97 98 /** 99 * Registers an injection listener for type {@code I}. Guice will notify the listener after all 100 * injections have been performed on an instance of {@code I}. 101 */ register(InjectionListener<? super I> listener)102 void register(InjectionListener<? super I> listener); 103 104 /*if[AOP]*/ 105 /** 106 * Binds method interceptor[s] to methods matched in type {@code I} and its supertypes. A 107 * method is eligible for interception if: 108 * 109 * <ul> 110 * <li>Guice created the instance the method is on</li> 111 * <li>Neither the enclosing type nor the method is final</li> 112 * <li>And the method is package-private or more accessible</li> 113 * </ul> 114 * 115 * @param methodMatcher matches methods the interceptor should apply to. For 116 * example: {@code annotatedWith(Transactional.class)}. 117 * @param interceptors to bind 118 */ bindInterceptor(Matcher<? super Method> methodMatcher, org.aopalliance.intercept.MethodInterceptor... interceptors)119 void bindInterceptor(Matcher<? super Method> methodMatcher, 120 org.aopalliance.intercept.MethodInterceptor... interceptors); 121 /*end[AOP]*/ 122 } 123