com.google.common.collect

## 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 java.lang.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

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImmutableMultimap.Builder()` Creates a new builder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableMultimap<K,V>` | `build()` Returns a newly-created immutable multimap.
    `ImmutableMultimap.Builder<K,V>` | `orderKeysBy(java.util.Comparator<? super K> keyComparator)` Specifies the ordering of the generated multimap's keys.
    `ImmutableMultimap.Builder<K,V>` | `orderValuesBy(java.util.Comparator<? super V> valueComparator)` Specifies the ordering of the generated multimap's values for each key.
    `ImmutableMultimap.Builder<K,V>` | `put(K key, V value)` Adds a key-value mapping to the built multimap.
    `ImmutableMultimap.Builder<K,V>` | `put(java.util.Map.Entry<? extends K,? extends V> entry)` Adds an entry to the built multimap.
    `ImmutableMultimap.Builder<K,V>` | `putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)` Adds entries to the built multimap.
    `ImmutableMultimap.Builder<K,V>` | `putAll(K key, java.lang.Iterable<? extends V> values)` Stores a collection of values with the same key in the built multimap.
    `ImmutableMultimap.Builder<K,V>` | `putAll(K key, V... values)` Stores an array of values with the same key in the built multimap.
    `ImmutableMultimap.Builder<K,V>` | `putAll(Multimap<? extends K,? extends V> multimap)` Stores another multimap's entries in the built multimap.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ImmutableMultimap.Builder

          public ImmutableMultimap.Builder()

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

  - ### Method Detail

    - #### 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(java.util.Map.Entry<? extends K,? extends V> entry)

      Adds an entry to the built multimap.
      Since:
        11.0

    - #### putAll

          @Beta
          public ImmutableMultimap.Builder<K,V> putAll(java.lang.Iterable<? extends java.util.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,
                                              java.lang.Iterable<? extends V> values)

      Stores a collection of values with the same key in the built multimap.
      Throws:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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(java.util.Comparator<? super K> keyComparator)

      Specifies the ordering of the generated multimap's keys.
      Since:
        8.0

    - #### orderValuesBy

          public ImmutableMultimap.Builder<K,V> orderValuesBy(java.util.Comparator<? super V> valueComparator)

      Specifies the ordering of the generated multimap's values for each key.
      Since:
        8.0

    - #### build

          public ImmutableMultimap<K,V> build()

      Returns a newly-created immutable multimap.