Interface Binder
- All Known Subinterfaces:
PrivateBinder
- All Known Implementing Classes:
Elements.RecordingBinder
Injector
. Guice provides this object to your application's Module
implementors so
they may each contribute their own bindings and other registrations.
The Guice Binding EDSL
Guice uses an embedded domain-specific language, or EDSL, to help you create bindings simply and readably. This approach is great for overall usability, but it does come with a small cost: it is difficult to learn how to use the Binding EDSL by reading method-level javadocs. Instead, you should consult the series of examples below. To save space, these examples omit the openingbinder
, just as you will if your module extends AbstractModule
.
bind(ServiceImpl.class);This statement does essentially nothing; it "binds the
ServiceImpl
class to itself" and
does not change Guice's default behavior. You may still want to use this if you prefer your
Module
class to serve as an explicit manifest for the services it provides. Also,
in rare cases, Guice may be unable to validate a binding at injector creation time unless it is
given explicitly.
bind(Service.class).to(ServiceImpl.class);Specifies that a request for a
Service
instance with no binding annotations should be
treated as if it were a request for a ServiceImpl
instance. This overrides the
function of any @ImplementedBy
or @ProvidedBy
annotations found on Service
, since Guice will have already "moved on" to
ServiceImpl
before it reaches the point when it starts looking for these annotations.
bind(Service.class).toProvider(ServiceProvider.class);In this example,
ServiceProvider
must extend or implement Provider<Service>
. This
binding specifies that Guice should resolve an unannotated injection request for Service
by first resolving an instance of ServiceProvider
in the regular way, then calling get()
on the resulting Provider instance to obtain the Service
instance.
The Provider
you use here does not have to be a "factory"; that is, a provider which
always creates each instance it provides. However, this is generally a good practice to
follow. You can then use Guice's concept of scopes
to guide when creation should
happen -- "letting Guice work for you".
bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);Like the previous example, but only applies to injection requests that use the binding annotation
@Red
. If your module also includes bindings for particular values of the
@Red
annotation (see below), then this binding will serve as a "catch-all" for any values
of @Red
that have no exact match in the bindings.
bind(ServiceImpl.class).in(Singleton.class); // or, alternatively bind(ServiceImpl.class).in(Scopes.SINGLETON);Either of these statements places the
ServiceImpl
class into singleton scope. Guice will
create only one instance of ServiceImpl
and will reuse it for all injection requests of
this type. Note that it is still possible to bind another instance of ServiceImpl
if the
second binding is qualified by an annotation as in the previous example. Guice is not overly
concerned with preventing you from creating multiple instances of your "singletons", only
with enabling your application to share only one instance if that's all you tell Guice you
need.
Note: a scope specified in this way overrides any scope that was specified with
an annotation on the ServiceImpl
class.
Besides Singleton
/Scopes.SINGLETON
, there are servlet-specific scopes
available in com.google.inject.servlet.ServletScopes
, and your Modules can contribute
their own custom scopes for use here as well.
bind(new TypeLiteral<PaymentService<CreditCard>>() {}) .to(CreditCardPaymentService.class);This admittedly odd construct is the way to bind a parameterized type. It tells Guice how to honor an injection request for an element of type
PaymentService<CreditCard>
. The class
CreditCardPaymentService
must implement the PaymentService<CreditCard>
interface.
Guice cannot currently bind or inject a generic type, such as Set<E>
; all type parameters
must be fully specified.
bind(Service.class).toInstance(new ServiceImpl()); // or, alternatively bind(Service.class).toInstance(SomeLegacyRegistry.getService());In this example, your module itself, not Guice, takes responsibility for obtaining a
ServiceImpl
instance, then asks Guice to always use this single instance to fulfill all
Service
injection requests. When the Injector
is created, it will automatically
perform field and method injection for this instance, but any injectable constructor on
ServiceImpl
is simply ignored. Note that using this approach results in "eager loading" behavior
that you can't control.
bindConstant().annotatedWith(ServerHost.class).to(args[0]);Sets up a constant binding. Constant injections must always be annotated. When a constant binding's value is a string, it is eligible for conversion to all primitive types, to
all enums
, and to class literals
. Conversions
for other types can be configured using convertToTypes()
.
@Color("red") Color red; // A member variable (field) . . . red = MyModule.class.getDeclaredField("red").getAnnotation(Color.class); bind(Service.class).annotatedWith(red).to(RedService.class);If your binding annotation has parameters you can apply different bindings to different specific values of your annotation. Getting your hands on the right instance of the annotation is a bit of a pain -- one approach, shown above, is to apply a prototype annotation to a field in your module class, so that you can read this annotation instance and give it to Guice.
bind(Service.class) .annotatedWith(Names.named("blue")) .to(BlueService.class);Differentiating by names is a common enough use case that we provided a standard annotation,
@Named
. Because of Guice's library support, binding by name
is quite easier than in the arbitrary binding annotation case we just saw. However, remember that
these names will live in a single flat namespace with all the other names used in your
application.
ConstructorIn this example, we directly tell Guice which constructor to use in a concrete class implementation. It means that we do not need to place @Inject on any of the constructors and that Guice treats the provided constructor as though it were annotated so. It is useful for cases where you cannot modify existing classes and is a bit simpler than using aloneCtor = getLoneCtorFromServiceImplViaReflection(); bind(ServiceImpl.class) .toConstructor(loneCtor);
Provider
.
The above list of examples is far from exhaustive. If you can think of how the concepts of one example might coexist with the concepts from another, you can most likely weave the two together. If the two concepts make no sense with each other, you most likely won't be able to do it. In a few cases Guice will let something bogus slip by, and will then inform you of the problems at runtime, as soon as you try to create your Injector.
The other methods of Binder such as bindScope(java.lang.Class<? extends java.lang.annotation.Annotation>, com.google.inject.Scope)
, #bindInterceptor
, install(com.google.inject.Module)
, requestStaticInjection(java.lang.Class<?>...)
, addError(java.lang.String, java.lang.Object...)
and currentStage()
are not
part of the Binding EDSL; you can learn how to use these in the usual way, from the method
documentation.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Records an error message to be presented to the user at a later time.void
Records an error message which will be presented to the user at a later time.void
Records an exception, the full details of which will be logged, and the message of which will be presented to the user at a later time.<T> LinkedBindingBuilder<T>
See the EDSL examples atBinder
.<T> AnnotatedBindingBuilder<T>
bind
(TypeLiteral<T> typeLiteral) See the EDSL examples atBinder
.<T> AnnotatedBindingBuilder<T>
See the EDSL examples atBinder
.See the EDSL examples atBinder
.void
bindListener
(Matcher<? super Binding<?>> bindingMatcher, ProvisionListener... listeners) Registers listeners for provisioned objects.void
bindListener
(Matcher<? super TypeLiteral<?>> typeMatcher, TypeListener listener) Registers a listener for injectable types.void
bindScope
(Class<? extends Annotation> annotationType, Scope scope) Binds a scope to an annotation.void
convertToTypes
(Matcher<? super TypeLiteral<?>> typeMatcher, TypeConverter converter) Binds a type converter.Gets the current stage.void
Prevents Guice from injecting dependencies that form a cycle, unless broken by aProvider
.<T> MembersInjector<T>
getMembersInjector
(TypeLiteral<T> typeLiteral) Returns the members injector used to inject dependencies into methods and fields on instances of the given typeT
.<T> MembersInjector<T>
getMembersInjector
(Class<T> type) Returns the members injector used to inject dependencies into methods and fields on instances of the given typeT
.<T> Provider<T>
getProvider
(Key<T> key) Returns the provider used to obtain instances for the given injection key.<T> Provider<T>
getProvider
(Dependency<T> dependency) Returns the provider used to obtain instances for the given injection key.<T> Provider<T>
getProvider
(Class<T> type) Returns the provider used to obtain instances for the given injection type.void
Uses the given module to configure more bindings.Creates a new private child environment for bindings and other configuration.<T> void
requestInjection
(TypeLiteral<T> type, T instance) Upon successful creation, theInjector
will inject instance fields and methods of the given object.void
requestInjection
(Object instance) Upon successful creation, theInjector
will inject instance fields and methods of the given object.void
requestStaticInjection
(Class<?>... types) Upon successful creation, theInjector
will inject static fields and methods in the given classes.void
Requires that a @Inject
annotation exists on a constructor in order for Guice to consider it an eligible injectable class.void
Requires that Guice finds an exactly matching binding annotation.void
Instructs the Injector that bindings must be listed in a Module in order to be injected.void
Adds a scanner that will look in all installed modules for annotations the scanner can parse, and binds them like @Provides methods.skipSources
(Class... classesToSkip) Returns a binder that skipsclassesToSkip
when identify the calling code.withSource
(Object source) Returns a binder that usessource
as the reference location for configuration errors.
-
Method Details
-
bindScope
Binds a scope to an annotation. -
bind
See the EDSL examples atBinder
. -
bind
See the EDSL examples atBinder
. -
bind
See the EDSL examples atBinder
. -
bindConstant
AnnotatedConstantBindingBuilder bindConstant()See the EDSL examples atBinder
. -
requestInjection
Upon successful creation, theInjector
will inject instance fields and methods of the given object.- Parameters:
type
- of instanceinstance
- for which members will be injected- Since:
- 2.0
-
requestInjection
Upon successful creation, theInjector
will inject instance fields and methods of the given object.- Parameters:
instance
- for which members will be injected- Since:
- 2.0
-
requestStaticInjection
Upon successful creation, theInjector
will inject static fields and methods in the given classes.- Parameters:
types
- for which static members will be injected
-
install
Uses the given module to configure more bindings. -
currentStage
Stage currentStage()Gets the current stage. -
addError
Records an error message which will be presented to the user at a later time. Unlike throwing an exception, this enable us to continue configuring the Injector and discover more errors. UsesString.format(String, Object[])
to insert the arguments into the message. -
addError
Records an exception, the full details of which will be logged, and the message of which will be presented to the user at a later time. If your Module calls something that you worry may fail, you should catch the exception and pass it into this. -
addError
Records an error message to be presented to the user at a later time.- Since:
- 2.0
-
getProvider
Returns the provider used to obtain instances for the given injection key. The returned provider will not be valid until theInjector
has been created. The provider will throw anIllegalStateException
if you try to use it beforehand.- Since:
- 2.0
-
getProvider
Returns the provider used to obtain instances for the given injection key. The returned provider will be attached to the injection point and will follow the nullability specified in the dependency. Additionally, the returned provider will not be valid until theInjector
has been created. The provider will throw anIllegalStateException
if you try to use it beforehand.- Since:
- 4.0
-
getProvider
Returns the provider used to obtain instances for the given injection type. The returned provider will not be valid until theInjector
has been created. The provider will throw anIllegalStateException
if you try to use it beforehand.- Since:
- 2.0
-
getMembersInjector
Returns the members injector used to inject dependencies into methods and fields on instances of the given typeT
. The returned members injector will not be valid until the mainInjector
has been created. The members injector will throw anIllegalStateException
if you try to use it beforehand.- Parameters:
typeLiteral
- type to get members injector for- Since:
- 2.0
-
getMembersInjector
Returns the members injector used to inject dependencies into methods and fields on instances of the given typeT
. The returned members injector will not be valid until the mainInjector
has been created. The members injector will throw anIllegalStateException
if you try to use it beforehand.- Parameters:
type
- type to get members injector for- Since:
- 2.0
-
convertToTypes
Binds a type converter. The injector will use the given converter to convert string constants to matching types as needed.- Parameters:
typeMatcher
- matches types the converter can handleconverter
- converts values- Since:
- 2.0
-
bindListener
Registers a listener for injectable types. Guice will notify the listener when it encounters injectable types matched by the given type matcher.- Parameters:
typeMatcher
- that matches injectable types the listener should be notified oflistener
- for injectable types matched by typeMatcher- Since:
- 2.0
-
bindListener
Registers listeners for provisioned objects. Guice will notify the listeners just before and after the object is provisioned. Provisioned objects that are also injectable (everything except objects provided through Providers) can also be notified through TypeListeners registered inbindListener(com.google.inject.matcher.Matcher<? super com.google.inject.TypeLiteral<?>>, com.google.inject.spi.TypeListener)
.- Parameters:
bindingMatcher
- that matches bindings of provisioned objects the listener should be notified oflisteners
- for provisioned objects matched by bindingMatcher- Since:
- 4.0
-
withSource
Returns a binder that usessource
as the reference location for configuration errors. This is typically aStackTraceElement
for.java
source but it could any binding source, such as the path to a.properties
file.- Parameters:
source
- any object representing the source location and has a concisetoString()
value- Returns:
- a binder that shares its configuration with this binder
- Since:
- 2.0
-
skipSources
Returns a binder that skipsclassesToSkip
when identify the calling code. The caller'sStackTraceElement
is used to locate the source of configuration errors.- Parameters:
classesToSkip
- library classes that create bindings on behalf of their clients.- Returns:
- a binder that shares its configuration with this binder.
- Since:
- 2.0
-
newPrivateBinder
PrivateBinder newPrivateBinder()Creates a new private child environment for bindings and other configuration. The returned binder can be used to add and configuration information in this environment. SeePrivateModule
for details.- Returns:
- a binder that inherits configuration from this binder. Only exposed configuration on the returned binder will be visible to this binder.
- Since:
- 2.0
-
requireExplicitBindings
void requireExplicitBindings()Instructs the Injector that bindings must be listed in a Module in order to be injected. Classes that are not explicitly bound in a module cannot be injected. Bindings created through a linked binding (bind(Foo.class).to(FooImpl.class)
) are allowed, but the implicit binding (FooImpl
) cannot be directly injected unless it is also explicitly bound (bind(FooImpl.class)
).Tools can still retrieve bindings for implicit bindings (bindings created through a linked binding) if explicit bindings are required, however
Binding.getProvider()
will fail.By default, explicit bindings are not required.
If a parent injector requires explicit bindings, then all child injectors (and private modules within that injector) also require explicit bindings. If a parent does not require explicit bindings, a child injector or private module may optionally declare itself as requiring explicit bindings. If it does, the behavior is limited only to that child or any grandchildren. No siblings of the child will require explicit bindings.
In the absence of an explicit binding for the target, linked bindings in child injectors create a binding for the target in the parent. Since this behavior can be surprising, it causes an error instead if explicit bindings are required. To avoid this error, add an explicit binding for the target, either in the child or the parent.
- Since:
- 3.0
-
disableCircularProxies
void disableCircularProxies()Prevents Guice from injecting dependencies that form a cycle, unless broken by aProvider
. By default, circular dependencies are not disabled.If a parent injector disables circular dependencies, then all child injectors (and private modules within that injector) also disable circular dependencies. If a parent does not disable circular dependencies, a child injector or private module may optionally declare itself as disabling circular dependencies. If it does, the behavior is limited only to that child or any grandchildren. No siblings of the child will disable circular dependencies.
- Since:
- 3.0
-
requireAtInjectOnConstructors
void requireAtInjectOnConstructors()Requires that a @Inject
annotation exists on a constructor in order for Guice to consider it an eligible injectable class. By default, Guice will inject classes that have a no-args constructor if no @Inject
annotation exists on any constructor.If the class is bound using
LinkedBindingBuilder.toConstructor(java.lang.reflect.Constructor<S>)
, Guice will still inject that constructor regardless of annotations.- Since:
- 4.0
-
requireExactBindingAnnotations
void requireExactBindingAnnotations()Requires that Guice finds an exactly matching binding annotation. This disables the error-prone feature in Guice where it can substitute a binding for@Named Foo
when attempting to inject@Named("foo") Foo
.- Since:
- 4.0
-
scanModulesForAnnotatedMethods
Adds a scanner that will look in all installed modules for annotations the scanner can parse, and binds them like @Provides methods. Scanners apply to all modules installed in the injector. Scanners installed in child injectors or private modules do not impact modules in siblings or parents, however scanners installed in parents do apply to all child injectors and private modules.- Since:
- 4.0
-