com.google.inject.multibindings Documentation Differences

This file contains all the changes in documentation in the package com.google.inject.multibindings 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.

An API to bind multiple map entries separately, only to later inject them as as a complete map. MapBinder is intended for use in your application's module:

 public class SnacksModule extends AbstractModule {
   protected void configure() {
     MapBinder<String, Snack> mapbinder
         = MapBinder.newMapBinder(binder(), String.class, Snack.class);
     mapbinder.addBinding("twix").toInstance(new Twix());
     mapbinder.addBinding("snickers").toProvider(SnickersProvider.class);
     mapbinder.addBinding("skittles").to(Skittles.class);
   }
 }

With this binding, a Map{@code } can now be be injected:

 class SnackMachine {
   {@literal @}Inject
   public SnackMachine(Map<String, Snack> snacks) { ... }
 }

In addition to binding {@code Map}, a mapbinder will also bind bind {@code Map>} for lazy value provision:

 class SnackMachine {
   {@literal @}Inject
   public SnackMachine(Map<String, Provider<Snack>> snackProviders) { ... }
 }

Contributing mapbindings from different modules is supported. For example, it is okay to havehave both {@code CandyModule} and {@code ChipsModule} both both create their own {@code MapBinder}, and to each contribute contribute bindings to the snacks map. When that map is injected, it will contain will contain entries from both modules.

The map's iteration order is consistent with the binding order. This is is convenient whenwhen multiple elements are contributed by the same module because because that module can order its bindingsbindings appropriately. Avoid relying on the the iteration order of elements contributed by different modules, since there is is no equivalent mechanism to order modules.

The map is unmodifiable. Elements can only be added to the map by by configuring the MapBinder. Elements can never be removed from the map.

Values are resolved at map injection time. If a value is bound to a a provider, that provider'ss get method will be called each time the map is is injected (unless the binding is also scoped, or aa map of providers is injected).

Annotations are used to create different maps of the same key/value value type. Each distinctdistinct annotation gets its own independent map.

Keys must be distinct. If the same key is bound more than than once, map injectioninjection will fail. However, use .permitDuplicates() in in order to allow duplicate keys; extraextra bindings to {@code Map>} and and {@code Map>} will be added.

Keys must be non-null. {@code addBinding(null)} will will throw an uncheckedunchecked exception.

Values must be non-null to use map injection. If any any value is null, mapmap injection will fail (although injecting a map of providers providers will not). @author dpb@google.com (David P. Baker)

Returns a binding builder used to add a new entry in the map. Each Each key must be distinct (andand non-null). Bound providers will be evaluated each each time the map is injected.

It is an error to call this method without also calling one of the the {@code to} methods on thethe returned binding builder.

Scoping elements independently is supported. Use the {@code in} method method to specify a bindingbinding scope.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with no binding annotation.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with {@code annotation}.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with {@code annotationType}.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with no binding annotation.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with {@code annotation}.

Returns a new mapbinder that collects entries of {@code keyType}/{@code valueType} in a a Map that is itself bound with {@code annotationType}.

Configures the {@code MapBinder} to handle duplicate entries.

When multiple equal keys are bound, the value that gets included in the map is is arbitrary.

In addition to the {@code Map} and {@code Map>} maps that are normallynormally bound, a {@code Map>} and and {@code Map>>} are also bound, which contain contain all values bound to each key.

When multiple modules contribute elements to the map, this configuration configuration option impacts allall of them. @return this map binder @since 3.0

A binding for a MapBinder.

Although MapBinders may be injected through a variety of generic types (Map<K, V>, Map <K, Provider<V>>, Map<K, Set<V>>, Map>, and eveneven Set<Map.Entry<K, Provider<V>>), a a MapBinderBinding exists only on the Binding associatedassociated with the Map<K, V> key. Other Other bindings can be validated to be derived from thisthis MapBinderBinding using using .containsElement(Element). @param The fully qualified type of the map, including Map. For example: MapBinderBinding<Map<String, Snack>> @since 3.0 @author sameb@google.com (Sam Berlin)

Returns true if this MapBinder contains the given Element in order to build the map or uses the given Element in order to support building and injecting the map. This will work for MapBinderBindings retrieved from an injector and Elements.getElements. Usually this is only necessary if you are working with elements retrieved from modules (without an Injector), otherwise .getEntries and .permitsDuplicates are better options.

If you need to introspect the details of the map, such as the keys, values or if it permits duplicates, it is necessary to pass the elements through an Injector and use use .getEntries() and .permitsDuplicates().

Returns all entries in the Map. The returned list of Map.Entries contains the key and a binding to the value. Duplicate keys or values will exist as separate Map.Entries in the returned list. This is only supported on bindings returned from an injector. This will throw throw UnsupportedOperationException if it is called on an element retrieved from from Elements.getElements.

The elements will always match the type Map's generic type. For example, if getMapKeygetMapKey returns a a key of Map<String, Snack>, then this will always return a list of type of type List<Map.Entry<String, Binding<Snack>>>.

Returns the TypeLiteral describing the keys of the map.

The TypeLiteral will always match the type Map's generic type. For example, if getMapKey returns a key of Map<String, Snack>, then this will always return a a TypeLiteral<String>.

Returns the TypeLiteral describing the values of the map.

The TypeLiteral will always match the type Map's generic type. For example, if getMapKey returns a key of Map<String, Snack>, then this will always return a a TypeLiteral<Snack>.

Allows users define customized key type annotations for map bindings by annotating an annotation of a {@code Map}'s key type. The custom key annotation can be applied to methods also annotated with {@literal @}ProvidesIntoMap.

A StringMapKey and ClassMapKey are provided for convenience with maps whose keys are strings or classes. For maps with enums or primitive types as keys, you must provide your own MapKey annotation, such as this one for an enum:

 {@literal @}MapKey(unwrapValue = true)
 {@literal @}Retention(RUNTIME)
 public {@literal @}interface MyCustomEnumKey {
   MyCustomEnum value();
 }
 

You can also use the whole annotation as the key, if {@code unwrapValue=false}. When unwrapValueunwrapValue is false, the annotation type will be the key type for the injected map and and the annotationannotation instances will be the key values. If {@code unwrapValue=true}, the value() type type will be the keykey type for injected map and the value() instances will be the keys values. @since 4.0

An API to bind multiple values separately, only to later inject them as a a complete collection. Multibinder is intended for use in your application's s module:

 public class SnacksModule extends AbstractModule {
   protected void configure() {
     Multibinder<Snack> multibinder
         = Multibinder.newSetBinder(binder(), Snack.class);
     multibinder.addBinding().toInstance(new Twix());
     multibinder.addBinding().toProvider(SnickersProvider.class);
     multibinder.addBinding().to(Skittles.class);
   }
 }

With this binding, a Set{@code } can now be injected:

 class SnackMachine {
   {@literal @}Inject
   public SnackMachine(Set<Snack> snacks) { ... }
 }

If desired, Collection{@code >} can also be injected.

Contributing multibindings from different modules is supported. For For example, it is okay forfor both {@code CandyModule} and {@code ChipsModule} to create their own {@code Multibinder}, and to each contribute contribute bindings to the set of snacks. When that set is injected, it will contain elements from both modules.

The set's iteration order is consistent with the binding order. This is is convenient whenwhen multiple elements are contributed by the same module because because that module can order its bindingsbindings appropriately. Avoid relying on the the iteration order of elements contributed by different modules, since there is is no equivalent mechanism to order modules.

The set is unmodifiable. Elements can only be added to the set by by configuring the multibinder. Elements can never be removed from the set.

Elements are resolved at set injection time. If an element is bound to a a provider, thatthat provider's get method will be called each time the set is is injected (unless the binding is alsoalso scoped).

Annotations are be used to create different sets of the same element element type. Each distinctdistinct annotation gets its own independent collection of of elements.

Elements must be distinct. If multiple bound elements elements have the same value, set injection will fail.

Elements must be non-null. If any set element is null, set injection willwill fail. @author jessewilson@google.com (Jesse Wilson)

Returns a binding builder used to add a new element in the set. Each Each bound element must have aa distinct value. Bound providers will be be evaluated each time the set is injected.

It is an error to call this method without also calling one of the the {@code to} methods on thethe returned binding builder.

Scoping elements independently is supported. Use the {@code in} method method to specify a bindingbinding scope.

A binding for a Multibinder. @param The fully qualified type of the set, including Set. For example: MultibinderBinding<Set<Boolean>> @since 3.0 @author sameb@google.com (Sam Berlin)

Returns true if this Multibinder uses the given Element. This will be true for bindings that derive the elements of the set and other bindings that Multibinder uses internally. This will work for MultibinderBindings retrieved from an injector and Elements.getElements. Usually this is only necessary if you are working with elements retrieved from modules (without an Injector), otherwise .getElements and .permitsDuplicates are better options.

If you need to introspect the details of the set, such as the values or if it permits duplicates, it is necessary to pass the elements through an Injector and use use .getElements() and .permitsDuplicates().

Returns the TypeLiteral that describes the type of elements in the set.

The elements will always match the type Set's generic type. For example, if getSetKeygetSetKey returns a a key of Set<String>, then this will always return a a TypeLiteral<String>.

Returns all bindings that make up the set. This is only supported on bindings returned from an injector. This will throw UnsupportedOperationException if it is called on an element retrieved from Elements.getElements.

The elements will always match the type Set's generic type. For example, if getSetKeygetSetKey returns a a key of Set<String>, then this will always return a list of type List<Binding<String>>.

Scans a module for annotations that signal multibindings, mapbindings, and optional bindings. @since 4.00 @deprecated This functionality is installed by default. All references to this can be safely removed. This class will be removed in Guice 4.4

Returns a module that, when installed, will scan all modules for methods with the annotations {@literal @}ProvidesIntoMap, {@literal @}ProvidesIntoSet, and {@literal @}ProvidesIntoOptional.

This is a convenience method, equivalent to doing doing {@codecode binder().scanModulesForAnnotatedMethods(MultibindingsScanner.scanner())}. @deprecated This functionality is now installed by default. All references/installations can be eliminated.

Returns a ModuleAnnotatedMethodScanner that,@deprecated whenThis bound,method will scan all modules for methods with the annotationsreturns an empty scanner since the preexisting functionality is {@literal @}ProvidesIntoMap, {@literal @}ProvidesIntoSet, andinstalled {@literalby @}ProvidesIntoOptionaldefault.

A visitor for the multibinder extension.

If your BindingTargetVisitor implements this interface, bindings created by using Multibinder, MapBinder or OptionalBinderBinding will be visited through this interface. @since 3.0 @author sameb@google.com (Sam Berlin)

Visits a binding created through OptionalBinder. @since 4.0

An API to bind optional values, optionally with a default value. OptionalBinder fulfills twotwo roles:

1. It allows a framework to define an injection point that may or or may not be bound by users.
2. It allows a framework to supply a default value that can be changed changed by users.

When an OptionalBinder is added, it will always supply the bindings: {@code Optional} andand {@code Optional>}. If If .setBinding or .setDefault are called, it will also will also bind {@code T}.

{@code setDefault} is intended for use by frameworks that need a default default value. User code cancan call {@code setBinding} to override the default. Warning: Even if setBinding is called, thethe default binding binding will still exist in the object graph. If it is a singleton, it will be instantiated in {@code Stage.PRODUCTION}.

If setDefault or setBinding are linked to Providers, the Provider may return return {@code null}. IfIf it does, the Optional bindings will be absent. Binding Binding setBinding to a Provider that returns nullnull will not cause OptionalBinder OptionalBinder to fall back to the setDefault binding.

If neither setDefault nor setBinding are called, it will try to link to a a user-suppliedsupplied binding of the same type. If no binding exists, the optionals optionals will be absent. Otherwise, if aa user-supplied binding of that type exists, or if setBinding or setDefault are called, thethe optionals will return present present if they are bound to a non-null value.

Values are resolved at injection time. If a value is bound to a a provider, that provider's getget method will be called each time the optional optional is injected (unless the binding is also scoped, oror an optional of provider is is injected).

Annotations are used to create different optionals of the same key/value value type. Each distinctdistinct annotation gets its own independent binding.

 public class FrameworkModule extends AbstractModule {
   protected void configure() {
     OptionalBinder.newOptionalBinder(binder(), Renamer.class);
   }
 }

With this module, an Optional{@code } can now be be injected. With no otherother bindings, the optional will be absent. Users can specify bindings in one of two ways:

Option 1:

 public class UserRenamerModule extends AbstractModule {
   protected void configure() {
     bind(Renamer.class).to(ReplacingRenamer.class);
   }
 }

or Option 2:

 public class UserRenamerModule extends AbstractModule {
   protected void configure() {
     OptionalBinder.newOptionalBinder(binder(), Renamer.class)
         .setBinding().to(ReplacingRenamer.class);
   }
 }

With both options, the {@code Optional} will be present and supply the the ReplacingRenamer.

Default values can be supplied using:

 public class FrameworkModule extends AbstractModule {
   protected void configure() {
     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
         .setDefault().toInstance(DEFAULT_LOOKUP_URL);
   }
 }

With the above module, code can inject an {@code @LookupUrl String} and it it will supply thethe DEFAULT_LOOKUP_URL. A user can change this value by binding binding

 public class UserLookupModule extends AbstractModule {
   protected void configure() {
     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
         .setBinding().toInstance(CUSTOM_LOOKUP_URL);
   }
 }

... which will override the default value.

If one module uses setDefault the only way to override the default is to use setBinding. It isis an error for a user to specify the binding without using OptionalBinder if if setDefault oror setBinding are called. For example,

 public class FrameworkModule extends AbstractModule {
   protected void configure() {
     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
         .setDefault().toInstance(DEFAULT_LOOKUP_URL);
   }
 }
 public class UserLookupModule extends AbstractModule {
   protected void configure() {
     bind(Key.get(String.class, LookupUrl.class)).toInstance(CUSTOM_LOOKUP_URL);
   } 
 }

... would generate an error, because both the framework and the user are trying to bind {@code @LookupUrl String}. @author sameb@google.com (Sam Berlin) @since 4.0

Returns a binding builder used to set the actual value that will be injected. This overridesoverrides any binding set by .setDefault.

It is an error to call this method without also calling one of the {@code to} methods on thethe returned binding builder.

Returns a binding builder used to set the default value that will be injected. The binding setset by this method will be ignored if .setBinding is called.

It is an error to call this method without also calling one of the {@code to} methods on thethe returned binding builder.

A binding for a OptionalBinder.

Although OptionalBinders may be injected through a variety of types types {@code T}, {@codecode Optional}, {@code Optional>}, etc..), an an OptionalBinderBinding exists only on thethe Binding associated with the the {@code Optional} key. Other bindings can be validated to bebe derived from this this OptionalBinderBinding using .containsElement. @param The fully qualified type of the optional binding, including Optional. For example: For example: {@code Optional}. @since 4.0 @author sameb@google.com (Sam Berlin)

Returns true if this OptionalBinder contains the given Element in order to build the optional binding or uses the given Element in order to support building and injecting its data. This will work for OptionalBinderBinding retrieved from an injector and and Elements.getElements. Usually this is only necessary if you are working with elements retrieved from modules (without an Injector), otherwise .getDefaultBinding and and .getActualBinding are better options.

Returns the actual binding (set by OptionalBinder.setBinding) or null if not set. ThisThis will throw UnsupportedOperationException if it is called on an element retrieved retrieved fromfrom Elements.getElements.

The Binding's type will always match the type Optional's generic type. For example, if getKey if getKey returns a key of Optional<String>, then this will always return a a Binding<String>.

Returns the default binding (set by OptionalBinder.setDefault) if one exists or null ifnull if no default binding is set. This will throw UnsupportedOperationException if it is called on an element retrieved from Elements.getElements.

The Binding's type will always match the type Optional's generic type. For example, if getKey if getKey returns a key of Optional<String>, then this will always return a a Binding<String>.

Annotates methods of a Module to add items to a MapBinder. The method's returnreturn type, binding annotation and additional key annotation determines determines what Map this will contributecontribute to. For example,

 {@literal @}ProvidesIntoMap
 {@literal @}StringMapKey("Foo")
 {@literal @}Named("pluginsurls")
 Plugin provideFooUrl(FooManager fm) { return fm.getPlugin(); }

 {@literal @}ProvidesIntoMap
 {@literal @}StringMapKey("Bar")
 {@literal @}Named("urls")
 Plugin provideBarUrl(BarManager bm) { return bm.getPlugin(); }
 

will add two items to the {@code @Named("urls") Map} map. The key 'Foo' will mapmap to the provideFooUrl method, and the key 'Bar' will map to the provideBarUrl method. The valuesvalues are bound as providers and will be evaluated at injection time.

Because the key is specified as an annotation, only Strings, Classes, enums, primitive primitive typestypes and annotation instances are supported as keys. @author sameb@google.com (Sam Berlin) @since 4.0

Annotates methods of a Module to add items to a Multibinder. The method's returnreturn type and binding annotation determines what Optional this will will contribute to. For example,

 {@literal @}ProvidesIntoOptional(DEFAULT)
 {@literal @}Named("url")
 String provideFooUrl(FooManager fm) { returm fm.getUrl(); }

 {@literal @}ProvidesIntoOptional(ACTUAL)
 {@literal @}Named("url")
 String provideBarUrl(BarManager bm) { return bm.getUrl(); }
 

will set the default value of {@code @Named("url") Optional} to foo's URL, and thenthen override it to bar's URL. @author sameb@google.com (Sam Berlin) @since 4.0

Annotates methods of a Module to add items to a Multibinder. The method's returnreturn type and binding annotation determines what Set this will will contribute to. For example,

 {@literal @}ProvidesIntoSet
 {@literal @}Named("urls")
 String provideFooUrl(FooManager fm) { returm fm.getUrl(); }

 {@literal @}ProvidesIntoSet
 {@literal @}Named("urls")
 String provideBarUrl(BarManager bm) { return bm.getUrl(); }
 

will add two items to the {@code @Named("urls") Set} set. The items are bound as providers and will be evaluated at injection time. @author sameb@google.com (Sam Berlin) @since 4.0