google/inject/Binder.java

/*
 * Copyright (C) 2007 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.binder.AnnotatedBindingBuilder;
import com.google.inject.binder.AnnotatedConstantBindingBuilder;
import com.google.inject.binder.LinkedBindingBuilder;
import com.google.inject.matcher.Matcher;
import com.google.inject.spi.Dependency;
import com.google.inject.spi.Message;
import com.google.inject.spi.ModuleAnnotatedMethodScanner;
import com.google.inject.spi.ProvisionListener;
import com.google.inject.spi.TypeConverter;
import com.google.inject.spi.TypeListener;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

/**
 * Collects configuration information (primarily <i>bindings</i>) which will be used to create an
 * {@link Injector}. Guice provides this object to your application's {@link Module} implementors so
 * they may each contribute their own bindings and other registrations.
 *
 * <h3>The Guice Binding EDSL</h3>
 *
 * Guice uses an <i>embedded domain-specific language</i>, or EDSL, to help you create bindings
 * simply and readably. This approach is great for overall usability, but it does come with a small
 * cost: <b>it is difficult to learn how to use the Binding EDSL by reading method-level
 * javadocs</b>. Instead, you should consult the series of examples below. To save space, these
 * examples omit the opening {@code binder}, just as you will if your module extends {@link
 * AbstractModule}.
 *
 * <pre>
 *     bind(ServiceImpl.class);</pre>
 *
 * This statement does essentially nothing; it "binds the {@code ServiceImpl} class to itself" and
 * does not change Guice's default behavior. You may still want to use this if you prefer your
 * {@link Module} class to serve as an explicit <i>manifest</i> for the services it provides. Also,
 * in rare cases, Guice may be unable to validate a binding at injector creation time unless it is
 * given explicitly.
 *
 * <pre>
 *     bind(Service.class).to(ServiceImpl.class);</pre>
 *
 * Specifies that a request for a {@code Service} instance with no binding annotations should be
 * treated as if it were a request for a {@code ServiceImpl} instance. This <i>overrides</i> the
 * function of any {@link ImplementedBy @ImplementedBy} or {@link ProvidedBy @ProvidedBy}
 * annotations found on {@code Service}, since Guice will have already "moved on" to {@code
 * ServiceImpl} before it reaches the point when it starts looking for these annotations.
 *
 * <pre>
 *     bind(Service.class).toProvider(ServiceProvider.class);</pre>
 *
 * In this example, {@code ServiceProvider} must extend or implement {@code Provider<Service>}. This
 * binding specifies that Guice should resolve an unannotated injection request for {@code Service}
 * by first resolving an instance of {@code ServiceProvider} in the regular way, then calling {@link
 * Provider#get get()} on the resulting Provider instance to obtain the {@code Service} instance.
 *
 * <p>The {@link Provider} you use here does not have to be a "factory"; that is, a provider which
 * always <i>creates</i> each instance it provides. However, this is generally a good practice to
 * follow. You can then use Guice's concept of {@link Scope scopes} to guide when creation should
 * happen -- "letting Guice work for you".
 *
 * <pre>
 *     bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);</pre>
 *
 * Like the previous example, but only applies to injection requests that use the binding annotation
 * {@code @Red}. If your module also includes bindings for particular <i>values</i> of the
 * {@code @Red} annotation (see below), then this binding will serve as a "catch-all" for any values
 * of {@code @Red} that have no exact match in the bindings.
 *
 * <pre>
 *     bind(ServiceImpl.class).in(Singleton.class);
 *     // or, alternatively
 *     bind(ServiceImpl.class).in(Scopes.SINGLETON);</pre>
 *
 * Either of these statements places the {@code ServiceImpl} class into singleton scope. Guice will
 * create only one instance of {@code ServiceImpl} and will reuse it for all injection requests of
 * this type. Note that it is still possible to bind another instance of {@code ServiceImpl} if the
 * second binding is qualified by an annotation as in the previous example. Guice is not overly
 * concerned with <i>preventing</i> you from creating multiple instances of your "singletons", only
 * with <i>enabling</i> your application to share only one instance if that's all you tell Guice you
 * need.
 *
 * <p><b>Note:</b> a scope specified in this way <i>overrides</i> any scope that was specified with
 * an annotation on the {@code ServiceImpl} class.
 *
 * <p>Besides {@link Singleton}/{@link Scopes#SINGLETON}, there are servlet-specific scopes
 * available in {@code com.google.inject.servlet.ServletScopes}, and your Modules can contribute
 * their own custom scopes for use here as well.
 *
 * <pre>
 *     bind(new TypeLiteral&lt;PaymentService&lt;CreditCard>>() {})
 *         .to(CreditCardPaymentService.class);</pre>
 *
 * This admittedly odd construct is the way to bind a parameterized type. It tells Guice how to
 * honor an injection request for an element of type {@code PaymentService<CreditCard>}. The class
 * {@code CreditCardPaymentService} must implement the {@code PaymentService<CreditCard>} interface.
 * Guice cannot currently bind or inject a generic type, such as {@code Set<E>}; all type parameters
 * must be fully specified.
 *
 * <pre>
 *     bind(Service.class).toInstance(new ServiceImpl());
 *     // or, alternatively
 *     bind(Service.class).toInstance(SomeLegacyRegistry.getService());</pre>
 *
 * In this example, your module itself, <i>not Guice</i>, takes responsibility for obtaining a
 * {@code ServiceImpl} instance, then asks Guice to always use this single instance to fulfill all
 * {@code Service} injection requests. When the {@link Injector} is created, it will automatically
 * perform field and method injection for this instance, but any injectable constructor on {@code
 * ServiceImpl} is simply ignored. Note that using this approach results in "eager loading" behavior
 * that you can't control.
 *
 * <pre>
 *     bindConstant().annotatedWith(ServerHost.class).to(args[0]);</pre>
 *
 * Sets up a constant binding. Constant injections must always be annotated. When a constant
 * binding's value is a string, it is eligile for conversion to all primitive types, to {@link
 * Enum#valueOf(Class, String) all enums}, and to {@link Class#forName class literals}. Conversions
 * for other types can be configured using {@link #convertToTypes(Matcher, TypeConverter)
 * convertToTypes()}.
 *
 * <pre>
 *   {@literal @}Color("red") Color red; // A member variable (field)
 *    . . .
 *     red = MyModule.class.getDeclaredField("red").getAnnotation(Color.class);
 *     bind(Service.class).annotatedWith(red).to(RedService.class);</pre>
 *
 * If your binding annotation has parameters you can apply different bindings to different specific
 * values of your annotation. Getting your hands on the right instance of the annotation is a bit of
 * a pain -- one approach, shown above, is to apply a prototype annotation to a field in your module
 * class, so that you can read this annotation instance and give it to Guice.
 *
 * <pre>
 *     bind(Service.class)
 *         .annotatedWith(Names.named("blue"))
 *         .to(BlueService.class);</pre>
 *
 * Differentiating by names is a common enough use case that we provided a standard annotation,
 * {@link com.google.inject.name.Named @Named}. Because of Guice's library support, binding by name
 * is quite easier than in the arbitrary binding annotation case we just saw. However, remember that
 * these names will live in a single flat namespace with all the other names used in your
 * application.
 *
 * <pre>
 *     Constructor<T> loneCtor = getLoneCtorFromServiceImplViaReflection();
 *     bind(ServiceImpl.class)
 *         .toConstructor(loneCtor);</pre>
 *
 * In this example, we directly tell Guice which constructor to use in a concrete class
 * implementation. It means that we do not need to place {@literal @}Inject on any of the
 * constructors and that Guice treats the provided constructor as though it were annotated so. It is
 * useful for cases where you cannot modify existing classes and is a bit simpler than using a
 * {@link Provider}.
 *
 * <p>The above list of examples is far from exhaustive. If you can think of how the concepts of one
 * example might coexist with the concepts from another, you can most likely weave the two together.
 * If the two concepts make no sense with each other, you most likely won't be able to do it. In a
 * few cases Guice will let something bogus slip by, and will then inform you of the problems at
 * runtime, as soon as you try to create your Injector.
 *
 * <p>The other methods of Binder such as {@link #bindScope}, {@link #bindInterceptor}, {@link
 * #install}, {@link #requestStaticInjection}, {@link #addError} and {@link #currentStage} are not
 * part of the Binding EDSL; you can learn how to use these in the usual way, from the method
 * documentation.
 *
 * @author crazybob@google.com (Bob Lee)
 * @author jessewilson@google.com (Jesse Wilson)
 * @author kevinb@google.com (Kevin Bourrillion)
 */
public interface Binder {

  /*if[AOP]*/
  /**
   * Binds method interceptor[s] to methods matched by class and method matchers. A method is
   * eligible for interception if:
   *
   * <ul>
   * <li>Guice created the instance the method is on
   * <li>Neither the enclosing type nor the method is final
   * <li>And the method is package-private, protected, or public
   * </ul>
   *
   * @param classMatcher matches classes the interceptor should apply to. For example: {@code
   *     only(Runnable.class)}.
   * @param methodMatcher matches methods the interceptor should apply to. For example: {@code
   *     annotatedWith(Transactional.class)}.
   * @param interceptors to bind. The interceptors are called in the order they are given.
   */
  void bindInterceptor(
      Matcher<? super Class<?>> classMatcher,
      Matcher<? super Method> methodMatcher,
      org.aopalliance.intercept.MethodInterceptor... interceptors);
  /*end[AOP]*/

  /** Binds a scope to an annotation. */
  void bindScope(Class<? extends Annotation> annotationType, Scope scope);

  /** See the EDSL examples at {@link Binder}. */
  <T> LinkedBindingBuilder<T> bind(Key<T> key);

  /** See the EDSL examples at {@link Binder}. */
  <T> AnnotatedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);

  /** See the EDSL examples at {@link Binder}. */
  <T> AnnotatedBindingBuilder<T> bind(Class<T> type);

  /** See the EDSL examples at {@link Binder}. */
  AnnotatedConstantBindingBuilder bindConstant();

  /**
   * Upon successful creation, the {@link Injector} will inject instance fields and methods of the
   * given object.
   *
   * @param type of instance
   * @param instance for which members will be injected
   * @since 2.0
   */
  <T> void requestInjection(TypeLiteral<T> type, T instance);

  /**
   * Upon successful creation, the {@link Injector} will inject instance fields and methods of the
   * given object.
   *
   * @param instance for which members will be injected
   * @since 2.0
   */
  void requestInjection(Object instance);

  /**
   * Upon successful creation, the {@link Injector} will inject static fields and methods in the
   * given classes.
   *
   * @param types for which static members will be injected
   */
  void requestStaticInjection(Class<?>... types);

  /** Uses the given module to configure more bindings. */
  void install(Module module);

  /** Gets the current stage. */
  Stage currentStage();

  /**
   * Records an error message which will be presented to the user at a later time. Unlike throwing
   * an exception, this enable us to continue configuring the Injector and discover more errors.
   * Uses {@link String#format(String, Object[])} to insert the arguments into the message.
   */
  void addError(String message, Object... arguments);

  /**
   * Records an exception, the full details of which will be logged, and the message of which will
   * be presented to the user at a later time. If your Module calls something that you worry may
   * fail, you should catch the exception and pass it into this.
   */
  void addError(Throwable t);

  /**
   * Records an error message to be presented to the user at a later time.
   *
   * @since 2.0
   */
  void addError(Message message);

  /**
   * Returns the provider used to obtain instances for the given injection key. The returned
   * provider will not be valid until the {@link Injector} has been created. The provider will throw
   * an {@code IllegalStateException} if you try to use it beforehand.
   *
   * @since 2.0
   */
  <T> Provider<T> getProvider(Key<T> key);

  /**
   * Returns the provider used to obtain instances for the given injection key. The returned
   * provider will be attached to the injection point and will follow the nullability specified in
   * the dependency. Additionally, the returned provider will not be valid until the {@link
   * Injector} has been created. The provider will throw an {@code IllegalStateException} if you try
   * to use it beforehand.
   *
   * @since 4.0
   */
  <T> Provider<T> getProvider(Dependency<T> dependency);

  /**
   * Returns the provider used to obtain instances for the given injection type. The returned
   * provider will not be valid until the {@link Injector} has been created. The provider will throw
   * an {@code IllegalStateException} if you try to use it beforehand.
   *
   * @since 2.0
   */
  <T> Provider<T> getProvider(Class<T> type);

  /**
   * Returns the members injector used to inject dependencies into methods and fields on instances
   * of the given type {@code T}. The returned members injector will not be valid until the main
   * {@link Injector} has been created. The members injector will throw an {@code
   * IllegalStateException} if you try to use it beforehand.
   *
   * @param typeLiteral type to get members injector for
   * @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}. The returned members injector will not be valid until the main
   * {@link Injector} has been created. The members injector will throw an {@code
   * IllegalStateException} if you try to use it beforehand.
   *
   * @param type type to get members injector for
   * @since 2.0
   */
  <T> MembersInjector<T> getMembersInjector(Class<T> type);

  /**
   * Binds a type converter. The injector will use the given converter to convert string constants
   * to matching types as needed.
   *
   * @param typeMatcher matches types the converter can handle
   * @param converter converts values
   * @since 2.0
   */
  void convertToTypes(Matcher<? super TypeLiteral<?>> typeMatcher, TypeConverter converter);

  /**
   * Registers a listener for injectable types. Guice will notify the listener when it encounters
   * injectable types matched by the given type matcher.
   *
   * @param typeMatcher that matches injectable types the listener should be notified of
   * @param listener for injectable types matched by typeMatcher
   * @since 2.0
   */
  void bindListener(Matcher<? super TypeLiteral<?>> typeMatcher, TypeListener listener);

  /**
   * Registers listeners for provisioned objects. Guice will notify the listeners just before and
   * after the object is provisioned. Provisioned objects that are also injectable (everything
   * except objects provided through Providers) can also be notified through TypeListeners
   * registered in {@link #bindListener}.
   *
   * @param bindingMatcher that matches bindings of provisioned objects the listener should be
   *     notified of
   * @param listeners for provisioned objects matched by bindingMatcher
   * @since 4.0
   */
  void bindListener(Matcher<? super Binding<?>> bindingMatcher, ProvisionListener... listeners);

  /**
   * Returns a binder that uses {@code source} as the reference location for configuration errors.
   * This is typically a {@link StackTraceElement} for {@code .java} source but it could any binding
   * source, such as the path to a {@code .properties} file.
   *
   * @param source any object representing the source location and has a concise {@link
   *     Object#toString() toString()} value
   * @return a binder that shares its configuration with this binder
   * @since 2.0
   */
  Binder withSource(Object source);

  /**
   * Returns a binder that skips {@code classesToSkip} when identify the calling code. The caller's
   * {@link StackTraceElement} is used to locate the source of configuration errors.
   *
   * @param classesToSkip library classes that create bindings on behalf of their clients.
   * @return a binder that shares its configuration with this binder.
   * @since 2.0
   */
  Binder skipSources(Class... classesToSkip);

  /**
   * Creates a new private child environment for bindings and other configuration. The returned
   * binder can be used to add and configuration information in this environment. See {@link
   * PrivateModule} for details.
   *
   * @return a binder that inherits configuration from this binder. Only exposed configuration on
   *     the returned binder will be visible to this binder.
   * @since 2.0
   */
  PrivateBinder newPrivateBinder();

  /**
   * Instructs the Injector that bindings must be listed in a Module in order to be injected.
   * Classes that are not explicitly bound in a module cannot be injected. Bindings created through
   * a linked binding (<code>bind(Foo.class).to(FooImpl.class)</code>) are allowed, but the implicit
   * binding (<code>FooImpl</code>) cannot be directly injected unless it is also explicitly bound (
   * <code>bind(FooImpl.class)</code>).
   *
   * <p>Tools can still retrieve bindings for implicit bindings (bindings created through a linked
   * binding) if explicit bindings are required, however {@link Binding#getProvider} will fail.
   *
   * <p>By default, explicit bindings are not required.
   *
   * <p>If a parent injector requires explicit bindings, then all child injectors (and private
   * modules within that injector) also require explicit bindings. If a parent does not require
   * explicit bindings, a child injector or private module may optionally declare itself as
   * requiring explicit bindings. If it does, the behavior is limited only to that child or any
   * grandchildren. No siblings of the child will require explicit bindings.
   *
   * <p>In the absence of an explicit binding for the target, linked bindings in child injectors
   * create a binding for the target in the parent. Since this behavior can be surprising, it causes
   * an error instead if explicit bindings are required. To avoid this error, add an explicit
   * binding for the target, either in the child or the parent.
   *
   * @since 3.0
   */
  void requireExplicitBindings();

  /**
   * Prevents Guice from injecting dependencies that form a cycle, unless broken by a {@link
   * Provider}. By default, circular dependencies are not disabled.
   *
   * <p>If a parent injector disables circular dependencies, then all child injectors (and private
   * modules within that injector) also disable circular dependencies. If a parent does not disable
   * circular dependencies, a child injector or private module may optionally declare itself as
   * disabling circular dependencies. If it does, the behavior is limited only to that child or any
   * grandchildren. No siblings of the child will disable circular dependencies.
   *
   * @since 3.0
   */
  void disableCircularProxies();

  /**
   * Requires that a {@literal @}{@link Inject} annotation exists on a constructor in order for
   * Guice to consider it an eligible injectable class. By default, Guice will inject classes that
   * have a no-args constructor if no {@literal @}{@link Inject} annotation exists on any
   * constructor.
   *
   * <p>If the class is bound using {@link LinkedBindingBuilder#toConstructor}, Guice will still
   * inject that constructor regardless of annotations.
   *
   * @since 4.0
   */
  void requireAtInjectOnConstructors();

  /**
   * Requires that Guice finds an exactly matching binding annotation. This disables the error-prone
   * feature in Guice where it can substitute a binding for <code>{@literal @}Named Foo</code> when
   * attempting to inject <code>{@literal @}Named("foo") Foo</code>.
   *
   * @since 4.0
   */
  void requireExactBindingAnnotations();

  /**
   * Adds a scanner that will look in all installed modules for annotations the scanner can parse,
   * and binds them like {@literal @}Provides methods. Scanners apply to all modules installed in
   * the injector. Scanners installed in child injectors or private modules do not impact modules in
   * siblings or parents, however scanners installed in parents do apply to all child injectors and
   * private modules.
   *
   * @since 4.0
   */
  void scanModulesForAnnotatedMethods(ModuleAnnotatedMethodScanner scanner);
}