MultimapBuilder
Date: 2016-05-24

com.google.common.collect

## Class MultimapBuilder<K0,V0>

- java.lang.Object
- - com.google.common.collect.MultimapBuilder<K0,V0>

- Type Parameters:
    `K0` - An upper bound on the key type of the generated multimap.
    `V0` - An upper bound on the value type of the generated multimap.
  Direct Known Subclasses:
    MultimapBuilder.ListMultimapBuilder, MultimapBuilder.SetMultimapBuilder

      @Beta
      @GwtCompatible
      @CheckReturnValue
      public abstract class MultimapBuilder<K0,V0>
      extends java.lang.Object

  A builder for a multimap implementation that allows customization of the backing map and value collection implementations used in a particular multimap.

  This can be used to easily configure multimap data structure implementations not provided explicitly in `com.google.common.collect`, for example:

         ListMultimap<String, Integer> treeListMultimap =
             MultimapBuilder.treeKeys().arrayListValues().build();
         SetMultimap<Integer, MyEnum> hashEnumMultimap =
             MultimapBuilder.hashKeys().enumSetValues(MyEnum.class).build();

  `MultimapBuilder` instances are immutable. Invoking a configuration method has no effect on the receiving instance; you must store and use the new builder instance it returns instead.

  The generated multimaps are serializable if the key and value types are serializable, unless stated otherwise in one of the configuration methods.

  Since:
    16.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MultimapBuilder.ListMultimapBuilder<K0,V0>` A specialization of `MultimapBuilder` that generates `ListMultimap` instances.
    `static class` | `MultimapBuilder.MultimapBuilderWithKeys<K0>` An intermediate stage in a `MultimapBuilder` in which the key-value collection map implementation has been specified, but the value collection implementation has not.
    `static class` | `MultimapBuilder.SetMultimapBuilder<K0,V0>` A specialization of `MultimapBuilder` that generates `SetMultimap` instances.
    `static class` | `MultimapBuilder.SortedSetMultimapBuilder<K0,V0>` A specialization of `MultimapBuilder` that generates `SortedSetMultimap` instances.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract <K extends K0,V extends V0> Multimap<K,V>` | `build()` Returns a new, empty `Multimap` with the specified implementation.
    `<K extends K0,V extends V0> Multimap<K,V>` | `build(Multimap<? extends K,? extends V> multimap)` Returns a `Multimap` with the specified implementation, initialized with the entries of `multimap`.
    `static <K0 extends java.lang.Enum<K0>> MultimapBuilder.MultimapBuilderWithKeys<K0>` | `enumKeys(java.lang.Class<K0> keyClass)` Uses an `EnumMap` to map keys to value collections.
    `static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object>` | `hashKeys()` Uses a `HashMap` to map keys to value collections.
    `static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object>` | `hashKeys(int expectedKeys)` Uses a `HashMap` to map keys to value collections, initialized to expect the specified number of keys.
    `static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object>` | `linkedHashKeys()` Uses a `LinkedHashMap` to map keys to value collections.
    `static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object>` | `linkedHashKeys(int expectedKeys)` Uses a `LinkedHashMap` to map keys to value collections, initialized to expect the specified number of keys.
    `static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Comparable>` | `treeKeys()` Uses a naturally-ordered `TreeMap` to map keys to value collections.
    `static <K0> MultimapBuilder.MultimapBuilderWithKeys<K0>` | `treeKeys(java.util.Comparator<K0> comparator)` Uses a `TreeMap` sorted by the specified comparator to map keys to value collections.

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

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

- - ### Method Detail

    - #### hashKeys

          public static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object> hashKeys()

      Uses a `HashMap` to map keys to value collections.

    - #### hashKeys

          public static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object> hashKeys(int expectedKeys)

      Uses a `HashMap` to map keys to value collections, initialized to expect the specified number of keys.
      Throws:
        `java.lang.IllegalArgumentException` - if `expectedKeys < 0`

    - #### linkedHashKeys

          public static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object> linkedHashKeys()

      Uses a `LinkedHashMap` to map keys to value collections.

      The collections returned by `Multimap.keySet()`, `Multimap.keys()`, and `Multimap.asMap()` will iterate through the keys in the order that they were first added to the multimap, save that if all values associated with a key are removed and then the key is added back into the multimap, that key will come last in the key iteration order.

    - #### linkedHashKeys

          public static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Object> linkedHashKeys(int expectedKeys)

      Uses a `LinkedHashMap` to map keys to value collections, initialized to expect the specified number of keys.

      The collections returned by `Multimap.keySet()`, `Multimap.keys()`, and `Multimap.asMap()` will iterate through the keys in the order that they were first added to the multimap, save that if all values associated with a key are removed and then the key is added back into the multimap, that key will come last in the key iteration order.

    - #### treeKeys

          public static MultimapBuilder.MultimapBuilderWithKeys<java.lang.Comparable> treeKeys()

      Uses a naturally-ordered `TreeMap` to map keys to value collections.

      The collections returned by `Multimap.keySet()`, `Multimap.keys()`, and `Multimap.asMap()` will iterate through the keys in sorted order.

      For all multimaps generated by the resulting builder, the `Multimap.keySet()` can be safely cast to a `SortedSet`, and the `Multimap.asMap()` can safely be cast to a `SortedMap`.

    - #### treeKeys

          public static <K0> MultimapBuilder.MultimapBuilderWithKeys<K0> treeKeys(java.util.Comparator<K0> comparator)

      Uses a `TreeMap` sorted by the specified comparator to map keys to value collections.

      The collections returned by `Multimap.keySet()`, `Multimap.keys()`, and `Multimap.asMap()` will iterate through the keys in sorted order.

      For all multimaps generated by the resulting builder, the `Multimap.keySet()` can be safely cast to a `SortedSet`, and the `Multimap.asMap()` can safely be cast to a `SortedMap`.

      Multimaps generated by the resulting builder will not be serializable if `comparator` is not serializable.

    - #### enumKeys

          public static <K0 extends java.lang.Enum<K0>> MultimapBuilder.MultimapBuilderWithKeys<K0> enumKeys(java.lang.Class<K0> keyClass)

      Uses an `EnumMap` to map keys to value collections.

    - #### build

          public abstract <K extends K0,V extends V0> Multimap<K,V> build()

      Returns a new, empty `Multimap` with the specified implementation.

    - #### build

          public <K extends K0,V extends V0> Multimap<K,V> build(Multimap<? extends K,? extends V> multimap)

      Returns a `Multimap` with the specified implementation, initialized with the entries of `multimap`.