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, ImmutableMap.IteratorBasedImmutableMap, ImmutableSortedMap, JdkBackedImmutableMap, RegularImmutableMap

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:
  • Field Details

  • Constructor Details

    • ImmutableMap

      ImmutableMap()
  • 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. 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:
      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
    • entryOf

      static <K, V> Map.Entry<K,V> entryOf(K key, V value)
      Verifies that key and value are non-null, and returns a new immutable entry with those values.

      A call to Map.Entry.setValue(V) on the returned entry will always throw UnsupportedOperationException.

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

      static void checkNoConflict(boolean safe, String conflictDescription, Object entry1, Object entry2)
    • conflictException

      static IllegalArgumentException conflictException(String conflictDescription, Object entry1, Object entry2)
    • 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
    • copyOfEnumMap

      private static <K extends Enum<K>, V> ImmutableMap<K,? extends V> copyOfEnumMap(EnumMap<?,? extends V> original)
    • put

      @Deprecated @CheckForNull 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 @CheckForNull 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 @CheckForNull 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 @CheckForNull 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 @CheckForNull 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 @CheckForNull public final V merge(K key, V value, BiFunction<? super V,? super V,? extends V> function)
      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 @CheckForNull public final V remove(@CheckForNull 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(@CheckForNull Object key, @CheckForNull 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(@CheckForNull Object key)
      Specified by:
      containsKey in interface Map<K,V>
    • containsValue

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

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

      @CheckForNull public final V getOrDefault(@CheckForNull Object key, @CheckForNull 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>
    • createEntrySet

      abstract ImmutableSet<Map.Entry<K,V>> createEntrySet()
    • 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>
    • createKeySet

      abstract ImmutableSet<K> createKeySet()
    • keyIterator

      UnmodifiableIterator<K> keyIterator()
    • keySpliterator

      Spliterator<K> keySpliterator()
    • 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>
    • createValues

      abstract ImmutableCollection<V> createValues()
    • asMultimap

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

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

      abstract boolean isPartialView()
    • hashCode

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

      boolean isHashCodeFast()
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • writeReplace

      Object writeReplace()
      Returns a serializable form of this object. Non-public subclasses should not override this method. Publicly-accessible subclasses must override this method and should return a subclass of SerializedForm whose readResolve() method returns objects of the subclass type.
    • readObject

      private void readObject(ObjectInputStream stream) throws InvalidObjectException
      Throws:
      InvalidObjectException