All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.inject.Injector Maven / Gradle / Ivy

There is a newer version: 3.0.0-alpha-3
Show newest version
/*
 * 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(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy