Module com.google.common
Package com.google.common.collect

Class ImmutableMap<K,V>

java.lang.Object
com.google.common.collect.ImmutableMap<K,V>
All Implemented Interfaces:
Serializable, Map<K,V>
Direct Known Subclasses:
ImmutableBiMap, ImmutableSortedMap
@GwtCompatible(serializable=true, emulated=true) public abstract class ImmutableMap<K,V> extends Object implements Map<K,V>, 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:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    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

    Map.Entry<K extends Object,V extends Object>

  • Method Summary

    Modifier and Type
    Method
    Description
    ImmutableSetMultimap<K,V>
    asMultimap()
    Returns a multimap view of the map.
    static <K, V> ImmutableMap.Builder<K,V>
    builder()
    Returns a new builder.
    static <K, V> ImmutableMap.Builder<K,V>
    builderWithExpectedSize(int expectedSize)
    Returns a new builder, expecting the specified number of entries to be added.
    final void
    clear()
    Deprecated.
    Unsupported operation.
    final V
    compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    Deprecated.
    Unsupported operation.
    final V
    computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
    Deprecated.
    Unsupported operation.
    final V
    computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    Deprecated.
    Unsupported operation.
    boolean
    containsKey(Object key)
     
    boolean
    containsValue(Object value)
     
    static <K, V> ImmutableMap<K,V>
    copyOf(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)
    Returns an immutable map containing the specified entries.
    static <K, V> ImmutableMap<K,V>
    copyOf(Map<? extends K,? extends V> map)
    Returns an immutable map containing the same entries as map.
    ImmutableSet<Map.Entry<K,V>>
    entrySet()
    Returns an immutable set of the mappings in this map.
    boolean
    equals(Object object)
     
    abstract V
    get(Object key)
     
    final V
    getOrDefault(Object key, V defaultValue)
     
    int
    hashCode()
     
    boolean
    isEmpty()
     
    ImmutableSet<K>
    keySet()
    Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.
    final V
    merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
    Deprecated.
    Unsupported operation.
    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.
    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, K k6, V v6)
    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, K k6, V v6, K k7, V v7)
    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, K k6, V v6, K k7, V v7, K k8, V v8)
    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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
    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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
    Returns an immutable map containing the given entries, in order.
    static <K, V> ImmutableMap<K,V>
    ofEntries(Map.Entry<? extends K,? extends V>... entries)
    Returns an immutable map containing the given entries, in order.
    final V
    put(K k, V v)
    Deprecated.
    Unsupported operation.
    final void
    putAll(Map<? extends K,? extends V> map)
    Deprecated.
    Unsupported operation.
    final V
    putIfAbsent(K key, V value)
    Deprecated.
    Unsupported operation.
    final V
    remove(Object o)
    Deprecated.
    Unsupported operation.
    final boolean
    remove(Object key, Object value)
    Deprecated.
    Unsupported operation.
    final V
    replace(K key, V value)
    Deprecated.
    Unsupported operation.
    final boolean
    replace(K key, V oldValue, V newValue)
    Deprecated.
    Unsupported operation.
    final void
    replaceAll(BiFunction<? super K,? super V,? extends V> function)
    Deprecated.
    Unsupported operation.
    static <T, K, V> Collector<T,?,ImmutableMap<K,V>>
    toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction)
    Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
    static <T, K, V> Collector<T,?,ImmutableMap<K,V>>
    toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction, BinaryOperator<V> mergeFunction)
    Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
    String
    toString()
     
    ImmutableCollection<V>
    values()
    Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Map

    forEach, size

  • Method Details

    • toImmutableMap

      public static <T, K, V> Collector<T,?,ImmutableMap<K,V>> toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction)
      Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements. Entries appear in the result ImmutableMap in encounter order.

      If the mapped keys contain duplicates (according to Object.equals(Object), an IllegalArgumentException is thrown when the collection operation is performed. (This differs from the Collector returned by Collectors.toMap(Function, Function), which throws an IllegalStateException.)

      Since:
      21.0

    • toImmutableMap

      public static <T, K, V> Collector<T,?,ImmutableMap<K,V>> toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction, BinaryOperator<V> mergeFunction)
      Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

      If the mapped keys contain duplicates (according to Object.equals(Object)), the values are merged using the specified merging function. Entries will appear in the encounter order of the first occurrence of the key.

      Since:
      21.0

    • 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.

      Performance note: the instance returned is a singleton.

    • 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:
      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:
      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:
      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:
      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, K k6, V v6)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • 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, K k6, V v6, K k7, V v7)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • 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, K k6, V v6, K k7, V v7, K k8, V v8)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • 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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • 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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • ofEntries

      @SafeVarargs public static <K, V> ImmutableMap<K,V> ofEntries(Map.Entry<? extends K,? extends V>... entries)
      Returns an immutable map containing the given entries, in order.
      Throws:
      IllegalArgumentException - if duplicate keys are provided
      Since:
      31.0

    • 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.

    • builderWithExpectedSize

      @Beta public static <K, V> ImmutableMap.Builder<K,V> builderWithExpectedSize(int expectedSize)
      Returns a new builder, expecting the specified number of entries to be added.

      If expectedSize is exactly the number of entries added to the builder before ImmutableMap.Builder.build() is called, the builder is likely to perform better than an unsized builder() would have.

      It is not specified if any performance benefits apply if expectedSize is close to, but not exactly, the number of entries added to the builder.

      Since:
      23.1

    • copyOf

      public static <K, V> ImmutableMap<K,V> copyOf(Map<? extends K,? extends V> map)
      Returns an immutable map containing the same entries as map. The returned map iterates over entries in the same order as the entrySet of the original 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:
      NullPointerException - if any key or value in map is null

    • copyOf

      @Beta public static <K, V> ImmutableMap<K,V> copyOf(Iterable<? extends 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:
      NullPointerException - if any key, value, or entry is null
      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 Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • putIfAbsent

      @Deprecated public final V putIfAbsent(K key, V value)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      putIfAbsent in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • replace

      @Deprecated public final boolean replace(K key, V oldValue, V newValue)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      replace in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • replace

      @Deprecated public final V replace(K key, V value)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      replace in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • computeIfAbsent

      @Deprecated public final V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      computeIfAbsent in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • computeIfPresent

      @Deprecated public final V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      computeIfPresent in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • compute

      @Deprecated public final V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      compute in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • merge

      @Deprecated public final V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      merge in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • putAll

      @Deprecated public final void putAll(Map<? extends K,? extends V> map)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      putAll in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • replaceAll

      @Deprecated public final void replaceAll(BiFunction<? super K,? super V,? extends V> function)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      replaceAll in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • remove

      @Deprecated public final V remove(Object o)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      remove in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • remove

      @Deprecated public final boolean remove(Object key, Object value)
      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      remove in interface Map<K,V>
      Throws:
      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 Map<K,V>
      Throws:
      UnsupportedOperationException - always

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Map<K,V>

    • containsKey

      public boolean containsKey(Object key)
      Specified by:
      containsKey in interface Map<K,V>

    • containsValue

      public boolean containsValue(Object value)
      Specified by:
      containsValue in interface Map<K,V>

    • get

      public abstract V get(Object key)
      Specified by:
      get in interface Map<K,V>

    • getOrDefault

      public final V getOrDefault(Object key, V defaultValue)
      Specified by:
      getOrDefault in interface Map<K,V>
      Since:
      21.0 (but only since 23.5 in the Android flavor). Note, however, that Java 8 users can call this method with any version and flavor of Guava.

    • entrySet

      public ImmutableSet<Map.Entry<K,V>> entrySet()
      Returns an immutable set of the mappings in this map. The iteration order is specified by the method used to create this map. Typically, this is insertion order.
      Specified by:
      entrySet in interface Map<K,V>

    • keySet

      public ImmutableSet<K> keySet()
      Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.
      Specified by:
      keySet in interface Map<K,V>

    • values

      public ImmutableCollection<V> values()
      Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.
      Specified by:
      values in interface Map<K,V>

    • asMultimap

      public ImmutableSetMultimap<K,V> asMultimap()
      Returns a multimap view of the map.
      Since:
      14.0

    • equals

      public boolean equals(Object object)
      Specified by:
      equals in interface Map<K,V>
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Map<K,V>
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object