Generated by
JDiff

com.google.inject Documentation Differences

This file contains all the changes in documentation in the package com.google.inject as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Binder

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.

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 {@code binder}, just as you will if your module extends AbstractModule.
     bind(ServiceImpl.class);
This statement does essentially nothing; it "binds the {@code 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 {@code Service} instance with no binding annotations should be treated as if it were a request for a {@code ServiceImpl} instance. This overrides the function of any @ImplementedBy or @ProvidedBy annotations found on {@code Service}, since Guice will have already "moved on" to {@code ServiceImpl} before it reaches the point when it starts looking for these annotations.
     bind(Service.class).toProvider(ServiceProvider.class);
In this example, {@code ServiceProvider} must extend or implement {@code Provider}. This binding specifies that Guice should resolve an unannotated injection request for {@code Service} by first resolving an instance of {@code ServiceProvider} in the regular way, then calling get() on the resulting Provider instance to obtain the {@code 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 {@code @Red}. If your module also includes bindings for particular values of the {@code @Red} annotation (see below), then this binding will serve as a "catch-all" for any values of {@code @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 {@code ServiceImpl} class into singleton scope. Guice will create only one instance of {@code ServiceImpl} and will reuse it for all injection requests of this type. Note that it is still possible to bind another instance of {@code 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 {@code ServiceImpl} class.

Besides Singleton/Scopes.SINGLETON, there are servlet-specific scopes available in {@code 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 {@code PaymentService}. The class {@code CreditCardPaymentService} must implement the {@code PaymentService} interface. Guice cannot currently bind or inject a generic type, such as {@code Set}; 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 {@code ServiceImpl} instance, then asks Guice to always use this single instance to fulfill all {@code Service} injection requests. When the Injector is created, it will automatically perform field and method injection for this instance, but any injectable constructor on {@code 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().
   {@literal @}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.

     Constructor loneCtor = getLoneCtorFromServiceImplViaReflection();
     bind(ServiceImpl.class)
         .toConstructor(loneCtor);
In this example, we directly tell Guice which constructor to use in a concrete class implementation. It means that we do not need to place {@literal @}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 a 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, .bindInterceptor, .install, .requestStaticInjection, .addError and .currentStage are not part of the Binding EDSL; you can learn how to use these in the usual way, from the method documentation. @author crazybob@google.com (Bob Lee) @author jessewilson@google.com (Jesse Wilson) @author kevinb@google.com (Kevin Bourrillion)

Class Binder, Provider<T> getProvider(Key<T>)

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 {@code IllegalStateException} if you try to use it beforehand. @since 2.0

Class Guice, Injector createInjector(Iterable<Module>)

Creates an injector for the given set of modules. @throws CreationException if one or more errors occur during Injector injector creation
Class Guice, Injector createInjector(Module[])

Creates an injector for the given set of modules. @throws CreationException if one or more errors occur during Injector injector construction
Class Guice, Injector createInjector(Stage, Iterable<Module>)

Creates an injector for the given set of modules, in a given development stage. @throws CreationException if one or more errors occur during Injector injector construction
Class Guice, Injector createInjector(Stage, Module[])

Creates an injector for the given set of modules, in a given development stage. @throws CreationException if one or more errors occur during Injector injector creation.

Class Injector, Injector createChildInjector(Iterable<Module>)

Returns a new injector that inherits all state from this injector. All bindings, scopes, interceptors and type converters are inherited -- they are visible to the child injector. Elements of the child injector are not visible to its parent.

Just-in-time bindings created for child injectors will be created in an ancestor injector whenever possible. This allows for scoped instances to be shared between injectors. Use explicit bindings to prevent bindings from being shared with the parent injector. Optional injections in just-in-time bindings (created in the parent injector) may be silently ignored if the optional dependencies are from the child injector.

No key may be bound by both an injector and one of its ancestors. This includes just-in-time bindings. The lone exception is the key for {@code Injector.class}, which is bound by each injector to itself. @since 2.0

Class Injector, Map<Key<?>, Binding<?>> getBindings()

Returns allthis injector's explicit bindings.

The returned map does not include bindings inherited from a parent injector, should one exist. The returned map is guaranteed to iterate (for example, with its java.util.Map.entrySet() iterator) in the order of insertion. In other words, the order inin which bindings appear in user Modules.

This method is part of the Guice SPI and is intended for use by tools and extensions.


Class ProvisionException, constructor ProvisionException(Iterable<Message>)

Creates a ConfigurationExceptionProvisionException containing {@code messages}.

Class ScopeAnnotation

Annotates annotations which are used for scoping. Only one such annotation may apply to a single implementation class. You must also annotate scope annotations with {@code @Retention(RUNTIME)}. For example:
   {@code @}Retention(RUNTIME)
   {@code @}Target(TYPE, METHOD)
   {@code @}ScopeAnnotation
   public {@code @}interface SessionScoped {}
 
@author crazybob@google.com (Bob Lee)

Class TypeLiteral

Represents a generic type {@code T}. Java doesn't yet provide a way to represent generic types, so this class does. Forces clients to create a subclass of this class which enables retrieval the type information even at runtime.

For example, to create a type literal for {@code List}, you can create an empty anonymous inner class:

{@code TypeLiteral> list = new TypeLiteral>() {};}

This syntax cannot be used to create type literals that have wildcard parameters, such as {@code Class} or {@code List extends CharSequence}. Such type literals must be constructed programatically, either by extracting types from members or by using the Types factory class. Along with modeling generic types, this class can resolve type parameters. For example, to figure out what type {@code keySet()} returns on a {@code Map}, use this code:

   {@code

   TypeLiteral> mapType
       = new TypeLiteral>() {};
   TypeLiteral<> keySetType
       = mapType.getReturnType(Map.class.getMethod("keySet"));
   System.out.println(keySetType); // prints "Set"}
@author crazybob@google.com (Bob Lee) @author jessewilson@google.com (Jesse Wilson)