Class OptionalBinder<T>
- java.lang.Object
-
- com.google.inject.multibindings.OptionalBinder<T>
-
public class OptionalBinder<T> extends Object
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<T>
andOptional<Provider<T>>
. Bothjava.util.Optional
andcom.google.common.base.Optional
are bound for compatibility. IfsetBinding()
orsetDefault()
are called, it will also bindT
.setDefault
is intended for use by frameworks that need a default value. User code can callsetBinding
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 inStage.PRODUCTION
.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:
With both options, thepublic class UserRenamerModule extends AbstractModule { protected void configure() { OptionalBinder.newOptionalBinder(binder(), Renamer.class) .setBinding().to(ReplacingRenamer.class); } }
Optional<Renamer>
will be present and supply the ReplacingRenamer.Default values can be supplied using:
With the above module, code can inject anpublic class FrameworkModule extends AbstractModule { protected void configure() { OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class)) .setDefault().toInstance(DEFAULT_LOOKUP_URL); } }
@LookupUrl String
and it will supply the DEFAULT_LOOKUP_URL. A user can change this value by binding
... which will override the default value.public class UserLookupModule extends AbstractModule { protected void configure() { OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class)) .setBinding().toInstance(CUSTOM_LOOKUP_URL); } }
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,
... would generate an error, because both the framework and the user are trying to bindpublic 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); } }
@LookupUrl String
.- Since:
- 4.0
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object obj)
int
hashCode()
static <T> OptionalBinder<T>
newOptionalBinder(Binder binder, Key<T> type)
static <T> OptionalBinder<T>
newOptionalBinder(Binder binder, TypeLiteral<T> type)
static <T> OptionalBinder<T>
newOptionalBinder(Binder binder, Class<T> type)
LinkedBindingBuilder<T>
setBinding()
Returns a binding builder used to set the actual value that will be injected.LinkedBindingBuilder<T>
setDefault()
Returns a binding builder used to set the default value that will be injected.
-
-
-
Method Detail
-
newOptionalBinder
public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, Class<T> type)
-
newOptionalBinder
public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, TypeLiteral<T> type)
-
newOptionalBinder
public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, Key<T> type)
-
setDefault
public LinkedBindingBuilder<T> setDefault()
Returns a binding builder used to set the default value that will be injected. The binding set by this method will be ignored ifsetBinding()
is called.It is an error to call this method without also calling one of the
to
methods on the returned binding builder.
-
setBinding
public LinkedBindingBuilder<T> setBinding()
Returns a binding builder used to set the actual value that will be injected. This overrides any binding set bysetDefault()
.It is an error to call this method without also calling one of the
to
methods on the returned binding builder.
-
-