src/com/google/inject/Injector.java - platform/external/guice - Git at Google

 /**
  * 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 java.lang.annotation.Annotation;
 import java.util.List;
 import java.util.Map;

 /**
  * 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.
  *
  * <p>Contains several default bindings:
  *
  * <ul>
  * <li>This {@link Injector} instance itself
  * <li>A {@code Provider<T>} for each binding of type {@code T}
  * <li>The {@link java.util.logging.Logger} for the class being injected
  * <li>The {@link Stage} in which the Injector was created
  * </ul>
  *
  * Injectors are created using the facade class {@link Guice}.
  *
  * <p>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.
  *
  * <p>Injectors can be {@link #createChildInjector(Iterable) hierarchical}. Child injectors inherit
  * the configuration of their parent injectors, but the converse does not hold.
  *
  * <p>The injector's {@link #getBindings() internal bindings} are available for introspection. This
  * enables tools and extensions to operate on an injector reflectively.
  *
  * @author crazybob@google.com (Bob Lee)
  * @author jessewilson@google.com (Jesse Wilson)
  */
 public interface Injector {

   /**
    * Injects dependencies into the fields and methods of {@code instance}. Ignores the presence or
    * absence of an injectable constructor.
    *
    * <p>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
    */
   <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> 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
    */
   <T> MembersInjector<T> getMembersInjector(Class<T> type);

   /**
    * Returns this injector's <strong>explicit</strong> bindings.
    *
    * <p>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.
    *
    * <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
    */
   Map<Key<?>, Binding<?>> getBindings();

   /**
    * Returns a snapshot of this injector's bindings, <strong>both explicit and
    * just-in-time</strong>. The returned map is immutable; it contains only the bindings that were
    * present when {@code getAllBindings()} was invoked. Subsequent calls may return a map with
    * additional just-in-time bindings.
    *
    * <p>The returned map does not include bindings inherited from a {@link #getParent() parent
    * injector}, should one exist.
    *
    * <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
    */
   Map<Key<?>, 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.
    *
    * <p>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.
    */
   <T> Binding<T> getBinding(Key<T> 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.
    *
    * <p>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
    */
   <T> Binding<T> getBinding(Class<T> type);

   /**
    * Returns all explicit bindings for {@code type}.
    *
    * <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
    */
   <T> List<Binding<T>> findBindingsByType(TypeLiteral<T> 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
    */
   <T> Provider<T> getProvider(Key<T> 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
    */
   <T> Provider<T> getProvider(Class<T> 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> T getInstance(Key<T> 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> T getInstance(Class<T> 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.
    *
    * <p>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.
    *
    * <p>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(Iterable<? extends Module> 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.
    *
    * <p>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.
    *
    * <p>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.
    *
    * <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
    */
   Map<Class<? extends Annotation>, Scope> getScopeBindings();
 }
	/**
	* 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 java.lang.annotation.Annotation;
	import java.util.List;
	import java.util.Map;

	/**
	* 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.
	*
	* <p>Contains several default bindings:
	*
	* <ul>
	* <li>This {@link Injector} instance itself
	* <li>A {@code Provider<T>} for each binding of type {@code T}
	* <li>The {@link java.util.logging.Logger} for the class being injected
	* <li>The {@link Stage} in which the Injector was created
	* </ul>
	*
	* Injectors are created using the facade class {@link Guice}.
	*
	* <p>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.
	*
	* <p>Injectors can be {@link #createChildInjector(Iterable) hierarchical}. Child injectors inherit
	* the configuration of their parent injectors, but the converse does not hold.
	*
	* <p>The injector's {@link #getBindings() internal bindings} are available for introspection. This
	* enables tools and extensions to operate on an injector reflectively.
	*
	* @author crazybob@google.com (Bob Lee)
	* @author jessewilson@google.com (Jesse Wilson)
	*/
	public interface Injector {

	/**
	* Injects dependencies into the fields and methods of {@code instance}. Ignores the presence or
	* absence of an injectable constructor.
	*
	* <p>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
	*/
	<T> MembersInjector<T> getMembersInjector(TypeLiteral<T> 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
	*/
	<T> MembersInjector<T> getMembersInjector(Class<T> type);

	/**
	* Returns this injector's <strong>explicit</strong> bindings.
	*
	* <p>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.
	*
	* <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
	*/
	Map<Key<?>, Binding<?>> getBindings();

	/**
	* Returns a snapshot of this injector's bindings, <strong>both explicit and
	* just-in-time</strong>. The returned map is immutable; it contains only the bindings that were
	* present when {@code getAllBindings()} was invoked. Subsequent calls may return a map with
	* additional just-in-time bindings.
	*
	* <p>The returned map does not include bindings inherited from a {@link #getParent() parent
	* injector}, should one exist.
	*
	* <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
	*/
	Map<Key<?>, 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.
	*
	* <p>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.
	*/
	<T> Binding<T> getBinding(Key<T> 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.
	*
	* <p>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
	*/
	<T> Binding<T> getBinding(Class<T> type);

	/**
	* Returns all explicit bindings for {@code type}.
	*
	* <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
	*/
	<T> List<Binding<T>> findBindingsByType(TypeLiteral<T> 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
	*/
	<T> Provider<T> getProvider(Key<T> 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
	*/
	<T> Provider<T> getProvider(Class<T> 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> T getInstance(Key<T> 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> T getInstance(Class<T> 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.
	*
	* <p>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.
	*
	* <p>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(Iterable<? extends Module> 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.
	*
	* <p>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.
	*
	* <p>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.
	*
	* <p>This method is part of the Guice SPI and is intended for use by tools and extensions.
	*/
	Map<Class<? extends Annotation>, Scope> getScopeBindings();
	}