Set Binding (Multibinder)

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with no binding annotation.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type);

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with no binding annotation.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, TypeLiteral<T> type);

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with annotation.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type, Annotation annotation);

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with annotation.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, TypeLiteral<T> type, Annotation annotation);

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with annotationType.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type, Class<? extends Annotation> annotationType);

/**
 * Returns a new multibinder that collects instances of type in a Set 
 * that is itself bound with annotationType.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, TypeLiteral<T> type, Class<? extends Annotation> annotationType);

/**
 * Returns a new multibinder that collects instances of the key's type in a Set 
 * that is itself bound with the annotation (if any) of the key.
 */
public static <T> Multibinder<T> newSetBinder(Binder binder, Key<T> key);

/**
 * Returns a binding builder used to add a new element in the set. Each bound element 
 * must have a distinct value. Bound providers will be evaluated each time the set is injected.
 * 
 * It is an error to call this method without also calling one of the to methods on the 
 * returned binding builder. Scoping elements independently is supported.
 */
public LinkedBindingBuilder<T> addBinding();

/**
 * Configures the bound set to silently discard duplicate elements. When multiple equal 
 * values are bound, the one that gets included is arbitrary. When multiple modules 
 * contribute elements to the set, this configuration option impacts all of them.
 */
public Multibinder<T> permitDuplicates();

/**
 * Annotates methods of a Module to add items to a Multibinder. The method's return 
 * type and binding annotation determines what Set this will contribute to.
 */
@Target(METHOD)
@Retention(RUNTIME)
public @interface ProvidesIntoSet {}

public class SnacksModule extends AbstractModule {
  @Override
  protected void configure() {
    Multibinder<Snack> multibinder = Multibinder.newSetBinder(binder(), Snack.class);
    multibinder.addBinding().toInstance(new Twix());
    multibinder.addBinding().toProvider(SnickersProvider.class);
    multibinder.addBinding().to(Skittles.class);
  }
}

// Injection
@Inject
public SnackMachine(Set<Snack> snacks) {
  this.snacks = snacks; // Contains Twix, Snickers, Skittles
}

public class WebServicesModule extends AbstractModule {
  @Override
  protected void configure() {
    Multibinder<RequestHandler> multibinder = Multibinder.newSetBinder(
        binder(), RequestHandler.class, Names.named("web"));
    multibinder.addBinding().to(UserRequestHandler.class);
    multibinder.addBinding().to(OrderRequestHandler.class);
  }
}

// Injection
@Inject
public WebServer(@Named("web") Set<RequestHandler> handlers) {
  this.handlers = handlers;
}

public class ServicesModule extends AbstractModule {
  @ProvidesIntoSet
  RequestHandler provideUserHandler(UserService userService) {
    return new UserRequestHandler(userService);
  }
  
  @ProvidesIntoSet
  @Named("web")
  RequestHandler provideWebHandler() {
    return new WebRequestHandler();
  }
}

// Can also inject Collection<Provider<T>> for lazy evaluation
@Inject 
public SnackMachine(Collection<Provider<Snack>> snackProviders) {
  this.snackProviders = snackProviders;
}

// CandyModule
public class CandyModule extends AbstractModule {
  @Override
  protected void configure() {
    Multibinder<Snack> multibinder = Multibinder.newSetBinder(binder(), Snack.class);
    multibinder.addBinding().to(Chocolate.class);
    multibinder.addBinding().to(Gummies.class);
  }
}

// ChipsModule  
public class ChipsModule extends AbstractModule {
  @Override
  protected void configure() {
    Multibinder<Snack> multibinder = Multibinder.newSetBinder(binder(), Snack.class);
    multibinder.addBinding().to(Doritos.class);
    multibinder.addBinding().to(Cheetos.class);
  }
}

// Final injected Set contains elements from both modules

public class ConfigModule extends AbstractModule {
  @Override
  protected void configure() {
    Multibinder<String> multibinder = Multibinder.newSetBinder(binder(), String.class)
        .permitDuplicates(); // Allow duplicate values
    multibinder.addBinding().toInstance("config1");
    multibinder.addBinding().toInstance("config1"); // Would normally fail without permitDuplicates()
  }
}