Collects configuration information (primarily
bindings) which will be
used to create a
Ginjector. Gin provides this object to your
application's
GinModule implementors so they may each contribute
their own bindings and other registrations.
The Gin Binding EDSL
Gin 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
AbstractGinModule.
The Gin EDSL is remarkably similar to the Guice EDSL, which has very similar
documentation in its
com.google.inject.Binder
bind(ServiceImpl.class);
This statement does essentially nothing; it "binds the
ServiceImplclass to itself" and does not change Gin's default behavior. You may still
want to use this if you prefer your
GinModule class to serve as an
explicit
manifest for the services it provides. Also, in rare cases,
Gin 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
ProvidedByannotations found on
Service, since Gin 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. This binding specifies that Gin should resolve
an unannotated injection request for
Service by first resolving an
instance of
ServiceProvider in the regular way, then calling
Provider#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
Gin's concept of
Scope to guide when creation should happen
-- "letting Gin 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
@Redthat 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. Gin will create only one instance of
ServiceImpland 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. Gin 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 Gin 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 Gin how to honor an injection request for an element of type
PaymentService. The class
CreditCardPaymentService must implement the
PaymentService interface. Gin cannot currently bind or
inject a generic type, such as
Set; all type parameters must be
fully specified.
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
Enum#valueOf(Class,String), and to
Class#forName. Conversions for other types can be
configured using
#convertToTypes(Matcher,TypeConverter).
@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 Gin.
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,
com.google.inject.name.Named. Because of
Gin'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 Gin will let something bogus slip by, and will then inform you of
the problems at runtime, as soon as you try to create your Ginjector.
The other methods of GinBinder such as
#install and
#requestStaticInjection are not part of the Binding EDSL;
you can learn how to use these in the usual way, from the method
documentation.