Package com.google.common.collect

Class ImmutableBiMap.Builder<K,V>

java.lang.Object

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

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

Enclosing class:

ImmutableBiMap<K,V>

public static final class ImmutableBiMap.Builder<K,V>
extends ImmutableMap.Builder<K,V>

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

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

For small immutable bimaps, the ImmutableBiMap.of() methods are even more convenient.

By default, a Builder will generate bimaps that iterate over entries in the order they were inserted into the builder. 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 orderEntriesByValue(Comparator), which changes this builder to sort entries by value.

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

Since:

2.0

Constructor Summary

Constructors

Constructor	Description
Builder()	Creates a new builder.

Method Summary

Modifier and Type	Method	Description
ImmutableBiMap<K,V>	build()	Returns a newly-created immutable bimap.
ImmutableBiMap<K,V>	buildKeepingLast()	Deprecated. This method does not make sense for bimaps and should not be called.
ImmutableBiMap<K,V>	buildOrThrow()	Returns a newly-created immutable bimap, or throws an exception if any key or value was added more than once.
ImmutableBiMap.Builder<K,V>	orderEntriesByValue(Comparator<? super V> valueComparator)	Configures this Builder to order entries by value according to the specified comparator.
ImmutableBiMap.Builder<K,V>	put(Map.Entry<? extends K,? extends V> entry)	Adds the given entry to the bimap.
ImmutableBiMap.Builder<K,V>	put(K key, V value)	Associates key with value in the built bimap.
ImmutableBiMap.Builder<K,V>	putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)	Adds all of the given entries to the built bimap.
ImmutableBiMap.Builder<K,V>	putAll(Map<? extends K,? extends V> map)	Associates all of the given map's keys and values in the built bimap.

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 ImmutableBiMap.builder().

Method Detail

put

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

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

Overrides:

put in class ImmutableMap.Builder<K,V>

put

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

Adds the given entry to the bimap. Duplicate keys or values are not allowed, and will cause build() to fail.

Overrides:

put in class ImmutableMap.Builder<K,V>

Since:

19.0

putAll

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

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

Overrides:

putAll in class ImmutableMap.Builder<K,V>

Throws:

NullPointerException - if any key or value in map is null

putAll

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

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

Overrides:

putAll in class ImmutableMap.Builder<K,V>

Throws:

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

Since:

19.0

orderEntriesByValue

@CanIgnoreReturnValue
@Beta
public ImmutableBiMap.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.

Overrides:

orderEntriesByValue in class ImmutableMap.Builder<K,V>

Throws:

IllegalStateException - if this method was already called

Since:

19.0

build

public ImmutableBiMap<K,V> build()

Returns a newly-created immutable bimap. The iteration order of the returned bimap 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.

Prefer the equivalent method buildOrThrow() to make it explicit that the method will throw an exception if there are duplicate keys or values. The build() method will soon be deprecated.

Overrides:

build in class ImmutableMap.Builder<K,V>

Throws:

IllegalArgumentException - if duplicate keys or values were added

buildOrThrow

public ImmutableBiMap<K,V> buildOrThrow()

Returns a newly-created immutable bimap, or throws an exception if any key or value was added more than once. The iteration order of the returned bimap 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.

Overrides:

buildOrThrow in class ImmutableMap.Builder<K,V>

Throws:

IllegalArgumentException - if duplicate keys or values were added

Since:

31.0

buildKeepingLast

@Deprecated
public ImmutableBiMap<K,V> buildKeepingLast()

Deprecated.

This method does not make sense for bimaps and should not be called.

Throws UnsupportedOperationException. This method is inherited from ImmutableMap.Builder, but it does not make sense for bimaps.

Overrides:

buildKeepingLast in class ImmutableMap.Builder<K,V>

Throws:

UnsupportedOperationException - always

Since:

31.1