com.google.inject.Injector Maven / Gradle / Ivy
/*
* Copyright (C) 2006 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.inject;
import com.google.inject.spi.Element;
import com.google.inject.spi.InjectionPoint;
import com.google.inject.spi.TypeConverterBinding;
import java.lang.annotation.Annotation;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* Builds the graphs of objects that make up your application. The injector tracks the dependencies
* for each type and uses bindings to inject them. This is the core of Guice, although you rarely
* interact with it directly. This "behind-the-scenes" operation is what distinguishes dependency
* injection from its cousin, the service locator pattern.
*
* Contains several default bindings:
*
*
* - This {@link Injector} instance itself
*
- A {@code Provider
} for each binding of type {@code T}
* - The {@link java.util.logging.Logger} for the class being injected
*
- The {@link Stage} in which the Injector was created
*
*
* Injectors are created using the facade class {@link Guice}.
*
* An injector can also {@link #injectMembers(Object) inject the dependencies} of
* already-constructed instances. This can be used to interoperate with objects created by other
* frameworks or services.
*
*
Injectors can be {@link #createChildInjector(Iterable) hierarchical}. Child injectors inherit
* the configuration of their parent injectors, but the converse does not hold.
*
*
The injector's {@link #getBindings() internal bindings} are available for introspection. This
* enables tools and extensions to operate on an injector reflectively.
*
* @author [email protected] (Bob Lee)
* @author [email protected] (Jesse Wilson)
*/
public interface Injector {
/**
* Injects dependencies into the fields and methods of {@code instance}. Ignores the presence or
* absence of an injectable constructor.
*
*
Whenever Guice creates an instance, it performs this injection automatically (after first
* performing constructor injection), so if you're able to let Guice create all your objects for
* you, you'll never need to use this method.
*
* @param instance to inject members on
* @see Binder#getMembersInjector(Class) for a preferred alternative that supports checks before
* run time
*/
void injectMembers(Object instance);
/**
* Returns the members injector used to inject dependencies into methods and fields on instances
* of the given type {@code T}.
*
* @param typeLiteral type to get members injector for
* @see Binder#getMembersInjector(TypeLiteral) for an alternative that offers up front error
* detection
* @since 2.0
*/
MembersInjector getMembersInjector(TypeLiteral typeLiteral);
/**
* Returns the members injector used to inject dependencies into methods and fields on instances
* of the given type {@code T}. When feasible, use {@link Binder#getMembersInjector(TypeLiteral)}
* instead to get increased up front error detection.
*
* @param type type to get members injector for
* @see Binder#getMembersInjector(Class) for an alternative that offers up front error detection
* @since 2.0
*/
MembersInjector getMembersInjector(Class type);
/**
* Returns this injector's explicit bindings.
*
* The returned map does not include bindings inherited from a {@link #getParent() parent
* injector}, should one exist. The returned map is guaranteed to iterate (for example, with its
* {@link Map#entrySet()} iterator) in the order of insertion. In other words, the order in which
* bindings appear in user Modules.
*
*
This method is part of the Guice SPI and is intended for use by tools and extensions.
*/
Map, Binding> getBindings();
/**
* Returns a snapshot of this injector's bindings, both explicit and
* just-in-time. The returned map is immutable; it contains only the bindings that were
* present when {@code getAllBindings()} was invoked. Just-in-time bindings are only present if
* they have been requested at least once. Subsequent calls may return a map with additional
* just-in-time bindings.
*
* The returned map does not include bindings inherited from a {@link #getParent() parent
* injector}, should one exist.
*
*
This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 3.0
*/
Map, Binding> getAllBindings();
/**
* Returns the binding for the given injection key. This will be an explicit bindings if the key
* was bound explicitly by a module, or an implicit binding otherwise. The implicit binding will
* be created if necessary.
*
* This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @throws ConfigurationException if this injector cannot find or create the binding.
*/
Binding getBinding(Key key);
/**
* Returns the binding for the given type. This will be an explicit bindings if the injection key
* was bound explicitly by a module, or an implicit binding otherwise. The implicit binding will
* be created if necessary.
*
* This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @throws ConfigurationException if this injector cannot find or create the binding.
* @since 2.0
*/
Binding getBinding(Class type);
/**
* Returns the binding if it already exists, or null if does not exist. Unlike {@link
* #getBinding(Key)}, this does not attempt to create just-in-time bindings for keys that aren't
* bound.
*
* This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 3.0
*/
Binding getExistingBinding(Key key);
/**
* Returns all explicit bindings for {@code type}.
*
* This method is part of the Guice SPI and is intended for use by tools and extensions.
*/
List> findBindingsByType(TypeLiteral type);
/**
* Returns the provider used to obtain instances for the given injection key. When feasible, avoid
* using this method, in favor of having Guice inject your dependencies ahead of time.
*
* @throws ConfigurationException if this injector cannot find or create the provider.
* @see Binder#getProvider(Key) for an alternative that offers up front error detection
*/
Provider getProvider(Key key);
/**
* Returns the provider used to obtain instances for the given type. When feasible, avoid using
* this method, in favor of having Guice inject your dependencies ahead of time.
*
* @throws ConfigurationException if this injector cannot find or create the provider.
* @see Binder#getProvider(Class) for an alternative that offers up front error detection
*/
Provider getProvider(Class type);
/**
* Returns the appropriate instance for the given injection key; equivalent to {@code
* getProvider(key).get()}. When feasible, avoid using this method, in favor of having Guice
* inject your dependencies ahead of time.
*
* @throws ConfigurationException if this injector cannot find or create the provider.
* @throws ProvisionException if there was a runtime failure while providing an instance.
*/
T getInstance(Key key);
/**
* Returns the appropriate instance for the given injection type; equivalent to {@code
* getProvider(type).get()}. When feasible, avoid using this method, in favor of having Guice
* inject your dependencies ahead of time.
*
* @throws ConfigurationException if this injector cannot find or create the provider.
* @throws ProvisionException if there was a runtime failure while providing an instance.
*/
T getInstance(Class type);
/**
* Returns this injector's parent, or {@code null} if this is a top-level injector.
*
* @since 2.0
*/
Injector getParent();
/**
* Returns a new injector that inherits all state from this injector. All bindings, scopes,
* interceptors and type converters are inherited -- they are visible to the child injector.
* Elements of the child injector are not visible to its parent.
*
* Just-in-time bindings created for child injectors will be created in an ancestor injector
* whenever possible. This allows for scoped instances to be shared between injectors. Use
* explicit bindings to prevent bindings from being shared with the parent injector. Optional
* injections in just-in-time bindings (created in the parent injector) may be silently ignored if
* the optional dependencies are from the child injector.
*
*
No key may be bound by both an injector and one of its ancestors. This includes just-in-time
* bindings. The lone exception is the key for {@code Injector.class}, which is bound by each
* injector to itself.
*
*
When using hierarchical injectors (via {@link Binder#newPrivateBinder}, {@link
* Binder#PrivateModule}, or {@link Injector#createChildInjector}), extra care is required to
* ensure that bindings are associated with the correct injector. Statements that are otherwise
* unnecessary - such as {code bind(ServiceImpl.class);} - become critical to associate the
* binding with this particular injector, otherwise Guice may promote the binding to an
* ancestor injector. Linked bindings such as {@code bind(Service.class).to(ServiceImpl.class);}
* will only associate the {@code Service} binding with the current injector; {@code ServiceImpl}
* will still be promoted to an ancestor injector without an explicit {@code
* bind(ServiceImpl.class);} statement.
*
* @since 2.0
*/
Injector createChildInjector(Iterable modules);
/**
* Returns a new injector that inherits all state from this injector. All bindings, scopes,
* interceptors and type converters are inherited -- they are visible to the child injector.
* Elements of the child injector are not visible to its parent.
*
*
Just-in-time bindings created for child injectors will be created in an ancestor injector
* whenever possible. This allows for scoped instances to be shared between injectors. Use
* explicit bindings to prevent bindings from being shared with the parent injector.
*
*
No key may be bound by both an injector and one of its ancestors. This includes just-in-time
* bindings. The lone exception is the key for {@code Injector.class}, which is bound by each
* injector to itself.
*
* @since 2.0
*/
Injector createChildInjector(Module... modules);
/**
* Returns a map containing all scopes in the injector. The maps keys are scoping annotations like
* {@code Singleton.class}, and the values are scope instances, such as {@code Scopes.SINGLETON}.
* The returned map is immutable.
*
*
This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 3.0
*/
Map, Scope> getScopeBindings();
/**
* Returns a set containing all type converter bindings in the injector. The returned set is
* immutable.
*
* This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 3.0
*/
Set getTypeConverterBindings();
/**
* Returns the elements that make up this injector. Note that not all kinds of elements are
* returned.
*
* The returned list does not include elements inherited from a {@link #getParent() parent
* injector}, should one exist.
*
*
The returned list is immutable; it contains only the elements that were present when {@link
* #getElements} was invoked. Subsequent calls may return a list with additional elements.
*
*
The returned list does not include data inherited from a {@link #getParent() parent
* injector}, should one exist.
*
*
This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 4.2.3
*/
List getElements();
/**
* Returns the injection points created for calls to {@link #getMembersInjector} (either directly
* or indirectly, e.g. through {@link #injectMembers}.
*
* This excludes any injection points from elements (which are accessible from each element via
* the SPI), unless {@link #getMembersInjector} or {@link #injectMembers} were also called for the
* same key.
*
*
The returned multimap does not include data inherited from a {@link #getParent() parent
* injector}, should one exist.
*
*
This method is part of the Guice SPI and is intended for use by tools and extensions.
*
* @since 4.2.3
*/
Map, List> getAllMembersInjectorInjectionPoints();
}