ImmutableMap
Date: 2016-05-24

com.google.common.collect

## Class ImmutableMap<K,V>

- java.lang.Object
- - com.google.common.collect.ImmutableMap<K,V>

- All Implemented Interfaces:
    java.io.Serializable, java.util.Map<K,V>
  Direct Known Subclasses:
    ImmutableBiMap, ImmutableSortedMap

      @GwtCompatible(serializable=true,
                     emulated=true)
      public abstract class ImmutableMap<K,V>
      extends java.lang.Object
      implements java.util.Map<K,V>, java.io.Serializable

  A `Map` whose contents will never change, with many other important properties detailed at `ImmutableCollection`.

  See the Guava User Guide article on immutable collections.

  Since:
    2.0
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ImmutableMap.Builder<K,V>` A builder for creating immutable map instances, especially `public static final` maps ("constant maps").

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `java.util.Map.Entry<K,V>`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableSetMultimap<K,V>` | `asMultimap()` Returns a multimap view of the map.
    `static <K,V> ImmutableMap.Builder<K,V>` | `builder()` Returns a new builder.
    `void` | `clear()` Deprecated. Unsupported operation.
    `boolean` | `containsKey(java.lang.Object key)`
    `boolean` | `containsValue(java.lang.Object value)`
    `static <K,V> ImmutableMap<K,V>` | `copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)` Returns an immutable map containing the specified entries.
    `static <K,V> ImmutableMap<K,V>` | `copyOf(java.util.Map<? extends K,? extends V> map)` Returns an immutable map containing the same entries as `map`.
    `ImmutableSet<java.util.Map.Entry<K,V>>` | `entrySet()` Returns an immutable set of the mappings in this map.
    `boolean` | `equals(java.lang.Object object)`
    `abstract V` | `get(java.lang.Object key)`
    `int` | `hashCode()`
    `boolean` | `isEmpty()`
    `ImmutableSet<K>` | `keySet()` Returns an immutable set of the keys in this map.
    `static <K,V> ImmutableMap<K,V>` | `of()` Returns the empty map.
    `static <K,V> ImmutableMap<K,V>` | `of(K k1, V v1)` Returns an immutable map containing a single entry.
    `static <K,V> ImmutableMap<K,V>` | `of(K k1, V v1, K k2, V v2)` Returns an immutable map containing the given entries, in order.
    `static <K,V> ImmutableMap<K,V>` | `of(K k1, V v1, K k2, V v2, K k3, V v3)` Returns an immutable map containing the given entries, in order.
    `static <K,V> ImmutableMap<K,V>` | `of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)` Returns an immutable map containing the given entries, in order.
    `static <K,V> ImmutableMap<K,V>` | `of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)` Returns an immutable map containing the given entries, in order.
    `V` | `put(K k, V v)` Deprecated. Unsupported operation.
    `void` | `putAll(java.util.Map<? extends K,? extends V> map)` Deprecated. Unsupported operation.
    `V` | `remove(java.lang.Object o)` Deprecated. Unsupported operation.
    `java.lang.String` | `toString()`
    `ImmutableCollection<V>` | `values()` Returns an immutable collection of the values in this map.

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Map

      `size`

- - ### Method Detail

    - #### of

          public static <K,V> ImmutableMap<K,V> of()

      Returns the empty map. This map behaves and performs comparably to `Collections.emptyMap()`, and is preferable mainly for consistency and maintainability of your code.

    - #### of

          public static <K,V> ImmutableMap<K,V> of(K k1,
                                   V v1)

      Returns an immutable map containing a single entry. This map behaves and performs comparably to `Collections.singletonMap(K, V)` but will not accept a null key or value. It is preferable mainly for consistency and maintainability of your code.

    - #### of

          public static <K,V> ImmutableMap<K,V> of(K k1,
                                   V v1,
                                   K k2,
                                   V v2)

      Returns an immutable map containing the given entries, in order.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys are provided

    - #### of

          public static <K,V> ImmutableMap<K,V> of(K k1,
                                   V v1,
                                   K k2,
                                   V v2,
                                   K k3,
                                   V v3)

      Returns an immutable map containing the given entries, in order.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys are provided

    - #### of

          public static <K,V> ImmutableMap<K,V> of(K k1,
                                   V v1,
                                   K k2,
                                   V v2,
                                   K k3,
                                   V v3,
                                   K k4,
                                   V v4)

      Returns an immutable map containing the given entries, in order.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys are provided

    - #### of

          public static <K,V> ImmutableMap<K,V> of(K k1,
                                   V v1,
                                   K k2,
                                   V v2,
                                   K k3,
                                   V v3,
                                   K k4,
                                   V v4,
                                   K k5,
                                   V v5)

      Returns an immutable map containing the given entries, in order.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys are provided

    - #### builder

          public static <K,V> ImmutableMap.Builder<K,V> builder()

      Returns a new builder. The generated builder is equivalent to the builder created by the `ImmutableMap.Builder` constructor.

    - #### copyOf

          public static <K,V> ImmutableMap<K,V> copyOf(java.util.Map<? extends K,? extends V> map)

      Returns an immutable map containing the same entries as `map`. If `map` somehow contains entries with duplicate keys (for example, if it is a `SortedMap` whose comparator is not consistent with equals), the results of this method are undefined.

      Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

      Throws:
        `java.lang.NullPointerException` - if any key or value in `map` is null

    - #### copyOf

          @Beta
          public static <K,V> ImmutableMap<K,V> copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)

      Returns an immutable map containing the specified entries. The returned map iterates over entries in the same order as the original iterable.
      Throws:
        `java.lang.NullPointerException` - if any key, value, or entry is null
        `java.lang.IllegalArgumentException` - if two entries have the same key
      Since:
        19.0

    - #### put

          @Deprecated
          public final V put(K k,
                         V v)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `put` in interface `java.util.Map<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### remove

          @Deprecated
          public final V remove(java.lang.Object o)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `remove` in interface `java.util.Map<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### putAll

          @Deprecated
          public final void putAll(java.util.Map<? extends K,? extends V> map)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `putAll` in interface `java.util.Map<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### clear

          @Deprecated
          public final void clear()

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `clear` in interface `java.util.Map<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `java.util.Map<K,V>`

    - #### containsKey

          public boolean containsKey(@Nullable
                            java.lang.Object key)

      Specified by:
        `containsKey` in interface `java.util.Map<K,V>`

    - #### containsValue

          public boolean containsValue(@Nullable
                              java.lang.Object value)

      Specified by:
        `containsValue` in interface `java.util.Map<K,V>`

    - #### get

          public abstract V get(@Nullable
              java.lang.Object key)

      Specified by:
        `get` in interface `java.util.Map<K,V>`

    - #### entrySet

          public ImmutableSet<java.util.Map.Entry<K,V>> entrySet()

      Returns an immutable set of the mappings in this map. The entries are in the same order as the parameters used to build this map.
      Specified by:
        `entrySet` in interface `java.util.Map<K,V>`

    - #### keySet

          public ImmutableSet<K> keySet()

      Returns an immutable set of the keys in this map. These keys are in the same order as the parameters used to build this map.
      Specified by:
        `keySet` in interface `java.util.Map<K,V>`

    - #### values

          public ImmutableCollection<V> values()

      Returns an immutable collection of the values in this map. The values are in the same order as the parameters used to build this map.
      Specified by:
        `values` in interface `java.util.Map<K,V>`

    - #### asMultimap

          @Beta
          public ImmutableSetMultimap<K,V> asMultimap()

      Returns a multimap view of the map.
      Since:
        14.0

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object object)

      Specified by:
        `equals` in interface `java.util.Map<K,V>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Map<K,V>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`