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

@DoNotMock("Use ImmutableMap.of or another implementation") @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
Author:
Jesse Wilson, Kevin Bourrillion
See Also:
  • Method Details

    • toImmutableMap

      public static <T extends @Nullable Object, 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:
      33.2.0 (available since 21.0 in guava-jre)
    • toImmutableMap

      public static <T extends @Nullable Object, 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. If the merging function returns null, then the collector removes the value that has been computed for the key thus far (though future occurrences of the key would reinsert it).

      Entries will appear in the encounter order of the first occurrence of the key.

      Since:
      33.2.0 (available since 21.0 in guava-jre)
    • 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

      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(boolean) 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

      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.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      put in interface Map<K,V>
      Throws:
      UnsupportedOperationException - always
    • remove

      Deprecated.
      Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
      remove 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
    • 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(@Nullable Object key)
      Specified by:
      containsKey in interface Map<K,V>
    • containsValue

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

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

      public final @Nullable V getOrDefault(@Nullable Object key, @Nullable V defaultValue)
      Specified by:
      getOrDefault in interface Map<K,V>
      Since:
      23.5 (but since 21.0 in the JRE flavor). Note, however, that Java 8+ users can call this method with any version and flavor of Guava.
    • 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

      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

      Returns a multimap view of the map.
      Since:
      14.0
    • equals

      public boolean equals(@Nullable 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