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 import java.lang.reflect.Method; 25 26 /** 27 * Context of an injectable type encounter. Enables reporting errors, registering injection 28 * listeners and binding method interceptors for injectable type {@code I}. It is an error to use an 29 * encounter after the {@link TypeListener#hear(TypeLiteral, TypeEncounter) hear()} method has 30 * returned. 31 * 32 * @param <I> the injectable type encountered 33 * @since 2.0 34 */ 35 public interface TypeEncounter<I> { 36 37 /** 38 * Records an error message for type {@code I} which will be presented to the user at a later 39 * time. Unlike throwing an exception, this enable us to continue configuring the Injector and 40 * discover more errors. Uses {@link String#format(String, Object[])} to insert the arguments into 41 * the message. 42 */ addError(String message, Object... arguments)43 void addError(String message, Object... arguments); 44 45 /** 46 * Records an exception for type {@code I}, the full details of which will be logged, and the 47 * message of which will be presented to the user at a later time. If your type listener calls 48 * something that you worry may fail, you should catch the exception and pass it to this method. 49 */ addError(Throwable t)50 void addError(Throwable t); 51 52 /** Records an error message to be presented to the user at a later time. */ addError(Message message)53 void addError(Message message); 54 55 /** 56 * Returns the provider used to obtain instances for the given injection key. The returned 57 * provider will not be valid until the injector has been created. The provider will throw an 58 * {@code IllegalStateException} if you try to use it beforehand. 59 */ getProvider(Key<T> key)60 <T> Provider<T> getProvider(Key<T> key); 61 62 /** 63 * Returns the provider used to obtain instances for the given injection type. The returned 64 * provider will not be valid until the injector has been created. The provider will throw an 65 * {@code IllegalStateException} if you try to use it beforehand. 66 */ getProvider(Class<T> type)67 <T> Provider<T> getProvider(Class<T> type); 68 69 /** 70 * Returns the members injector used to inject dependencies into methods and fields on instances 71 * of the given type {@code T}. The returned members injector will not be valid until the main 72 * injector has been created. The members injector will throw an {@code IllegalStateException} if 73 * you try to use it beforehand. 74 * 75 * @param typeLiteral type to get members injector for 76 */ getMembersInjector(TypeLiteral<T> typeLiteral)77 <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> typeLiteral); 78 79 /** 80 * Returns the members injector used to inject dependencies into methods and fields on instances 81 * of the given type {@code T}. The returned members injector will not be valid until the main 82 * injector has been created. The members injector will throw an {@code IllegalStateException} if 83 * you try to use it beforehand. 84 * 85 * @param type type to get members injector for 86 */ getMembersInjector(Class<T> type)87 <T> MembersInjector<T> getMembersInjector(Class<T> type); 88 89 /** 90 * Registers a members injector for type {@code I}. Guice will use the members injector after its 91 * performed its own injections on an instance of {@code I}. 92 */ register(MembersInjector<? super I> membersInjector)93 void register(MembersInjector<? super I> membersInjector); 94 95 /** 96 * Registers an injection listener for type {@code I}. Guice will notify the listener after all 97 * injections have been performed on an instance of {@code I}. 98 */ register(InjectionListener<? super I> listener)99 void register(InjectionListener<? super I> listener); 100 101 /*if[AOP]*/ 102 /** 103 * Binds method interceptor[s] to methods matched in type {@code I} and its supertypes. A method 104 * is eligible for interception if: 105 * 106 * <ul> 107 * <li>Guice created the instance the method is on 108 * <li>Neither the enclosing type nor the method is final 109 * <li>And the method is package-private or more accessible 110 * </ul> 111 * 112 * @param methodMatcher matches methods the interceptor should apply to. For example: {@code 113 * annotatedWith(Transactional.class)}. 114 * @param interceptors to bind 115 */ bindInterceptor( Matcher<? super Method> methodMatcher, org.aopalliance.intercept.MethodInterceptor... interceptors)116 void bindInterceptor( 117 Matcher<? super Method> methodMatcher, 118 org.aopalliance.intercept.MethodInterceptor... interceptors); 119 /*end[AOP]*/ 120 } 121