An API to bind optional values, optionally with a default value. OptionalBinder fulfills two roles:

1. It allows a framework to define an injection point that may or may not be bound by users.
2. It allows a framework to supply a default value that can be changed by users.

When an OptionalBinder is added, it will always supply the bindings: Optional<T> and Optional<Provider<T>>. Both java.util.Optional and com.google.common.base.Optional are bound for compatibility. If setBinding or setDefault are called, it will also bind T.

setDefault is intended for use by frameworks that need a default value. User code can call setBinding to override the default.

If setDefault or setBinding are linked to Providers, the Provider may return null. If it does, Optional<T> will be bound to an absent Optional. Binding setBinding to a Provider that returns null will not cause OptionalBinder to fall back to the setDefault binding.

If neither setDefault nor setBinding are called, it will try to link to a user-supplied binding of the same type. If no binding exists, the optionals will be absent. Otherwise, if a user-supplied binding of that type exists, or if setBinding or setDefault are called, the optionals will return present if they are bound to a non-null value.

Values are resolved at injection time. If a value is bound to a provider, that provider's get method will be called each time the optional is injected (unless the binding is also scoped, or an optional of provider is injected).

Annotations are used to create different optionals of the same key/value type. Each distinct annotation gets its own independent binding.

public class FrameworkModule extends AbstractModule {
  protected void configure() {
    OptionalBinder.newOptionalBinder(binder(), Renamer.class);
  }
}

With this module, an Optional<Renamer> can now be injected. With no other bindings, the optional will be absent. Users can specify bindings in one of two ways:

Option 1:

public class UserRenamerModule extends AbstractModule {
  protected void configure() {
    bind(Renamer.class).to(ReplacingRenamer.class);
  }
}

or Option 2:

public class UserRenamerModule extends AbstractModule {
  protected void configure() {
    OptionalBinder.newOptionalBinder(binder(), Renamer.class)
        .setBinding().to(ReplacingRenamer.class);
  }
}

With both options, the Optional<Renamer> will be present and supply the ReplacingRenamer.

Default values can be supplied using:

public class FrameworkModule extends AbstractModule {
  protected void configure() {
    OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
        .setDefault().toInstance(DEFAULT_LOOKUP_URL);
  }
}

With the above module, code can inject an @LookupUrl String and it will supply the DEFAULT_LOOKUP_URL. A user can change this value by binding

public class UserLookupModule extends AbstractModule {
  protected void configure() {
    OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
        .setBinding().toInstance(CUSTOM_LOOKUP_URL);
  }
}

... which will override the default value.

If one module uses setDefault the only way to override the default is to use setBinding. It is an error for a user to specify the binding without using OptionalBinder if setDefault or setBinding are called. For example,

public class FrameworkModule extends AbstractModule {
  protected void configure() {
    OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
        .setDefault().toInstance(DEFAULT_LOOKUP_URL);
  }
}
public class UserLookupModule extends AbstractModule {
  protected void configure() {
    bind(Key.get(String.class, LookupUrl.class)).toInstance(CUSTOM_LOOKUP_URL);
  }
}

... would generate an error, because both the framework and the user are trying to bind @LookupUrl String.