Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.gwt.inject.client.binder
Interface GinBinder

All Known Subinterfaces:
  PrivateGinBinder

All Known Implementing Classes:
  PrivateBinderAdapter

    public interface GinBinder

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 `Binder`

         bind(ServiceImpl.class);

This statement does essentially nothing; it "binds the `ServiceImpl` class 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 `@ProvidedBy` annotations 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<Service>`. 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 `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 `scopes` 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 `@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. Gin 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. 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<CreditCard>`. The class `CreditCardPaymentService` must implement the `PaymentService<CreditCard>` interface. Gin cannot currently bind or inject a generic type, such as `Set<E>`; 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 `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 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, `@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(com.google.gwt.inject.client.GinModule)` and `requestStaticInjection(java.lang.Class...)` are not part of the Binding EDSL; you can learn how to use these in the usual way, from the method documentation.

Method Summary
`
`<T> GinAnnotatedBindingBuilder<T>`
` | `bind(java.lang.Class<T> clazz)` See the EDSL examples at `GinBinder`
`
`<T> GinLinkedBindingBuilder<T>`
` | `bind(Key<T> key)` See the EDSL examples at `GinBinder`
`
`<T> GinAnnotatedBindingBuilder<T>`
` | `bind(TypeLiteral<T> type)` See the EDSL examples at `GinBinder`
`GinAnnotatedConstantBindingBuilder` | `bindConstant()` See the EDSL examples at `GinBinder`
`void` | `install(GinModule install)` Uses the given module to configure more bindings.
`void` | `requestStaticInjection(java.lang.Class<?>... types)` Upon successful creation, the `Ginjector` will inject static fields and methods in the given classes.

Method Detail

### bind

    <T> GinAnnotatedBindingBuilder<T> bind(java.lang.Class<T> clazz)

  See the EDSL examples at `GinBinder`

### bind

    <T> GinAnnotatedBindingBuilder<T> bind(TypeLiteral<T> type)

  See the EDSL examples at `GinBinder`

### bind

    <T> GinLinkedBindingBuilder<T> bind(Key<T> key)

  See the EDSL examples at `GinBinder`

### bindConstant

    GinAnnotatedConstantBindingBuilder bindConstant()

  See the EDSL examples at `GinBinder`

### install

    void install(GinModule install)

  Uses the given module to configure more bindings.

### requestStaticInjection

    void requestStaticInjection(java.lang.Class<?>... types)

  Upon successful creation, the `Ginjector` will inject static fields and methods in the given classes.

  Parameters:
    `types` - for which static members will be injected

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD