- All Known Subinterfaces:
PrivateBinder
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 opening
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.
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.
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.
@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.
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 install(org.elasticsearch.injection.guice.Module), and addError(java.lang.String, java.lang.Object...) 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 TypeMethodDescriptionvoidRecords an error message which will be presented to the user at a later time.voidRecords an error message to be presented to the user at a later time.<T> AnnotatedBindingBuilder<T> See the EDSL examples atBinder.<T> LinkedBindingBuilder<T> See the EDSL examples atBinder.<T> AnnotatedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral) See the EDSL examples atBinder.<T> Provider<T> getProvider(Key<T> key) Returns the provider used to obtain instances for the given injection key.voidUses the given module to configure more bindings.skipSources(Class<?>... classesToSkip) Returns a binder that skipsclassesToSkipwhen identify the calling code.withSource(Object source) Returns a binder that usessourceas the reference location for configuration errors.
-
Method Details
-
bind
See the EDSL examples atBinder. -
bind
See the EDSL examples atBinder. -
bind
See the EDSL examples atBinder. -
install
Uses the given module to configure more bindings. -
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 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 will not be valid until theInjectorhas been created. The provider will throw anIllegalStateExceptionif you try to use it beforehand.- Since:
- 2.0
-
withSource
Returns a binder that usessourceas the reference location for configuration errors. This is typically aStackTraceElementfor.javasource but it could any binding source, such as the path to a.propertiesfile.- 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 skipsclassesToSkipwhen identify the calling code. The caller'sStackTraceElementis 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
-