Class ImmutableMultimap.Builder<K,V>

java.lang.Object
com.google.common.collect.ImmutableMultimap.Builder<K,V>
Direct Known Subclasses:
ImmutableListMultimap.Builder, ImmutableSetMultimap.Builder
Enclosing class:
ImmutableMultimap<K,V>

public static class ImmutableMultimap.Builder<K,V> extends Object
A builder for creating immutable multimap instances, especially public static final multimaps ("constant multimaps"). Example:

 static final Multimap<String, Integer> STRING_TO_INTEGER_MULTIMAP =
     new ImmutableMultimap.Builder<String, Integer>()
         .put("one", 1)
         .putAll("several", 1, 2, 3)
         .putAll("many", 1, 2, 3, 4, 5)
         .build();
 

Builder instances can be reused; it is safe to call build() multiple times to build multiple multimaps in series. Each multimap contains the key-value mappings in the previously created multimaps.

Since:
2.0
  • Field Details

  • Constructor Details

    • Builder

      public Builder()
      Creates a new builder. The returned builder is equivalent to the builder generated by ImmutableMultimap.builder().
    • Builder

      Builder(int expectedKeys)
      Creates a new builder with a hint for the number of distinct keys.
  • Method Details

    • ensureBuilderMapNonNull

      Map<K,ImmutableCollection.Builder<V>> ensureBuilderMapNonNull()
    • newValueCollectionBuilderWithExpectedSize

      ImmutableCollection.Builder<V> newValueCollectionBuilderWithExpectedSize(int expectedSize)
    • expectedValuesPerKey

      public ImmutableMultimap.Builder<K,V> expectedValuesPerKey(int expectedValuesPerKey)
      Provides a hint for how many values will be associated with each key newly added to the builder after this call. This does not change semantics, but may improve performance if expectedValuesPerKey is a good estimate.

      This may be called more than once; each newly added key will use the most recent call to expectedValuesPerKey as its hint.

      Throws:
      IllegalArgumentException - if expectedValuesPerKey is negative
      Since:
      33.3.0
    • expectedValueCollectionSize

      int expectedValueCollectionSize(int defaultExpectedValues, Iterable<?> values)
      By default, if we are handed a value collection bigger than expectedValuesPerKey, presize to accept that many elements.

      This gets overridden in ImmutableSetMultimap.Builder to only trust the size of values if it is a Set and therefore probably already deduplicated.

    • put

      public ImmutableMultimap.Builder<K,V> put(K key, V value)
      Adds a key-value mapping to the built multimap.
    • put

      public ImmutableMultimap.Builder<K,V> put(Map.Entry<? extends K,? extends V> entry)
      Adds an entry to the built multimap.
      Since:
      11.0
    • putAll

      public ImmutableMultimap.Builder<K,V> putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)
      Adds entries to the built multimap.
      Since:
      19.0
    • putAll

      public ImmutableMultimap.Builder<K,V> putAll(K key, Iterable<? extends V> values)
      Stores a collection of values with the same key in the built multimap.
      Throws:
      NullPointerException - if key, values, or any element in values is null. The builder is left in an invalid state.
    • putAll

      public ImmutableMultimap.Builder<K,V> putAll(K key, V... values)
      Stores an array of values with the same key in the built multimap.
      Throws:
      NullPointerException - if the key or any value is null. The builder is left in an invalid state.
    • putAll

      public ImmutableMultimap.Builder<K,V> putAll(Multimap<? extends K,? extends V> multimap)
      Stores another multimap's entries in the built multimap. The generated multimap's key and value orderings correspond to the iteration ordering of the multimap.asMap() view, with new keys and values following any existing keys and values.
      Throws:
      NullPointerException - if any key or value in multimap is null. The builder is left in an invalid state.
    • orderKeysBy

      public ImmutableMultimap.Builder<K,V> orderKeysBy(Comparator<? super K> keyComparator)
      Specifies the ordering of the generated multimap's keys.
      Since:
      8.0
    • orderValuesBy

      public ImmutableMultimap.Builder<K,V> orderValuesBy(Comparator<? super V> valueComparator)
      Specifies the ordering of the generated multimap's values for each key.
      Since:
      8.0
    • combine

    • build

      public ImmutableMultimap<K,V> build()
      Returns a newly-created immutable multimap.