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
17package com.google.inject;
18
19import com.google.inject.spi.TypeConverterBinding;
20
21import java.lang.annotation.Annotation;
22import java.util.List;
23import java.util.Map;
24import 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 */
56public 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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
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   */
264  Set<TypeConverterBinding> getTypeConverterBindings();
265}
266