1 /** 2 * Copyright (C) 2006 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; 18 19 import com.google.inject.spi.TypeConverterBinding; 20 21 import java.lang.annotation.Annotation; 22 import java.util.List; 23 import java.util.Map; 24 import java.util.Set; 25 26 /** 27 * Builds the graphs of objects that make up your application. The injector tracks the dependencies 28 * for each type and uses bindings to inject them. This is the core of Guice, although you rarely 29 * interact with it directly. This "behind-the-scenes" operation is what distinguishes dependency 30 * injection from its cousin, the service locator pattern. 31 * 32 * <p>Contains several default bindings: 33 * 34 * <ul> 35 * <li>This {@link Injector} instance itself 36 * <li>A {@code Provider<T>} for each binding of type {@code T} 37 * <li>The {@link java.util.logging.Logger} for the class being injected 38 * <li>The {@link Stage} in which the Injector was created 39 * </ul> 40 * 41 * Injectors are created using the facade class {@link Guice}. 42 * 43 * <p>An injector can also {@link #injectMembers(Object) inject the dependencies} of 44 * already-constructed instances. This can be used to interoperate with objects created by other 45 * frameworks or services. 46 * 47 * <p>Injectors can be {@link #createChildInjector(Iterable) hierarchical}. Child injectors inherit 48 * the configuration of their parent injectors, but the converse does not hold. 49 * 50 * <p>The injector's {@link #getBindings() internal bindings} are available for introspection. This 51 * enables tools and extensions to operate on an injector reflectively. 52 * 53 * @author crazybob@google.com (Bob Lee) 54 * @author jessewilson@google.com (Jesse Wilson) 55 */ 56 public interface Injector { 57 58 /** 59 * Injects dependencies into the fields and methods of {@code instance}. Ignores the presence or 60 * absence of an injectable constructor. 61 * 62 * <p>Whenever Guice creates an instance, it performs this injection automatically (after first 63 * performing constructor injection), so if you're able to let Guice create all your objects for 64 * you, you'll never need to use this method. 65 * 66 * @param instance to inject members on 67 * 68 * @see Binder#getMembersInjector(Class) for a preferred alternative that supports checks before 69 * run time 70 */ injectMembers(Object instance)71 void injectMembers(Object instance); 72 73 /** 74 * Returns the members injector used to inject dependencies into methods and fields on instances 75 * of the given type {@code T}. 76 * 77 * @param typeLiteral type to get members injector for 78 * @see Binder#getMembersInjector(TypeLiteral) for an alternative that offers up front error 79 * detection 80 * @since 2.0 81 */ getMembersInjector(TypeLiteral<T> typeLiteral)82 <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> typeLiteral); 83 84 /** 85 * Returns the members injector used to inject dependencies into methods and fields on instances 86 * of the given type {@code T}. When feasible, use {@link Binder#getMembersInjector(TypeLiteral)} 87 * instead to get increased up front error detection. 88 * 89 * @param type type to get members injector for 90 * @see Binder#getMembersInjector(Class) for an alternative that offers up front error 91 * detection 92 * @since 2.0 93 */ getMembersInjector(Class<T> type)94 <T> MembersInjector<T> getMembersInjector(Class<T> type); 95 96 /** 97 * Returns this injector's <strong>explicit</strong> bindings. 98 * 99 * <p>The returned map does not include bindings inherited from a {@link #getParent() parent 100 * injector}, should one exist. The returned map is guaranteed to iterate (for example, with 101 * its {@link Map#entrySet()} iterator) in the order of insertion. In other words, the order in 102 * which bindings appear in user Modules. 103 * 104 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 105 */ getBindings()106 Map<Key<?>, Binding<?>> getBindings(); 107 108 /** 109 * Returns a snapshot of this injector's bindings, <strong>both explicit and 110 * just-in-time</strong>. The returned map is immutable; it contains only the bindings that were 111 * present when {@code getAllBindings()} was invoked. Subsequent calls may return a map with 112 * additional just-in-time bindings. 113 * 114 * <p>The returned map does not include bindings inherited from a {@link #getParent() parent 115 * injector}, should one exist. 116 * 117 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 118 * 119 * @since 3.0 120 */ getAllBindings()121 Map<Key<?>, Binding<?>> getAllBindings(); 122 123 /** 124 * Returns the binding for the given injection key. This will be an explicit bindings if the key 125 * was bound explicitly by a module, or an implicit binding otherwise. The implicit binding will 126 * be created if necessary. 127 * 128 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 129 * 130 * @throws ConfigurationException if this injector cannot find or create the binding. 131 */ getBinding(Key<T> key)132 <T> Binding<T> getBinding(Key<T> key); 133 134 /** 135 * Returns the binding for the given type. This will be an explicit bindings if the injection key 136 * was bound explicitly by a module, or an implicit binding otherwise. The implicit binding will 137 * be created if necessary. 138 * 139 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 140 * 141 * @throws ConfigurationException if this injector cannot find or create the binding. 142 * @since 2.0 143 */ getBinding(Class<T> type)144 <T> Binding<T> getBinding(Class<T> type); 145 146 /** 147 * Returns the binding if it already exists, or null if does not exist. Unlike 148 * {@link #getBinding(Key)}, this does not attempt to create just-in-time bindings 149 * for keys that aren't bound. 150 * 151 * <p> This method is part of the Guice SPI and is intended for use by tools and extensions. 152 * 153 * @since 3.0 154 */ getExistingBinding(Key<T> key)155 <T> Binding<T> getExistingBinding(Key<T> key); 156 157 /** 158 * Returns all explicit bindings for {@code type}. 159 * 160 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 161 */ findBindingsByType(TypeLiteral<T> type)162 <T> List<Binding<T>> findBindingsByType(TypeLiteral<T> type); 163 164 /** 165 * Returns the provider used to obtain instances for the given injection key. When feasible, avoid 166 * using this method, in favor of having Guice inject your dependencies ahead of time. 167 * 168 * @throws ConfigurationException if this injector cannot find or create the provider. 169 * @see Binder#getProvider(Key) for an alternative that offers up front error detection 170 */ getProvider(Key<T> key)171 <T> Provider<T> getProvider(Key<T> key); 172 173 /** 174 * Returns the provider used to obtain instances for the given type. When feasible, avoid 175 * using this method, in favor of having Guice inject your dependencies ahead of time. 176 * 177 * @throws ConfigurationException if this injector cannot find or create the provider. 178 * @see Binder#getProvider(Class) for an alternative that offers up front error detection 179 */ getProvider(Class<T> type)180 <T> Provider<T> getProvider(Class<T> type); 181 182 /** 183 * Returns the appropriate instance for the given injection key; equivalent to {@code 184 * getProvider(key).get()}. When feasible, avoid using this method, in favor of having Guice 185 * inject your dependencies ahead of time. 186 * 187 * @throws ConfigurationException if this injector cannot find or create the provider. 188 * @throws ProvisionException if there was a runtime failure while providing an instance. 189 */ getInstance(Key<T> key)190 <T> T getInstance(Key<T> key); 191 192 /** 193 * Returns the appropriate instance for the given injection type; equivalent to {@code 194 * getProvider(type).get()}. When feasible, avoid using this method, in favor of having Guice 195 * inject your dependencies ahead of time. 196 * 197 * @throws ConfigurationException if this injector cannot find or create the provider. 198 * @throws ProvisionException if there was a runtime failure while providing an instance. 199 */ getInstance(Class<T> type)200 <T> T getInstance(Class<T> type); 201 202 /** 203 * Returns this injector's parent, or {@code null} if this is a top-level injector. 204 * 205 * @since 2.0 206 */ getParent()207 Injector getParent(); 208 209 /** 210 * Returns a new injector that inherits all state from this injector. All bindings, scopes, 211 * interceptors and type converters are inherited -- they are visible to the child injector. 212 * Elements of the child injector are not visible to its parent. 213 * 214 * <p>Just-in-time bindings created for child injectors will be created in an ancestor injector 215 * whenever possible. This allows for scoped instances to be shared between injectors. Use 216 * explicit bindings to prevent bindings from being shared with the parent injector. Optional 217 * injections in just-in-time bindings (created in the parent injector) may be silently 218 * ignored if the optional dependencies are from the child injector. 219 * 220 * <p>No key may be bound by both an injector and one of its ancestors. This includes just-in-time 221 * bindings. The lone exception is the key for {@code Injector.class}, which is bound by each 222 * injector to itself. 223 * 224 * @since 2.0 225 */ createChildInjector(Iterable<? extends Module> modules)226 Injector createChildInjector(Iterable<? extends Module> modules); 227 228 /** 229 * Returns a new injector that inherits all state from this injector. All bindings, scopes, 230 * interceptors and type converters are inherited -- they are visible to the child injector. 231 * Elements of the child injector are not visible to its parent. 232 * 233 * <p>Just-in-time bindings created for child injectors will be created in an ancestor injector 234 * whenever possible. This allows for scoped instances to be shared between injectors. Use 235 * explicit bindings to prevent bindings from being shared with the parent injector. 236 * 237 * <p>No key may be bound by both an injector and one of its ancestors. This includes just-in-time 238 * bindings. The lone exception is the key for {@code Injector.class}, which is bound by each 239 * injector to itself. 240 * 241 * @since 2.0 242 */ createChildInjector(Module... modules)243 Injector createChildInjector(Module... modules); 244 245 /** 246 * Returns a map containing all scopes in the injector. The maps keys are scoping annotations 247 * like {@code Singleton.class}, and the values are scope instances, such as {@code 248 * Scopes.SINGLETON}. The returned map is immutable. 249 * 250 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 251 * 252 * @since 3.0 253 */ getScopeBindings()254 Map<Class<? extends Annotation>, Scope> getScopeBindings(); 255 256 /** 257 * Returns a set containing all type converter bindings in the injector. The returned set is 258 * immutable. 259 * 260 * <p>This method is part of the Guice SPI and is intended for use by tools and extensions. 261 * 262 * @since 3.0 263 */ getTypeConverterBindings()264 Set<TypeConverterBinding> getTypeConverterBindings(); 265 } 266