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