inject/assistedinject/FactoryModuleBuilder.java

/**
 * Copyright (C) 2009 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.assistedinject;

import com.google.inject.AbstractModule;
import com.google.inject.Key;
import com.google.inject.Module;
import com.google.inject.Provider;
import com.google.inject.TypeLiteral;

import java.lang.annotation.Annotation;

/**
 * Provides a factory that combines the caller's arguments with injector-supplied values to
 * construct objects.
 *
 * <h3>Defining a factory</h3>
 * Create an interface whose methods return the constructed type, or any of its supertypes. The
 * method's parameters are the arguments required to build the constructed type.
 *
 * <pre>public interface PaymentFactory {
 *   Payment create(Date startDate, Money amount);
 * }</pre>
 *
 * You can name your factory methods whatever you like, such as <i>create</i>, <i>createPayment</i>
 * or <i>newPayment</i>.
 *
 * <h3>Creating a type that accepts factory parameters</h3>
 * {@code constructedType} is a concrete class with an {@literal @}{@link com.google.inject.Inject
 * Inject}-annotated constructor. In addition to injector-supplied parameters, the constructor
 * should have parameters that match each of the factory method's parameters. Each factory-supplied
 * parameter requires an {@literal @}{@link Assisted} annotation. This serves to document that the
 * parameter is not bound by your application's modules.
 *
 * <pre>public class RealPayment implements Payment {
 *   {@literal @}Inject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *      <strong>{@literal @}Assisted Date startDate</strong>,
 *      <strong>{@literal @}Assisted Money amount</strong>) {
 *     ...
 *   }
 * }</pre>
 *
 * <h3>Multiple factory methods for the same type</h3>
 * If the factory contains many methods that return the same type, you can create multiple
 * constructors in your concrete class, each constructor marked with with
 * {@literal @}{@link AssistedInject}, in order to match the different parameters types of the
 * factory methods.
 *
 * <pre>public interface PaymentFactory {
 *    Payment create(Date startDate, Money amount);
 *    Payment createWithoutDate(Money amount);
 * }
 *
 * public class RealPayment implements Payment {
 *  {@literal @}AssistedInject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *     <strong>{@literal @}Assisted Date startDate</strong>,
 *     <strong>{@literal @}Assisted Money amount</strong>) {
 *     ...
 *   }
 *
 *  {@literal @}AssistedInject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *     <strong>{@literal @}Assisted Money amount</strong>) {
 *     ...
 *   }
 * }</pre>
 *
 * <h3>Configuring simple factories</h3>
 * In your {@link Module module}, install a {@code FactoryModuleBuilder} that creates the
 * factory:
 *
 * <pre>install(new FactoryModuleBuilder()
 *     .implement(Payment.class, RealPayment.class)
 *     .build(PaymentFactory.class));</pre>
 *
 * As a side-effect of this binding, Guice will inject the factory to initialize it for use. The
 * factory cannot be used until the injector has been initialized.
 *
 * <h3>Configuring complex factories</h3>
 * Factories can create an arbitrary number of objects, one per each method.  Each factory
 * method can be configured using <code>.implement</code>.
 *
 * <pre>public interface OrderFactory {
 *    Payment create(Date startDate, Money amount);
 *    Shipment create(Customer customer, Item item);
 *    Receipt create(Payment payment, Shipment shipment);
 * }
 *
 * [...]
 *
 * install(new FactoryModuleBuilder()
 *     .implement(Payment.class, RealPayment.class)
 *     // excluding .implement for Shipment means the implementation class
 *     // will be 'Shipment' itself, which is legal if it's not an interface.
 *     .implement(Receipt.class, RealReceipt.class)
 *     .build(OrderFactory.class));</pre>
 * </pre>
 *
 * <h3>Using the factory</h3>
 * Inject your factory into your application classes. When you use the factory, your arguments
 * will be combined with values from the injector to construct an instance.
 *
 * <pre>public class PaymentAction {
 *   {@literal @}Inject private PaymentFactory paymentFactory;
 *
 *   public void doPayment(Money amount) {
 *     Payment payment = paymentFactory.create(new Date(), amount);
 *     payment.apply();
 *   }
 * }</pre>
 *
 * <h3>Making parameter types distinct</h3>
 * The types of the factory method's parameters must be distinct. To use multiple parameters of
 * the same type, use a named {@literal @}{@link Assisted} annotation to disambiguate the
 * parameters. The names must be applied to the factory method's parameters:
 *
 * <pre>public interface PaymentFactory {
 *   Payment create(
 *       <strong>{@literal @}Assisted("startDate")</strong> Date startDate,
 *       <strong>{@literal @}Assisted("dueDate")</strong> Date dueDate,
 *       Money amount);
 * } </pre>
 *
 * ...and to the concrete type's constructor parameters:
 *
 * <pre>public class RealPayment implements Payment {
 *   {@literal @}Inject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *      <strong>{@literal @}Assisted("startDate")</strong> Date startDate,
 *      <strong>{@literal @}Assisted("dueDate")</strong> Date dueDate,
 *      <strong>{@literal @}Assisted</strong> Money amount) {
 *     ...
 *   }
 * }</pre>
 *
 * <h3>Values are created by Guice</h3>
 * Returned factories use child injectors to create values. The values are eligible for method
 * interception. In addition, {@literal @}{@literal Inject} members will be injected before they are
 * returned.
 *
 * <h3>More configuration options</h3>
 * In addition to simply specifying an implementation class for any returned type, factories' return
 * values can be automatic or can be configured to use annotations:
 * <p/>
 * If you just want to return the types specified in the factory, do not configure any
 * implementations:
 *
 * <pre>public interface FruitFactory {
 *   Apple getApple(Color color);
 * }
 * ...
 * protected void configure() {
 *   install(new FactoryModuleBuilder().build(FruitFactory.class));
 * }</pre>
 *
 * Note that any type returned by the factory in this manner needs to be an implementation class.
 * <p/>
 * To return two different implementations for the same interface from your factory, use binding
 * annotations on your return types:
 *
 * <pre>interface CarFactory {
 *   {@literal @}Named("fast") Car getFastCar(Color color);
 *   {@literal @}Named("clean") Car getCleanCar(Color color);
 * }
 * ...
 * protected void configure() {
 *   install(new FactoryModuleBuilder()
 *       .implement(Car.class, Names.named("fast"), Porsche.class)
 *       .implement(Car.class, Names.named("clean"), Prius.class)
 *       .build(CarFactory.class));
 * }</pre>
 *
 * <h3>Implementation limitations</h3>
 * As a limitation of the implementation, it is prohibited to declare a factory method that
 * accepts a {@code Provider} as one of its arguments.
 *
 * @since 3.0
 * @author schmitt@google.com (Peter Schmitt)
 */
public final class FactoryModuleBuilder {

  private final BindingCollector bindings = new BindingCollector();

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source, Class<? extends T> target) {
    return implement(source, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source, TypeLiteral<? extends T> target) {
    return implement(TypeLiteral.get(source), target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source, Class<? extends T> target) {
    return implement(source, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source,
      TypeLiteral<? extends T> target) {
    return implement(Key.get(source), target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source, Annotation annotation,
      Class<? extends T> target) {
    return implement(source, annotation, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source, Annotation annotation,
      TypeLiteral<? extends T> target) {
    return implement(TypeLiteral.get(source), annotation, target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source, Annotation annotation,
      Class<? extends T> target) {
    return implement(source, annotation, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source, Annotation annotation,
      TypeLiteral<? extends T> target) {
    return implement(Key.get(source, annotation), target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source,
      Class<? extends Annotation> annotationType, Class<? extends T> target) {
    return implement(source, annotationType, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Class<T> source,
      Class<? extends Annotation> annotationType, TypeLiteral<? extends T> target) {
    return implement(TypeLiteral.get(source), annotationType, target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source,
      Class<? extends Annotation> annotationType, Class<? extends T> target) {
    return implement(source, annotationType, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(TypeLiteral<T> source,
      Class<? extends Annotation> annotationType, TypeLiteral<? extends T> target) {
    return implement(Key.get(source, annotationType), target);
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Key<T> source, Class<? extends T> target) {
    return implement(source, TypeLiteral.get(target));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <T> FactoryModuleBuilder implement(Key<T> source, TypeLiteral<? extends T> target) {
    bindings.addBinding(source, target);
    return this;
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <F> Module build(Class<F> factoryInterface) {
    return build(TypeLiteral.get(factoryInterface));
  }

  /**
   * See the factory configuration examples at {@link FactoryModuleBuilder}.
   */
  public <F> Module build(TypeLiteral<F> factoryInterface) {
    return build(Key.get(factoryInterface));
  }


  public <F> Module build(final Key<F> factoryInterface) {
    return new AbstractModule() {
      @Override protected void configure() {
        Provider<F> provider = new FactoryProvider2<F>(factoryInterface, bindings);
        bind(factoryInterface).toProvider(provider);
      }
    };
  }
}