Google Guice - Core Library 7.0.0 · com.google.inject.multibindings.MapBinder

An API to bind multiple map entries separately, only to later inject them 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<String, Snack> can now be injected:


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

In addition to binding Map<K, V>, a mapbinder will also bind Map<K, Provider<V>> for lazy value provision:


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

Contributing mapbindings from different modules is supported. For example, it is okay to have both CandyModule and ChipsModule both create their own MapBinder<String, Snack>, and to each contribute bindings to the snacks map. When that map is injected, it will contain entries from both modules.

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

The map is unmodifiable. Elements can only be added to the map 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 provider, that provider's get method will be called each time the map is injected (unless the binding is also scoped, or a map of providers is injected).

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

Keys must be distinct. If the same key is bound more than once, map injection will fail. However, use permitDuplicates() in order to allow duplicate keys; extra bindings to Map<K, Set<V>> and Map<K, Set<Provider<V>> will be added.

Keys must be non-null. addBinding(null) will throw an unchecked exception.

Values must be non-null to use map injection. If any value is null, map injection will fail (although injecting a map of providers will not).

Modifier and Type	Field and Description
private final RealMapBinder<K, V>	delegate

Access	Constructor and Description
private	MapBinder(RealMapBinder<K, V> delegate)

Method Summary

Modifier and Type	Method and Description
public LinkedBindingBuilder<V>	addBinding(K key) Returns a binding builder used to add a new entry in the map.
public boolean	equals(Object the reference object with which to compare. obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this object.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with no binding annotation.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with no binding annotation.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType, Annotation annotation) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotation`.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType, Annotation annotation) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotation`.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType, Class<? extends Annotation> annotationType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotationType`.
public static <K, V> MapBinder<K, V>	newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType, Class<? extends Annotation> annotationType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotationType`.
public MapBinder<K, V>	Returns: this map binder permitDuplicates() Configures the `MapBinder` to handle duplicate entries.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

delegate	back to summary
private final RealMapBinder<K, V> delegate

Constructor Detail

MapBinder	back to summary
private MapBinder(RealMapBinder<K, V> delegate)

Method Detail

addBinding back to summary

addBinding	back to summary
public LinkedBindingBuilder<V> addBinding(K key) Returns a binding builder used to add a new entry in the map. Each key must be distinct (and non-null). Bound providers will be evaluated each time the map is injected. It is an error to call this method without also calling one of the `to` methods on the returned binding builder. Scoping elements independently is supported. Use the `in` method to specify a binding scope.

public LinkedBindingBuilder<V> addBinding(K key)

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

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

Scoping elements independently is supported. Use the in method to specify a binding scope.

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. Doc from java.lang.Object.equals. Indicates whether some other object is "equal to" this one. The `equals` method implements an equivalence relation on non-null object references: It is reflexive: for any non-null reference value `x`, `x.equals(x)` should return `true`. It is symmetric: for any non-null reference values `x` and `y`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`. It is transitive: for any non-null reference values `x`, `y`, and `z`, if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`. It is consistent: for any non-null reference values `x` and `y`, multiple invocations of `x.equals(y)` consistently return `true` or consistently return `false`, provided no information used in `equals` comparisons on the objects is modified. For any non-null reference value `x`, `x.equals(null)` should return `false`. An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes. Parameters obj:Object the reference object with which to compare. Returns:boolean `true` if this object is the same as the obj argument; `false` otherwise. Annotations @Override

public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference value x, x.equals(x) should return true.
It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters

obj:Object: the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations

@Override

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. The general contract of `hashCode` is: Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables. Returns:int a hash code value for this object Annotations @Override

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns:int

a hash code value for this object

Annotations

@Override

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with no binding annotation.

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with no binding annotation.

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType, Annotation annotation) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotation`.

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType, Annotation annotation) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotation`.

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType, Class<? extends Annotation> annotationType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotationType`.

newMapBinder	back to summary
public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType, Class<? extends Annotation> annotationType) Returns a new mapbinder that collects entries of `keyType`/`valueType` in a `Map` that is itself bound with `annotationType`.

permitDuplicates back to summary

permitDuplicates	back to summary
public MapBinder<K, V> permitDuplicates() Configures the `MapBinder` to handle duplicate entries. When multiple equal keys are bound, the value that gets included in the map is arbitrary. In addition to the `Map<K, V>` and `Map<K, Provider<V>>` maps that are normally bound, a `Map<K, Set<V>>` and `Map<K, Set<Provider<V>>>` are also bound, which contain all values bound to each key. When multiple modules contribute elements to the map, this configuration option impacts all of them. Returns:MapBinder<K, V> this map binder Since 3.0

public MapBinder<K, V> permitDuplicates()

Configures the MapBinder to handle duplicate entries.

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

In addition to the Map<K, V> and Map<K, Provider<V>> maps that are normally bound, a Map<K, Set<V>> and Map<K, Set<Provider<V>>> are also bound, which contain all values bound to each key.

When multiple modules contribute elements to the map, this configuration option impacts all of them.

Returns:MapBinder<K, V>: this map binder
Since: 3.0

public Class MapBinder<K, V>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail