com.google.inject.assistedinject.FactoryModuleBuilder Maven / Gradle / Ivy

Go to download
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.
 *
 * Defining a factory
 * 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.
 *
 * public interface PaymentFactory {
 *   Payment create(Date startDate, Money amount);
 * }
 *
 * You can name your factory methods whatever you like, such as create, createPayment
 * or newPayment.
 *
 * Creating a type that accepts factory parameters
 * {@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.
 *
 * public class RealPayment implements Payment {
 *   {@literal @}Inject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *      {@literal @}Assisted Date startDate,
 *      {@literal @}Assisted Money amount) {
 *     ...
 *   }
 * }
 *
 * Multiple factory methods for the same type
 * 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.
 *
 * 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,
 *     {@literal @}Assisted Date startDate,
 *     {@literal @}Assisted Money amount) {
 *     ...
 *   }
 *
 *  {@literal @}AssistedInject
 *   public RealPayment(
 *      CreditService creditService,
 *      AuthService authService,
 *     {@literal @}Assisted Money amount) {
 *     ...
 *   }
 * }
 *
 * Configuring simple factories
 * In your {@link Module module}, install a {@code FactoryModuleBuilder} that creates the
 * factory:
 *
 * install(new FactoryModuleBuilder()
 *     .implement(Payment.class, RealPayment.class)
 *     .build(PaymentFactory.class));
 *
 * 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.
 *
 * Configuring complex factories
 * Factories can create an arbitrary number of objects, one per each method.  Each factory
 * method can be configured using .implement.
 *
 * 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));
 * 
 *
 * Using the factory
 * 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.
 *
 * public class PaymentAction {
 * {@literal @}Inject private PaymentFactory paymentFactory;
 *
 * public void doPayment(Money amount) {
 * Payment payment = paymentFactory.create(new Date(), amount);
 * payment.apply();
 * }
 * }
 *
 * Making parameter types distinct
 * 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:
 *
 * public interface PaymentFactory {
 * Payment create(
 * {@literal @}Assisted("startDate") Date startDate,
 * {@literal @}Assisted("dueDate") Date dueDate,
 * Money amount);
 * } 
 *
 * ...and to the concrete type's constructor parameters:
 *
 * public class RealPayment implements Payment {
 * {@literal @}Inject
 * public RealPayment(
 * CreditService creditService,
 * AuthService authService,
 * {@literal @}Assisted("startDate") Date startDate,
 * {@literal @}Assisted("dueDate") Date dueDate,
 * {@literal @}Assisted Money amount) {
 * ...
 * }
 * }
 *
 * Values are created by Guice
 * 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.
 *
 * More configuration options
 * 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:
 * If you just want to return the types specified in the factory, do not configure any
 * implementations:
 *
 * public interface FruitFactory {
 * Apple getApple(Color color);
 * }
 * ...
 * protected void configure() {
 * install(new FactoryModuleBuilder().build(FruitFactory.class));
 * }
 *
 * Note that any type returned by the factory in this manner needs to be an implementation class.
 * To return two different implementations for the same interface from your factory, use binding
 * annotations on your return types:
 *
 * 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));
 * }
 *
 * Implementation limitations
 * As a limitation of the implementation, it is prohibited to declare a factory method that
 * accepts a {@code Provider} as one of its arguments.
 */
public final class FactoryModuleBuilder {

    private final BindingCollector bindings = new BindingCollector();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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