An API to bind optional values, optionally with a default value. OptionalBinder fulfills two
roles:
- It allows a framework to define an injection point that may or may not be bound by users.
- 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 and
Optional>. 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. Warning: Even if setBinding is called, the
default binding will still exist in the object graph. If it is a singleton, it will be
instantiated in
Stage.PRODUCTION.
If setDefault or setBinding are linked to Providers, the Provider may return
null. If
it does, the Optional bindings will be absent. 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 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 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.