com.google.common.collect

Class ImmutableMap.Builder<K,V>

java.lang.Object

com.google.common.collect.ImmutableMap.Builder<K,V>

Direct Known Subclasses:

ImmutableBiMap.Builder, ImmutableSortedMap.Builder

Enclosing class:

ImmutableMap<K,V>

@DoNotMock
public static class ImmutableMap.Builder<K,V>
extends Object

A builder for creating immutable map instances, especially public static final maps ("constant maps"). Example:

 static final ImmutableMap<String, Integer> WORD_TO_INT =
     new ImmutableMap.Builder<String, Integer>()
         .put("one", 1)
         .put("two", 2)
         .put("three", 3)
         .build();
 

For small immutable maps, the ImmutableMap.of() methods are even more convenient.

By default, a Builder will generate maps that iterate over entries in the order they were inserted into the builder, equivalently to LinkedHashMap. For example, in the above example, WORD_TO_INT.entrySet() is guaranteed to iterate over the entries in the order "one"=1, "two"=2, "three"=3, and keySet() and values() respect the same order. If you want a different order, consider using ImmutableSortedMap to sort by keys, or call orderEntriesByValue(Comparator), which changes this builder to sort entries by value.

Builder instances can be reused - it is safe to call build() multiple times to build multiple maps in series. Each map is a superset of the maps created before it.

Since:

2.0

Constructor Summary

Constructors

Constructor and Description
Builder() Creates a new builder.

Method Summary

Modifier and Type	Method and Description
ImmutableMap<K,V>	build() Returns a newly-created immutable map.
ImmutableMap.Builder<K,V>	orderEntriesByValue(Comparator<? super V> valueComparator) Configures this Builder to order entries by value according to the specified comparator.
ImmutableMap.Builder<K,V>	put(K key, V value) Associates key with value in the built map.
ImmutableMap.Builder<K,V>	put(Map.Entry<? extends K,? extends V> entry) Adds the given entry to the map, making it immutable if necessary.
ImmutableMap.Builder<K,V>	putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries) Adds all of the given entries to the built map.
ImmutableMap.Builder<K,V>	putAll(Map<? extends K,? extends V> map) Associates all of the given map's keys and values in the built map.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Creates a new builder. The returned builder is equivalent to the builder generated by ImmutableMap.builder().

Method Detail

put

@CanIgnoreReturnValue
public ImmutableMap.Builder<K,V> put(K key,
                                                           V value)

Associates key with value in the built map. Duplicate keys are not allowed, and will cause build() to fail.

put

@CanIgnoreReturnValue
public ImmutableMap.Builder<K,V> put(Map.Entry<? extends K,? extends V> entry)

Adds the given entry to the map, making it immutable if necessary. Duplicate keys are not allowed, and will cause build() to fail.

Since:

11.0

putAll

@CanIgnoreReturnValue
public ImmutableMap.Builder<K,V> putAll(Map<? extends K,? extends V> map)

Associates all of the given map's keys and values in the built map. Duplicate keys are not allowed, and will cause build() to fail.

Throws:

NullPointerException - if any key or value in map is null

putAll

@CanIgnoreReturnValue
 @Beta
public ImmutableMap.Builder<K,V> putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)

Adds all of the given entries to the built map. Duplicate keys are not allowed, and will cause build() to fail.

Throws:

NullPointerException - if any key, value, or entry is null

Since:

19.0

orderEntriesByValue

@CanIgnoreReturnValue
 @Beta
public ImmutableMap.Builder<K,V> orderEntriesByValue(Comparator<? super V> valueComparator)

Configures this Builder to order entries by value according to the specified comparator.

The sort order is stable, that is, if two entries have values that compare as equivalent, the entry that was inserted first will be first in the built map's iteration order.

Throws:

IllegalStateException - if this method was already called

Since:

19.0

build

public ImmutableMap<K,V> build()

Returns a newly-created immutable map. The iteration order of the returned map is the order in which entries were inserted into the builder, unless orderEntriesByValue(java.util.Comparator<? super V>) was called, in which case entries are sorted by value.

Throws:

IllegalArgumentException - if duplicate keys were added