com.google.inject.Binder |
Known Indirect Subclasses |
Collects configuration information (primarily bindings) which will be
used to create an Injector
. Guice provides this object to your
application's Module
implementors so they may each contribute
their own bindings and other registrations.
binder
, 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
/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 eligile 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(Class extends Annotation>, Scope)
,
bindInterceptor(Matcher super Class>>, Matcher super Method>, MethodInterceptor...)
, install(Module)
, requestStaticInjection(Class>...)
,
addError(String, 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.
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Records an error message to be presented to the user at a later time.
| |||||||||||
Records an error message which will be presented to the user at a later
time.
| |||||||||||
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.
| |||||||||||
See the EDSL examples at
Binder . | |||||||||||
See the EDSL examples at
Binder . | |||||||||||
See the EDSL examples at
Binder . | |||||||||||
See the EDSL examples at
Binder . | |||||||||||
Binds method interceptor[s] to methods matched by class and method matchers.
| |||||||||||
Registers a listener for injectable types.
| |||||||||||
Binds a scope to an annotation.
| |||||||||||
Binds a type converter.
| |||||||||||
Gets the current stage.
| |||||||||||
Prevents Guice from constructing a Proxy when a circular dependency
is found.
| |||||||||||
Returns the members injector used to inject dependencies into methods and fields on instances
of the given type
T . | |||||||||||
Returns the members injector used to inject dependencies into methods and fields on instances
of the given type
T . | |||||||||||
Returns the provider used to obtain instances for the given injection key.
| |||||||||||
Returns the provider used to obtain instances for the given injection type.
| |||||||||||
Uses the given module to configure more bindings.
| |||||||||||
Creates a new private child environment for bindings and other configuration.
| |||||||||||
Upon successful creation, the
Injector will inject instance fields
and methods of the given object. | |||||||||||
Upon successful creation, the
Injector will inject instance fields
and methods of the given object. | |||||||||||
Upon successful creation, the
Injector will inject static fields
and methods in the given classes. | |||||||||||
Instructs the Injector that bindings must be listed in a Module in order to
be injected.
| |||||||||||
Returns a binder that skips
classesToSkip when identify the
calling code. | |||||||||||
Returns a binder that uses
source as the reference location for
configuration errors. |
Records an error message to be presented to the user at a later time.
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. Uses format(String, Object[])
to insert the arguments into the
message.
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.
See the EDSL examples at Binder
.
See the EDSL examples at Binder
.
See the EDSL examples at Binder
.
See the EDSL examples at Binder
.
Binds method interceptor[s] to methods matched by class and method matchers. A method is eligible for interception if:
classMatcher | matches classes the interceptor should apply to. For
example: only(Runnable.class) . |
---|---|
methodMatcher | matches methods the interceptor should apply to. For
example: annotatedWith(Transactional.class) . |
interceptors | to bind |
Registers a listener for injectable types. Guice will notify the listener when it encounters injectable types matched by the given type matcher.
typeMatcher | that matches injectable types the listener should be notified of |
---|---|
listener | for injectable types matched by typeMatcher |
Binds a scope to an annotation.
Binds a type converter. The injector will use the given converter to convert string constants to matching types as needed.
typeMatcher | matches types the converter can handle |
---|---|
converter | converts values |
Prevents Guice from constructing a Proxy when a circular dependency is found. By default, circular proxies are not disabled.
If a parent injector disables circular proxies, then all child injectors (and private modules within that injector) also disable circular proxies. If a parent does not disable circular proxies, a child injector or private module may optionally declare itself as disabling circular proxies. If it does, the behavior is limited only to that child or any grandchildren. No siblings of the child will disable circular proxies.
Returns the members injector used to inject dependencies into methods and fields on instances
of the given type T
. The returned members injector will not be valid until the main
Injector
has been created. The members injector will throw an IllegalStateException
if you try to use it beforehand.
typeLiteral | type to get members injector for |
---|
Returns the members injector used to inject dependencies into methods and fields on instances
of the given type T
. The returned members injector will not be valid until the main
Injector
has been created. The members injector will throw an IllegalStateException
if you try to use it beforehand.
type | type to get members injector for |
---|
Returns the provider used to obtain instances for the given injection key.
The returned provider will not be valid until the Injector
has been
created. The provider will throw an IllegalStateException
if you
try to use it beforehand.
Returns the provider used to obtain instances for the given injection type.
The returned provider will not be valid until the Injector
has been
created. The provider will throw an IllegalStateException
if you
try to use it beforehand.
Uses the given module to configure more bindings.
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. See PrivateModule
for details.
Upon successful creation, the Injector
will inject instance fields
and methods of the given object.
type | of instance |
---|---|
instance | for which members will be injected |
Upon successful creation, the Injector
will inject instance fields
and methods of the given object.
instance | for which members will be injected |
---|
Upon successful creation, the Injector
will inject static fields
and methods in the given classes.
types | for which static members will be injected |
---|
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
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.
If the parent did not require explicit bindings but the child does, it is possible that a linked binding in the child may add a JIT binding to the parent. The child will not be allowed to reference the target binding directly, but the parent and other children of the parent may be able to.
Returns a binder that skips classesToSkip
when identify the
calling code. The caller's StackTraceElement is used to locate
the source of configuration errors.
classesToSkip | library classes that create bindings on behalf of their clients. |
---|
Returns a binder that uses source
as the reference location for
configuration errors. This is typically a StackTraceElement
for .java
source but it could any binding source, such as the
path to a .properties
file.
source | any object representing the source location and has a
concise toString() value |
---|