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.

A support class for Modules which reduces repetition and results in in a more readablereadable configuration. Simply extend this class, implement .configure(), and call the inheritedinherited methods which mirror those found in in Binder. For example:

 public class MyModule extends AbstractModule {
   protected void configure() {
     bind(Service.class).to(ServiceImpl.class).in(Singleton.class);
     bind(CreditCardPaymentService.class);
     bind(PaymentService.class).to(CreditCardPaymentService.class);
     bindConstant().annotatedWith(Names.named("port")).to(8080);
   }
 }
 

@author crazybob@google.com (Bob Lee)

@see Binder#bindInterceptor(com.google.inject.matcher.Matcher, com.google.inject.matcher.Matcher, org.aopalliance.intercept.MethodInterceptor[])

@see Binder#bindListener(com.google.inject.matcher.Matcher, com.google.inject.spi.TypeListener) @since 2.0

@see Binder#currentStage() @since 2.0

Adds a dependency from this module to {@code type}. When the injector is is created, Guice willwill report an error if {@code type} cannot be injected. Note that this requirement may be satisfiedsatisfied by implicit binding, such as as a public no-arguments constructor. @since 2.0

Adds a dependency from this module to {@code key}. When the injector is is created, Guice willwill report an error if {@code key} cannot be injected. Note that this requirement may be satisfiedsatisfied by implicit binding, such as as a public no-arguments constructor. @since 2.0

Collects configuration information (primarily bindings) which will be be used to create anan Injector. Guice provides this object to your your application's Module implementors soso they may each contribute contribute their own bindings and other registrations.

The Guice Binding EDSL

Guice uses an embedded domain-specific language, or EDSL, to help you you create bindingsbindings simply and readably. This approach is great for overall overall usability, but it does come with a smallsmall cost: it is difficult to to learn how to use the Binding EDSL by reading reading method-levellevel javadocs. Instead, you should consult the series of of examples below. To save space, thesethese examples omit the opening opening {@code binder}, just as you will if your module extends extends AbstractModule.

     bind(ServiceImpl.class);

This statement does essentially nothing; it "binds the {@code ServiceImpl} class to itself" andand does not change Guice's default behavior. You may still still want to use this if you prefer youryour Module class to serve as an 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 isit is given explicitly.

     bind(Service.class).to(ServiceImpl.class);

Specifies that a request for a {@code Service} instance with no binding binding annotations should bebe treated as if it were a request for a a {@code ServiceImpl} instance. This overrides thethe function of any any @ImplementedBy or @ProvidedBy annotations found on {@code Service}, since Guice will have already already "moved on" to {@codecode ServiceImpl} before it reaches the point when it starts starts looking for these annotations.

     bind(Service.class).toProvider(ServiceProvider.class);

In this example, {@code ServiceProvider} must extend or implement implement {@code Provider}. ThisThis binding specifies that Guice should resolve resolve an unannotated injection request for {@code Service} by first resolving an an instance of {@code ServiceProvider} in the regular way, then calling calling get() on the resulting Provider instance to obtain the the {@code Service} instance.

The Provider you use here does not have to be a "factory"; that that is, a provider whichwhich always creates each instance it provides. However, this is generally a good practice toto follow. You can then use use Guice's concept of scopes to guide when creation shouldshould happen 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 use the binding annotationannotation {@code @Red}. If your module also includes bindings bindings for particular values of thethe {@code @Red} annotation (see below), then this binding will serve as a "catch-all" for any valuesvalues 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 into singleton scope. Guice willwill create only one instance of {@code ServiceImpl} and will reuse it for all injection requests ofof this type. Note that it is is still possible to bind another instance of {@code ServiceImpl} if thethe second second binding is qualified by an annotation as in the previous example. Guice is is not overlyoverly concerned with preventing you from creating multiple multiple instances of your "singletons", onlyonly with enabling your application to to share only one instance if that's all you tell Guice youyou need.

Note: a scope specified in this way overrides any scope that that was specified withwith an annotation on the {@code ServiceImpl} class.

Besides Singleton/Scopes.SINGLETON, there are are servlet-specific scopesscopes available in in {@code com.google.inject.servlet.ServletScopes}, and your Modules can can contributecontribute 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 It tells Guice how toto honor an injection request for an element of type type {@code PaymentService}. The class {@code CreditCardPaymentService} must implement the the {@code PaymentService} interface. Guice cannot currently bind or or inject a generic type, such as {@code Set}; all type parametersparameters must be 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 responsibility for obtaining aa {@code ServiceImpl} instance, then asks Guice to always use use this single instance to fulfill allall {@code Service} injection requests. When When the Injector is created, it will automaticallyautomatically perform field field and method injection for this instance, but any injectable constructor on on {@codecode ServiceImpl} is simply ignored. Note that using this approach results results in "eager loading" behaviorbehavior 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 constantconstant binding's value is a string, it is eligile for conversion to to all primitive types, to all enums, and to to class literals. ConversionsConversions for other types can be 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 to different specificspecific values of your annotation. Getting your hands on the the right instance of the annotation is a bit ofof a pain -- one approach, shown shown above, is to apply a prototype annotation to a field in your modulemodule class, so 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 a standard annotation, @Named. Because of of Guice's library support, binding by namename is quite easier than in the the arbitrary binding annotation case we just saw. However, remember that these that these names will live in a single flat namespace with all the other names used in in youryour application.

     Constructor loneCtor = getLoneCtorFromServiceImplViaReflection();
     bind(ServiceImpl.class)
         .toConstructor(loneCtor);

In this example, we directly tell Guice which constructor to use in a concrete concrete classclass implementation. It means that we do not need to place {@literal @}Inject Inject on any of thethe constructors and that Guice treats the provided constructor as though though it were annotated so. It isis useful for cases where you cannot modify existing existing classes and is a bit simpler than using aa Provider.

The above list of examples is far from exhaustive. If you can think of of how the concepts of oneone example might coexist with the concepts from another, you can most likely weave the two together. If the two concepts make no no sense with each other, you most likely won't be able to do it. In a few a few cases Guice will let something bogus slip by, and will then inform you of of the problems atat 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 notnot 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)

Records an error message which will be presented to the user at a later later time. Unlike throwingthrowing an exception, this enable us to continue continue configuring the Injector and discover more errors. Uses String.format(String, Object[]) to insert the arguments into the the message.

Records an exception, the full details of which will be logged, and the the message of which willwill be presented to the user at a later later time. If your Module calls something that you worry maymay fail, you should should catch the exception and pass it into this.

Binds method interceptor[s] to methods matched by class and method matchers. A method is eligible for interception if:

• Guice created the instance the method is on on
• Neither the enclosing type nor the method is final final
• And the method is package-private, protected, or public public

@param classMatcher matches classes the interceptor should apply to. For For example: {@codecode only(Runnable.class)}. @param methodMatcher matches methods the interceptor should apply to. For For example: {@codecode annotatedWith(Transactional.class)}. @param interceptors to bind. The interceptors are called in the order they they are given.

Registers listeners for provisioned objects. Guice will notify the the listeners just before andand after the object is provisioned. Provisioned Provisioned objects that are also injectable (everythingeverything except objects provided provided through Providers) can also be notified through TypeListenersTypeListeners registered in in .bindListener. @param bindingMatcher that matches bindings of provisioned objects the listener listener should be should be notified of @param listeners for provisioned objects matched by bindingMatcher bindingMatcher @since 4.0

Binds a type converter. The injector will use the given converter to to convert string constantsconstants to matching types as needed. @param typeMatcher matches types the converter can handle @param converter converts values @since 2.0

Prevents Guice from injecting dependencies that form a cycle, unless broken by a a Provider. By default, circular dependencies are not disabled.

If a parent injector disables circular dependencies, then all child injectors (and private modules within that injector) also disable circular dependencies. If a parent does not disable circular dependencies, a child injector or private module may optionally declare itself as disabling circular dependencies. If it does, the behavior is limited only to that child or any grandchildren. No siblings of the child will disable circular dependencies. @since 3.0

Returns the provider used to obtain instances for the given injection type. The returnedreturned provider will not be valid until the Injector has been been created. The provider will throwthrow an {@code IllegalStateException} if you you try to use it beforehand. @since 2.0

Returns the provider used to obtain instances for the given injection key. The returnedreturned provider will be attached to the injection point and will will follow the nullability specified inin the dependency. Additionally, the returned provider will not be valid until the Injector has been created. The provider will throw an {@code IllegalStateException} if you tryyou try to use it beforehand. @since 4.0

Returns the provider used to obtain instances for the given injection key. The returnedreturned provider will not be valid until the Injector has been been created. The provider will throwthrow an {@code IllegalStateException} if you you try to use it beforehand. @since 2.0

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. @return a binder that inherits configuration from this binder. Only exposed configuration on the returned binder will be visible to this binder. @since 2.0

Upon successful creation, the Injector will inject instance fields fields and methods of thethe given object. @param instance for which members will be injected @since 2.0

Upon successful creation, the Injector will inject instance fields fields and methods of thethe given object. @param type of instance @param instance for which members will be injected @since 2.0

Upon successful creation, the Injector will inject static fields fields and methods in thethe given classes. @param types for which static members will be injected

Requires that a {@literal @}Inject annotation exists on a constructor in order for Guice to consider it an eligible injectable class. By default, Guice will inject classes that have a no-args constructor if no {@literal @}Inject annotation exists on any constructor.

If the class is bound using LinkedBindingBuilder.toConstructor, Guice will still inject still inject that constructor regardless of annotations. @since 4.0

Requires that Guice finds an exactly matching binding annotation. This disables the the error-proneprone feature in Guice where it can substitute a binding for for {@literal @}Named Foo whenwhen attempting to inject inject {@literal @}Named("foo") Foo. @since 4.0

Instructs the Injector that bindings must be listed in a Module in order to to be injected. Classes that are not explicitly bound in a module cannot be be injected. Bindings created throughthrough a linked binding binding (bind(Foo.class).to(FooImpl.class)) are allowed, but the the implicitimplicit binding (FooImpl) cannot be directly injected unless unless it is also explicitly bound ( bind(FooImpl.class)).

Tools can still retrieve bindings for implicit bindings (bindings created created through a linkedlinked binding) if explicit bindings are required, however however Binding.getProvider will fail.

By default, explicit bindings are not required.

If a parent injector requires explicit bindings, then all child injectors injectors (and privateprivate modules within that injector) also require explicit bindings. If a parent does not requirerequire explicit bindings, a child injector or private private module may optionally declare itself asas requiring explicit bindings. If it it does, the behavior is limited only to that child or anyany grandchildren. No No siblings of the child will require explicit bindings.

In the absence of an explicit binding for the target, linked bindings in in child injectorsinjectors create a binding for the target in the parent. Since this this behavior can be surprising, it causescauses an error instead if explicit bindings bindings are required. To avoid this error, add an explicitexplicit binding for the target, either in the child or the parent. @since 3.0

Returns a binder that skips {@code classesToSkip} when identify the the calling code. The caller'ss StackTraceElement is used to locate locate the source of configuration errors. @param classesToSkip library classes that create bindings on behalf of of their clients. @return a binder that shares its configuration with this binder. @since 2.0

Returns a binder that uses {@code source} as the reference location for for configuration errors. This is typically a StackTraceElement for {@code .java} source but it could any bindingbinding source, such as the the path to a {@code .properties} file. @param source any object representing the source location and has a a concise toString() value @return a binder that shares its configuration with this binder @since 2.0

A mapping from a key (type and optional annotation) to the strategy for getting instances of the type. This interface is part of the introspection API and is intended primarily for use by tools.

Bindings are created in several ways:

• Explicitly in a module, via {@code bind()} and {@code bindConstant()} statements: statements:

       bind(Service.class).annotatedWith(Red.class).to(ServiceImpl.class);
       bindConstant().annotatedWith(ServerHost.class).to(args[0]);

• Implicitly by the Injector by following a type's pointer annotations or by using its annotated or or default constructor.
• By converting a bound instance to a different type.
• For providers, by delegating to the binding for the provided type.

They exist on both modules and on injectors, and their behaviour is different for each:

• Module bindings are incomplete and cannot be used to provide instances. This This is because the applicable scopes and interceptors may not be known until an injector injector is is created. From a tool's perspective, module bindings are like the injector's source source code. They code. They can be inspected or rewritten, but this analysis must be done statically.
• Injector bindings are complete and valid and can be used to provide instances. From a tools' perspective, injector bindings are like reflection for an an injector. injector. They have full runtime information, including the complete graph of injections injections necessary to necessary to satisfy a binding.

@param the bound type. The injected is always assignable to this type. @author crazybob@google.com (Bob Lee) @author jessewilson@google.com (Jesse Wilson)

Returns the scoped provider guice uses to fulfill requests for this this binding. @throws UnsupportedOperationException when invoked on a Binding created via com.google.inject.spi.Elements.getElements. This This method is only supported on Bindings returned from an injector.

Annotates annotations which are used for binding. Only one such annotation annotation may apply to a singlesingle injection point. You must also annotate binder binder annotations with {@code @Retention(RUNTIME)}. ForFor example:

   {@code @}Retention(RUNTIME)
   {@code @}Target({ FIELD, PARAMETER, METHOD })
   {@code @}BindingAnnotation
   public {@code @}interface Transactional {}
 

@author crazybob@google.com (Bob Lee)

Returns a value that was only partially computed due to this exception. The caller can use thisuse this while collecting additional configuration problems. @return the partial value, or {@code null} if none was set. The type of the partial value is specified by the throwing method.

The entry point to the Guice framework. Creates Injectors from from Modules.

Guice supports a model of development that draws clear boundaries between between APIs, Implementations of these APIs, Modules which configure these these implementations, and finallyfinally Applications which consist of a collection of of Modules. It is the Application, which typicallytypically defines your {@code main()} method, that bootstraps the Guice Injector using the {@code Guice} class, as as in this example:

     public class FooApplication {
       public static void main(String[] args) {
         Injector injector = Guice.createInjector(
             new ModuleA(),
             new ModuleB(),
             . . .
             new FooApplicationFlagsModule(args)
         );

         // Now just bootstrap the application and you're done
         FooStarter starter = injector.getInstance(FooStarter.class);
         starter.runApplication();
       }
     }
 

Creates an injector for the given set of modules. This is equivalent to to calling .createInjector(Stage, Iterable) with Stage.DEVELOPMENT. @throws CreationException if one or more errors occur during injector injector creation

Creates an injector for the given set of modules. This is equivalent to to calling .createInjector(Stage, Module...) with Stage.DEVELOPMENT. @throws CreationException if one or more errors occur during injector injector construction

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

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

Annotates members of your implementation class (constructors, methods methods and fields) into which thethe Injector should inject values. The Injector fulfills injection requests for:

• Every instance it constructs. The class being constructed must have have exactly one of itsits constructors marked with {@code @Inject} or must have a a constructor taking no parameters. TheThe Injector then proceeds to perform perform field and method injections.
• Pre-constructed instances passed to Injector.injectMembers, com.google.inject.binder.LinkedBindingBuilder.toInstance(Object) and and com.google.inject.binder.LinkedBindingBuilder.toProvider(javax.inject.Provider). In thisthis case all constructors are, of course, ignored.
• Static fields and methods of classes which any Module has has specifically requestedrequested static injection for, using using Binder.requestStaticInjection.

In all cases, a member can be injected regardless of its Java access access specifier (private, default, protected, public). @author crazybob@google.com (Bob Lee)

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 silently ignored ifif 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

Returns a snapshot of this injector's bindings, both explicit and just-in-time. The returned map is immutable; it contains only the bindings that were present when {@code getAllBindings()} was invoked. Just-in-time bindings are only present if they have been requested at least once. Subsequent calls may return a map with additionalwith additional just-in-time bindings.

The returned map does not include bindings inherited from a parent injector, should one exist.

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

Returns this 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 itswith its Map.entrySet() iterator) in the order of insertion. In other words, the order in in whichwhich bindings appear in user Modules.

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

Returns the binding if it already exists, or null if does not exist. Unlike Unlike .getBinding(Key), this does not attempt to create just-in-time bindings bindings for keys that aren'tt bound.

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

Returns the members injector used to inject dependencies into methods and fields on instances of the given type {@code T}. When feasible, use Binder.getMembersInjector(TypeLiteral) instead to get increased up front error detection. @param type type to get members injector for @see Binder#getMembersInjector(Class) for an alternative that offers up front error error detection @since 2.0

Returns the members injector used to inject dependencies into methods and fields on instances of the given type {@code T}. @param typeLiteral type to get members injector for @see Binder#getMembersInjector(TypeLiteral) for an alternative that offers up front error detection @since 2.0

Returns the provider used to obtain instances for the given type. When feasible, avoid usingavoid using this method, in favor of having Guice inject your dependencies ahead of time. @throws ConfigurationException if this injector cannot find or create the provider. @see Binder#getProvider(Class) for an alternative that offers up front error detection

Returns a map containing all scopes in the injector. The maps keys are scoping annotations likeannotations like {@code Singleton.class}, and the values are scope instances, such as {@code code Scopes.SINGLETON}. The returned map is immutable.

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

Returns a set containing all type converter bindings in the injector. The returned set is immutable.

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

Injects dependencies into the fields and methods of {@code instance}. Ignores the presence or absence of an injectable constructor.

Whenever Guice creates an instance, it performs this injection automatically (after first performing constructor injection), so if you're able to let Guice create all your objects for you, you'll never need to use this method. @param instance to inject members on on @see Binder#getMembersInjector(Class) for a preferred alternative that supports checks before run time

Binding key consisting of an injection type and an optional annotation. Matches the type andand annotation at a point of injection.

For example, {@code Key.get(Service.class, Transactional.class)} will will match:

   {@literal @}Inject
   public void setService({@literal @}Transactional Service service) {
     ...
   }
 

{@code Key} supports generic types via subclassing just like TypeLiteral.

Keys do not differentiate between primitive types (int, char, etc.) and and their correspondingcorresponding wrapper types (Integer, Character, etc.). Primitive Primitive types will be replaced with their wrapperwrapper types when keys are created. @author crazybob@google.com (Bob Lee)

Constructs a new key. Derives the type from this class's type parameter.

Clients create an empty anonymous subclass. Doing so embeds the type type parameter in thethe anonymous class's type hierarchy so we can reconstitute it it at runtime despite erasure.

Example usage for a binding of type {@code Foo}:

{@code new Key() {}}.

Constructs a new key. Derives the type from this class's type parameter.

Clients create an empty anonymous subclass. Doing so embeds the type type parameter in thethe anonymous class's type hierarchy so we can reconstitute it it at runtime despite erasure.

Example usage for a binding of type {@code Foo} annotated with with {@code @Bar}:

{@code new Key(new Bar()) {}}.

Constructs a new key. Derives the type from this class's type parameter.

Clients create an empty anonymous subclass. Doing so embeds the type type parameter in thethe anonymous class's type hierarchy so we can reconstitute it it at runtime despite erasure.

Example usage for a binding of type {@code Foo} annotated with with {@code @Bar}:

{@code new Key(Bar.class) {}}.

Returns a new key of the specified type with the same annotation as this this key. @since 3.0

Returns a new key of the specified type with the same annotation as this this key. @since 3.0

Returns a new key of the specified type with the same annotation as this this key. @since 3.0

Returns this key without annotation attributes, i.e. with only the the annotation type. @since 3.0

Injects dependencies into the fields and methods on instances of type {@code T}. Ignores the presence or absence of an injectable constructor. @param type to inject members of of @author crazybob@google.com (Bob Lee) @author jessewilson@google.com (Jesse Wilson) @since 2.0

A module contributes configuration information, typically interface interface bindings, which will be usedused to create an Injector. A Guice-based based application is ultimately composed of little moremore than a set of of {@code Module}s and some bootstrapping code.

Your Module classes can use a more streamlined syntax by extending extending AbstractModule rather than implementing this interface directly.

In addition to the bindings configured via .configure, bindings bindings will be created forfor all methods annotated with {@literal @}Provides. Use scope and binding annotations onon these methods to configure the the bindings.

Thrown from Provider.get when an attempt is made to access a scoped scoped object while thethe scope in question is not currently active. @author kevinb@google.com (Kevin Bourrillion) @since 2.0

Returns a binder whose configuration information is hidden from its environment by default. See PrivateModule for details. @author jessewilson@google.com (Jesse Wilson) @since 2.0

Makes a binding for {@code type} available to the enclosing environment. Use annotatedWith() toto expose {@code type} with a a binding annotation.

A module whose configuration information is hidden from its environment by default. Only bindings that are explicitly exposed will be available to other modules and to the users of the injector. This module may expose the bindings it creates and the bindings of the modules it installs.

A private module can be nested within a regular module or within another private module using install(). Its bindings live in a new environment that inherits bindings, type converters, scopes, and interceptors from the surrounding ("parent") environment. When you nest multiple private modules, the result is a tree of environments where the injector's environment is the root.

Guice EDSL bindings can be exposed with expose(). {@literal @}Provides bindings can be exposed with the {@literal @}Exposed annotation:

 public class FooBarBazModule extends PrivateModule {
   protected void configure() {
     bind(Foo.class).to(RealFoo.class);
     expose(Foo.class);

     install(new TransactionalBarModule());
     expose(Bar.class).annotatedWith(Transactional.class);

     bind(SomeImplementationDetail.class);
     install(new MoreImplementationDetailsModule());
   }

   {@literal @}Provides {@literal @}Exposed
   public Baz provideBaz() {
     return new SuperBaz();
   }
 }
 

Private modules are implemented using parent injectors. When it can satisfy their dependencies, just-in-time bindings will be created in the root environment. Such bindings are shared among all environments in the tree.

The scope of a binding is constrained to its environment. A singleton bound in a private module will be unique to its environment. But a binding for the same type in a different private module will yield a different instance.

A shared binding that injects the {@code Injector} gets the root injector, which only has access to bindings in the root environment. An explicit binding that injects the {@code Injector} gets access to all bindings in the child environment.

To promote a just-in-time binding to an explicit binding, bind it:

   bind(FooImpl.class);
 

@author jessewilson@google.com (Jesse Wilson) @since 2.0

@see Binder#bindInterceptor(com.google.inject.matcher.Matcher, com.google.inject.matcher.Matcher, org.aopalliance.intercept.MethodInterceptor[])

@see Binder#convertToTypes(com.google.inject.matcher.Matcher, com.google.inject.spi.TypeConverter)

An object capable of providing instances of type {@code T}. Providers are used in numerous ways by Guice:

• When the default means for obtaining instances (an injectable or parameterless constructor) is insufficient for a particular binding, the module can specify a custom {@code Provider} instead, to control exactly how Guice creates or obtains instances for the binding.
• An implementation class may always choose to have a {@code Provider} instance injected, rather than having a {@code T} injected directly. This may give you access to multiple instances, instances you wish to safely mutate and discard, instances which are out of scope (e.g. using a {@code @RequestScoped} object from within a {@code @SessionScoped} object), or instances that will be initialized lazily.
• A custom Scope is implemented as a decorator of {@code Provider}, which decides when to delegate to the backing provider and when to provide the instance some other way.
• The Injector offers access to the {@code Provider} it uses to fulfill requests requests forfor a given key, via the Injector.getProvider methods.

@param the type of object this provides provides @author crazybob@google.com (Bob Lee)

Provides an instance of {@code T}. Must never return {@code null}. @throws OutOfScopeException when an attempt is made to access a scoped object while the scope in question is not currently active @throws ProvisionException if an instance cannot be provided. Such exceptions include messages and throwables to describe why provision failed.

Indicates that there was a runtime failure while providing an instance. @author kevinb@google.com (Kevin Bourrillion) @author jessewilson@google.com (Jesse Wilson) @since 2.0

A scope is a level of visibility that instances provided by Guice may have. By default, anan instance created by the Injector has no scope, meaning it has no state from thethe framework's perspective -- the the {@code Injector} creates it, injects it once into the class thatthat required it, and then immediately forgets it. Associating a scope with a particular bindingparticular binding allows the created instance to be "remembered" and possibly used used again for other injections.

An example of a scope is Scopes.SINGLETON. @author crazybob@google.com (Bob Lee)

Scopes a provider. The returned provider returns objects from this scope. If an object does notnot exist in this scope, the provider can use the given given unscoped provider to retrieve one.

Scope implementations are strongly encouraged to override override Object.toString in thethe returned provider and include the backing backing provider's {@code toString()} output. @param key binding key @param unscoped locates an instance when one doesn't already exist in this this scope. @return a new provider which only delegates to the given unscoped provider provider when an instance ofof the requested object doesn't already exist in this this scope

A short but useful description of this scope. For comparison, the standard standard scopes that shipship with guice use the descriptions descriptions {@code "Scopes.SINGLETON"}, {@code "ServletScopes.SESSION"} and {@code "ServletScopes.REQUEST"}.

Annotates annotations which are used for scoping. Only one such annotation annotation may apply to a singlesingle implementation class. You must also annotate scope 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)

Returns true if the object is a proxy for a circular dependency, constructed by Guice becausebecause it encountered a circular dependency. Scope Scope implementations should be careful to not cachecache circular proxies, because the proxies are not intended for general purpose use. (They are designed just to fulfill the immediate injection, not all injections. Caching them can lead toto IllegalArgumentExceptions or ClassCastExceptions.) @since 4.0

No scope; the same as not applying any scope at all. Each time the the Injector obtains an instanceinstance of an object with "no scope", it injects this this instance then immediately forgets it. When thethe next request for the same same binding arrives it will need to obtain the instance over again.

This exists only in case a class has been annotated with a scope scope annotation such as @Singleton, and you need to override override this to "no scope" in your binding. @since 2.0

Apply this to implementation classes when you want only one instance instance (per Injector) to bebe reused for all injections for that binding. @author crazybob@google.com (Bob Lee)

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

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

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

Along with modeling generic types, this class can resolve type parameters. For example, toto figure out what type {@code keySet()} returns on a {@code code Map}, use this code:

{@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)

Constructs a new type literal. Derives represented class from type type parameter.

Clients create an empty anonymous subclass. Doing so embeds the type type parameter in thethe anonymous class's type hierarchy so we can reconstitute it it at runtime despite erasure.

Returns the raw (non-generic) type for this type. @since 2.0