com.google.inject.assistedinject Documentation Differences

This file contains all the changes in documentation in the package com.google.inject.assistedinject as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

When used in tandem with FactoryModuleBuilder, constructors annotated with with {@code @AssistedInject} indicate that multiple constructors can be injected, each with different parameters. AssistedInject annotations should not be mixed with {@literal @}Inject annotations. The assisted parameters must exactly match one corresponding factory method within the factory interface, but the parameters do not need to be in the same order. Constructors annotated with AssistedInject are created by Guice and receive all the benefits benefits (such asas AOP).

Obsolete Usage: When used in tandem with FactoryProvider, constructors constructors annotated with {@code @AssistedInject} trigger a "backwards compatibility mode". TheThe assisted assisted parameters must exactly match one corresponding factory method within the factoryfactory interface and and all must be in the same order as listed in the factory. In this backwardsbackwards compatable mode, constructors annotated with AssistedInject are not created by Guice andand thus receive receive none of the benefits.

Constructor parameters must be either supplied by the factory interface and marked with with @Assisted, or they must be injectable. @author jmourits@google.com (Jerome Mourits) @author jessewilson@google.com (Jesse Wilson)

A binding for a factory created by FactoryModuleBuilder. @param The fully qualified type of the factory. @since 3.0 @author ramakrishna@google.com (Ramakrishna Rajanna)

A visitor for the AssistedInject extension.

If your BindingTargetVisitor implements this interface, bindings created by using FactoryModuleBuilder will be visited through this interface. @since 3.0 @author ramakrishna@google.com (Ramakrishna Rajanna)

Details about how a method in an assisted inject factory will be assisted. @since 3.0 @author ramakrishna@google.com (Ramakrishna Rajanna)

Returns all non-assisted dependencies required to construct and inject inject the implementation.

Returns the constructor that will be used to construct instances of the implementation.

Returns the implementation type that will be created when the method is is used.

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 @} 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 @}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 with {@literal @}AssistedInject, in order to match the different parameters types of the 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 module, install a {@code FactoryModuleBuilder} that creates the 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 factory method cancan 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 willarguments 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 theof the same type, use a named {@literal @}Assisted annotation to disambiguate the 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 that acceptsaccepts a {@code Provider} as one of its arguments. @since 3.0 @author schmitt@google.com (Peter Schmitt)

Obsolete. Prefer FactoryModuleBuilder for its more concise API and additional capability.

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 @}Inject-annotated constructor. In addition to injector-supplied parameters, the constructor should have parametershave parameters that match each of the factory method's parameters. Each factory-supplied parameter parameter requires anan {@literal @}Assisted annotation. This serves to document that the parameter parameter is not boundbound 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) {
     ...
   }
 }

Any parameter that permits a null value should also be annotated {@code @Nullable}.

Configuring factories

In your module, bind the factory interface to the returned factory:

bind(PaymentFactory.class).toProvider(
     FactoryProvider.newFactory(PaymentFactory.class, RealPayment.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.

Using the factory

Inject your factory into your application classes. When you use the factory, your arguments arguments willwill 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 of thethe same type, use a named {@literal @}Assisted annotation to disambiguate the 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.

Backwards compatibility using {@literal @}AssistedInject

Instead of the {@literal @}Inject annotation, you may annotate the constructed classes with {@literal @}AssistedInject. This triggers a limited backwards-compatability mode.

Instead of matching factory method arguments to constructor parameters using their names, the parameters are matched by their order. The first factory method argument is usedis used for the first {@literal @}Assisted constructor parameter, etc.. Annotation names have no no effect.

Returned values are not created by Guice. These types are not eligible for method interception. They do receive post-construction member injection. @param The factory interface interface @author jmourits@google.com (Jerome Mourits) @author jessewilson@google.com (Jesse Wilson) @author dtm@google.com (Daniel Martin) @deprecated use FactoryModuleBuilder instead.