Module java.base
Package java.util

Interface Map<K,V>

类型参数:
K - 此映射维护的键的类型
V - 映射值的类型
所有已知的子接口:
Bindings, ConcurrentMap<K,V>, ConcurrentNavigableMap<K,V>, NavigableMap<K,V>, SequencedMap<K,V>, SortedMap<K,V>
所有已知的实现类:
AbstractMap, Attributes, AuthProvider, ConcurrentHashMap, ConcurrentSkipListMap, EnumMap, HashMap, Hashtable, Headers, IdentityHashMap, LinkedHashMap, PrinterStateReasons, Properties, Provider, RenderingHints, SimpleBindings, TabularDataSupport, TreeMap, UIDefaults, WeakHashMap
public interface Map<K,V>
将键映射到值的对象。映射不可以包含重复的键；每个键最多可以映射到一个值。

此接口取代了Dictionary类，后者是一个完全抽象的类而不是一个接口。

Map接口提供了三种集合视图，允许将映射的内容视为键的集合、值的集合或键-值映射的集合。映射的顺序被定义为迭代器在映射的集合视图上返回元素的顺序。一些映射实现（如TreeMap类）对它们的遍历顺序做出了具体保证；而另一些（如HashMap类）则没有。具有定义的遍历顺序的映射通常是SequencedMap接口的子类型。

注意：如果将可变对象用作映射键，则必须格外小心。如果更改对象的值以影响equals比较，而该对象是映射中的键，则映射的行为未指定。此禁令的一个特例是，映射不得包含自身作为键。虽然映射可以包含自身作为值，但建议极度小心：在这种映射上，equals和hashCode方法不再被明确定义。

所有通用映射实现类应提供两个“标准”构造函数：一个无参构造函数，用于创建一个空映射，以及一个带有Map类型单个参数的构造函数，用于创建一个具有与其参数相同的键-值映射的新映射。实际上，后一个构造函数允许用户复制任何映射，生成所需类的等效映射。虽然无法强制执行此建议（因为接口不能包含构造函数），但JDK中的所有通用映射实现都遵守这一点。

此接口中包含的“破坏性”方法，即修改其操作的映射的方法，如果此映射不支持操作，则指定抛出UnsupportedOperationException。如果是这种情况，这些方法可能会在对映射没有影响的情况下抛出UnsupportedOperationException，但不是必须的。例如，在不可修改的映射上调用putAll(Map)方法可能会抛出异常，但不是必须的，如果要“叠加”其映射的映射为空。

一些映射实现对它们可能包含的键和值有限制。例如，一些实现禁止空键和值，并且一些对其键的类型有限制。尝试插入不合格的键或值会引发未经检查的异常，通常是NullPointerException或ClassCastException。尝试查询不合格的键或值的存在可能会引发异常，或者可能只会返回false；一些实现将表现出前一种行为，而另一些将表现出后一种行为。更一般地，尝试对不合格的键或值执行操作，如果完成操作不会导致将不合格元素插入映射，则可能会抛出异常，也可能会成功，由实现的选择。此类异常在此接口的规范中标记为“可选”。

集合框架接口中的许多方法是根据equals方法定义的。例如，containsKey(Object key)方法的规范说：“当且仅当此映射包含一个键为k的映射，使得(key==null ? k==null : key.equals(k))”时返回true。不应将此规范解释为调用Map.containsKey时，对于非空参数key会导致为任何键k调用key.equals(k)。实现可以自由实现优化，例如，通过首先比较两个键的哈希码来避免equals调用。（Object.hashCode()规范保证具有不相等哈希码的两个对象不可能相等。）更一般地，各种集合框架接口的实现可以利用底层Object方法的指定行为，无论实现者认为适当。

一些执行对映射进行递归遍历的映射操作可能会因映射直接或间接包含自身而导致异常。这包括clone()、equals()、hashCode()和toString()方法。实现可以选择处理自引用情况，但目前大多数实现都不这样做。

不可修改的映射

Map.of、Map.ofEntries和Map.copyOf静态工厂方法提供了创建不可修改映射的便捷方式。这些方法创建的Map实例具有以下特征：

  • 它们是不可修改的。无法添加、删除或更新键和值。在映射上调用任何修改器方法将始终导致抛出UnsupportedOperationException。但是，如果包含的键或值本身是可变的，则可能导致映射行为不一致或其内容似乎发生更改。
  • 它们不允许null键和值。尝试使用null键或值创建它们将导致NullPointerException。
  • 如果所有键和值都是可序列化的，则它们是可序列化的。
  • 它们在创建时拒绝重复的键。传递给静态工厂方法的重复键将导致IllegalArgumentException。
  • 映射的映射顺序是未指定的，并且可能会更改。
  • 它们是基于值的。程序员应将相等的实例视为可互换，并且不应将它们用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能会失败。调用者不应对返回实例的标识做任何假设。工厂可以创建新实例或重用现有实例。
  • 它们按照序列化形式页面上指定的方式进行序列化。

此接口是Java集合框架的成员。

自 JDK 1.2 起:
1.2
参见:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Map.Entry<K,V>
    映射条目（键-值对）。

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    从此映射中删除所有映射（可选操作）。
    default V
    compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    尝试为指定的键及其当前映射值（如果没有当前映射则为null）计算映射。
    default V
    computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
    如果指定的键尚未与值关联（或映射到null），则尝试使用给定的映射函数计算其值，并将其输入到此映射中，除非为null。
    default V
    computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    如果指定键的值存在且非空，则尝试根据键及其当前映射值计算新映射。
    boolean
    containsKey(Object key)
    如果此映射包含指定键的映射，则返回true。
    boolean
    containsValue(Object value)
    如果此映射将一个或多个键映射到指定值，则返回true。
    static <K, V> Map<K,V>
    copyOf(Map<? extends K,? extends V> map)
    返回包含给定映射条目的不可修改的Map。
    static <K, V> Map.Entry<K,V>
    entry(K k, V v)
    返回包含给定键和值的不可修改的Map.Entry。
    Set<Map.Entry<K,V>>
    entrySet()
    返回此映射中包含的映射的Set视图。
    boolean
    equals(Object o)
    将指定对象与此映射进行比较以判断是否相等。
    default void
    forEach(BiConsumer<? super K,? super V> action)
    对此映射中的每个条目执行给定操作，直到处理完所有条目或操作引发异常。
    V
    get(Object key)
    返回指定键映射到的值，如果此映射不包含键的映射，则返回null。
    default V
    getOrDefault(Object key, V defaultValue)
    返回指定键映射到的值，如果此映射不包含键的映射，则返回defaultValue。
    int
    hashCode()
    返回此映射的哈希码值。
    boolean
    isEmpty()
    如果此映射不包含键-值映射，则返回true。
    Set<K>
    keySet()
    返回此映射中包含的键的Set视图。
    default V
    merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
    如果指定键尚未与值关联或与null关联，则将其与给定非null值关联。
    static <K, V> Map<K,V>
    of()
    返回包含零个映射的不可修改的映射。
    static <K, V> Map<K,V>
    of(K k1, V v1)
    返回包含单个映射的不可修改的映射。
    static <K, V> Map<K,V>
    of(K k1, V v1, K k2, V v2)
    返回包含两个映射的不可修改的映射。
    static <K, V> Map<K,V>
    of(K k1, V v1, K k2, V v2, K k3, V v3)
    返回包含三个映射的不可修改的映射。
    static <K, V> Map<K,V>
    of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
    返回包含四个映射的不可修改的映射。
    static <K, V> Map<K,V>
    of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
    返回包含五个映射的不可修改的映射。
    static <K, V> Map<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)
    返回包含六个映射的不可修改的映射。
    static <K, V> Map<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)
    返回包含七个映射的不可修改的映射。
    static <K, V> Map<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)
    返回包含八个映射的不可修改的映射。
    static <K, V> Map<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)
    返回包含九个映射的不可修改的映射。
    static <K, V> Map<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)
    返回包含十个映射的不可修改的映射。
    static <K, V> Map<K,V>
    ofEntries(Map.Entry<? extends K,? extends V>... entries)
    返回从给定条目中提取的键和值的不可修改的映射。
    V
    put(K key, V value)
    在此映射中将指定值与指定键关联（可选操作）。
    void
    putAll(Map<? extends K,? extends V> m)
    将指定映射中的所有映射复制到此映射（可选操作）。
    default V
    putIfAbsent(K key, V value)
    如果指定键尚未与值关联（或映射到null），则将其与给定值关联并返回null，否则返回当前值。
    V
    remove(Object key)
    如果存在，则从此映射中删除键的映射（可选操作）。
    default boolean
    remove(Object key, Object value)
    仅当指定键当前映射到指定值时，才删除指定键的条目。
    default V
    replace(K key, V value)
    仅当指定键当前映射到某个值时才替换该条目。
    default boolean
    replace(K key, V oldValue, V newValue)
    仅当指定键当前映射到指定值时才替换该条目。
    default void
    replaceAll(BiFunction<? super K,? super V,? extends V> function)
    将每个条目的值替换为在该条目上调用给定函数的结果，直到处理完所有条目或函数引发异常。
    int
    size()
    返回此映射中键-值映射的数量。
    Collection<V>
    values()
    返回此映射中包含的值的Collection视图。

  • Method Details

    • size

      int size()
      返回此映射中键-值映射的数量。如果映射包含的元素超过Integer.MAX_VALUE，则返回Integer.MAX_VALUE。
      返回:
      此映射中键-值映射的数量

    • isEmpty

      boolean isEmpty()
      如果此映射不包含键-值映射，则返回true。
      返回:
      如果此映射不包含键-值映射，则返回true

    • containsKey

      boolean containsKey(Object key)
      如果此映射包含指定键的映射，则返回true。更正式地说，仅当此映射包含将键k映射到值的映射时，才返回true，使得Objects.equals(key, k)。 （最多只能有一个这样的映射。）
      参数:
      key - 要测试其在此映射中是否存在的键
      返回:
      如果此映射包含指定键的映射，则返回true
      抛出:
      ClassCastException - 如果键对于此映射的类型不适当（可选）
      NullPointerException - 如果指定键为null且此映射不允许null键（可选）

    • containsValue

      boolean containsValue(Object value)
      如果此映射将一个或多个键映射到指定值，则返回true。更正式地说，仅当此映射包含至少一个将值v映射到的映射时，才返回true，使得Objects.equals(value, v)。 对于大多数Map接口的实现，此操作可能需要与映射大小成线性时间。
      参数:
      value - 要测试其在此映射中是否存在的值
      返回:
      如果此映射将一个或多个键映射到指定值，则返回true
      抛出:
      ClassCastException - 如果值对于此映射的类型不适当（可选）
      NullPointerException - 如果指定值为null且此映射不允许null值（可选）

    • get

      V get(Object key)
      返回指定键映射到的值，如果此映射不包含键的映射，则返回null。

      更正式地说，如果此映射包含将键k映射到值v的映射，使得Objects.equals(key, k)，则此方法返回v；否则返回null。（最多只能有一个这样的映射。）

      如果此映射允许null值，则返回null的返回值不一定表示映射不包含键的映射；也可能是映射明确将键映射到null。可以使用containsKey操作来区分这两种情况。

      参数:
      key - 要返回其关联值的键
      返回:
      指定键映射到的值，如果此映射不包含键的映射，则返回null
      抛出:
      ClassCastException - 如果键对于此映射的类型不适当（可选）
      NullPointerException - 如果指定键为null且此映射不允许null键（可选）

    • put

      V put(K key, V value)
      在此映射中将指定值与指定键关联（可选操作）。如果映射先前包含键的映射，则旧值将被指定值替换。 （如果映射m包含键k的映射，则仅当m.containsKey(k)返回true时，才说映射包含键k的映射。）
      参数:
      key - 要与指定值关联的键
      value - 要与指定键关联的值
      返回:
      与key关联的先前值，如果key没有映射，则返回null。（如果实现支持null值，则null返回还可以表示映射先前将null与key关联。）
      抛出:
      UnsupportedOperationException - 如果此映射不支持put操作
      ClassCastException - 如果指定键或值的类阻止将其存储在此映射中
      NullPointerException - 如果指定键或值为null且此映射不允许null键或值
      IllegalArgumentException - 如果指定键或值的某些属性阻止将其存储在此映射中

    • remove

      V remove(Object key)
      如果存在，则从此映射中删除键的映射（可选操作）。更正式地说，如果此映射包含将键k映射到值v的映射，使得Objects.equals(key, k)，则将删除该映射。 （映射最多只能包含一个这样的映射。）

      返回此映射先前关联的键的值，如果映射不包含键的映射，则返回null。

      如果此映射允许null值，则返回null的返回值不一定表示映射不包含键的映射；也可能是映射明确将键映射到null。

      一旦调用返回，映射将不再包含指定键的映射。

      参数:
      key - 要从映射中移除的键
      返回:
      与key关联的先前值，如果key没有映射则返回null
      抛出:
      UnsupportedOperationException - 如果此映射不支持remove操作
      ClassCastException - 如果键的类型不适合此映射（可选）
      NullPointerException - 如果指定的键为null且此映射不允许null键（可选）

    • putAll

      void putAll(Map<? extends K,? extends V> m)
      将指定映射中的所有映射复制到此映射中（可选操作）。此调用的效果等同于在指定映射中每个从键k到值v的映射上调用一次put(k, v)在此映射上。如果在操作进行时修改了指定映射，则此操作的行为是未定义的。如果指定映射具有定义的遇到顺序，则通常以该顺序处理其映射。
      参数:
      m - 要存储在此映射中的映射
      抛出:
      UnsupportedOperationException - 如果此映射不支持putAll操作
      ClassCastException - 如果指定映射中键或值的类别阻止其存储在此映射中
      NullPointerException - 如果指定映射为null，或者此映射不允许null键或值，并且指定映射包含null键或值
      IllegalArgumentException - 如果指定映射中键或值的某些属性阻止其存储在此映射中

    • clear

      void clear()
      从此映射中删除所有映射（可选操作）。此调用返回后，映射将为空。
      抛出:
      UnsupportedOperationException - 如果此映射不支持clear操作

    • keySet

      Set<K> keySet()
      返回此映射中包含的键的Set视图。该集合由映射支持，因此对映射的更改会反映在集合中，反之亦然。如果在对集合进行迭代时修改了映射（除非通过迭代器自身的remove操作），则迭代的结果是未定义的。该集合支持元素删除，通过Iterator.remove、Set.remove、removeAll、retainAll和clear操作从映射中删除相应的映射。它不支持add或addAll操作。
      返回:
      包含在此映射中的键的集合视图

    • values

      Collection<V> values()
      返回此映射中包含的值的Collection视图。该集合由映射支持，因此对映射的更改会反映在集合中，反之亦然。如果在对集合进行迭代时修改了映射（除非通过迭代器自身的remove操作），则迭代的结果是未定义的。该集合支持元素删除，通过Iterator.remove、Collection.remove、removeAll、retainAll和clear操作从映射中删除相应的映射。它不支持add或addAll操作。
      返回:
      包含在此映射中的值的集合视图

    • entrySet

      Set<Map.Entry<K,V>> entrySet()
      返回此映射中包含的映射的Set视图。该集合由映射支持，因此对映射的更改会反映在集合中，反之亦然。如果在对集合进行迭代时修改了映射（除非通过迭代器自身的remove操作，或通过迭代器返回的映射条目的setValue操作），则迭代的结果是未定义的。该集合支持元素删除，通过Iterator.remove、Set.remove、removeAll、retainAll和clear操作从映射中删除相应的映射。它不支持add或addAll操作。
      返回:
      包含在此映射中的映射的集合视图

    • equals

      boolean equals(Object o)
      将指定对象与此映射进行比较以检查是否相等。如果给定对象也是一个映射，并且两个映射表示相同的映射，则返回true。更正式地，如果两个映射m1和m2表示相同的映射，则m1.entrySet().equals(m2.entrySet())。这确保了equals方法在Map接口的不同实现之间正常工作。
      覆盖:
      equals 在类 Object
      参数:
      o - 用于与此映射比较相等的对象
      返回:
      如果指定对象等于此映射，则返回true
      参见:

    • hashCode

      int hashCode()
      返回此映射的哈希码值。映射的哈希码定义为映射的entrySet()视图中每个条目的哈希码之和。这确保了对于任何两个映射m1和m2，如果m1.equals(m2)，则m1.hashCode()==m2.hashCode()，这是Object.hashCode()的一般契约要求。
      覆盖:
      hashCode 在类 Object
      返回:
      此映射的哈希码值
      参见:

    • getOrDefault

      default V getOrDefault(Object key, V defaultValue)
      返回指定键映射到的值，如果此映射不包含键的映射，则返回defaultValue。
      实现要求:
      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。
      参数:
      key - 要返回其关联值的键
      defaultValue - 键的默认映射
      返回:
      如果此映射不包含键的映射，则返回指定键映射到的值，否则返回defaultValue
      抛出:
      ClassCastException - 如果键的类型不适合此映射（可选)
      NullPointerException - 如果指定键为null且此映射不允许null键（可选)
      自1.8起:
      1.8

    • forEach

      default void forEach(BiConsumer<? super K,? super V> action)
      对此映射中的每个条目执行给定操作，直到所有条目都已处理或操作引发异常。除非实现类另有规定，否则按照条目集合迭代的顺序执行操作（如果指定了迭代顺序）。操作引发的异常将传递给调用者。
      实现要求:
      默认实现等效于对于此map： 
       
 for (Map.Entry<K, V> entry : map.entrySet())
     action.accept(entry.getKey(), entry.getValue());
      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。
      参数:
      action - 要对每个条目执行的操作
      抛出:
      NullPointerException - 如果指定操作为null
      ConcurrentModificationException - 如果在迭代过程中发现要删除的条目
      自1.8起:
      1.8

    • replaceAll

      default void replaceAll(BiFunction<? super K,? super V,? extends V> function)
      替换每个条目的值为在该条目上调用给定函数的结果，直到所有条目都已处理或函数引发异常。函数引发的异常将传递给调用者。
      Implementation Requirements:

      The default implementation is equivalent to, for this map:

       
 for (Map.Entry<K, V> entry : map.entrySet())
     entry.setValue(function.apply(entry.getKey(), entry.getValue()));

      The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.

      Parameters:
      function - the function to apply to each entry
      Throws:
      UnsupportedOperationException - if the set operation is not supported by this map's entry set iterator.
      ClassCastException - if the class of a replacement value prevents it from being stored in this map (optional)
      NullPointerException - if the specified function is null, or if a replacement value is null and this map does not permit null values (optional)
      IllegalArgumentException - if some property of a replacement value prevents it from being stored in this map (optional)
      ConcurrentModificationException - if an entry is found to be removed during iteration
      Since:
      1.8

    • putIfAbsent

      default V putIfAbsent(K key, V value)
      If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.
      Implementation Requirements:
      The default implementation is equivalent to, for this map: 
       
 V v = map.get(key);
 if (v == null)
     v = map.put(key, value);

 return v;

      The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.

      Parameters:
      key - key with which the specified value is to be associated
      value - value to be associated with the specified key
      Returns:
      the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map (optional)
      ClassCastException - if the key or value is of an inappropriate type for this map (optional)
      NullPointerException - if the specified key or value is null, and this map does not permit null keys or values (optional)
      IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map (optional)
      Since:
      1.8

    • remove

      default boolean remove(Object key, Object value)
      Removes the entry for the specified key only if it is currently mapped to the specified value.
      Implementation Requirements:
      The default implementation is equivalent to, for this map: 
       
 if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
     map.remove(key);
     return true;
 } else
     return false;

      The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.

      Parameters:
      key - key with which the specified value is associated
      value - value expected to be associated with the specified key
      Returns:
      true if the value was removed
      Throws:
      UnsupportedOperationException - if the remove operation is not supported by this map (optional)
      ClassCastException - if the key or value is of an inappropriate type for this map (optional)
      NullPointerException - if the specified key or value is null, and this map does not permit null keys or values (optional)
      Since:
      1.8

    • replace

      default boolean replace(K key, V oldValue, V newValue)
      Replaces the entry for the specified key only if currently mapped to the specified value.
      Implementation Requirements:
      The default implementation is equivalent to, for this map: 
       
 if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
     map.put(key, newValue);
     return true;
 } else
     return false;
      The default implementation does not throw NullPointerException for maps that do not support null values if oldValue is null unless newValue is also null.

      The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.

      Parameters:
      key - key with which the specified value is associated
      oldValue - value expected to be associated with the specified key
      newValue - value to be associated with the specified key
      Returns:
      true if the value was replaced
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map (optional)
      ClassCastException - if the class of a specified key or value prevents it from being stored in this map
      NullPointerException - if a specified key or newValue is null, and this map does not permit null keys or values
      NullPointerException - if oldValue is null and this map does not permit null values (optional)
      IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this map
      Since:
      1.8

    • replace

      default V replace(K key, V value)
      Replaces the entry for the specified key only if it is currently mapped to some value.
      Implementation Requirements:
      The default implementation is equivalent to, for this map: 
       
 if (map.containsKey(key)) {
     return map.put(key, value);
 } else
     return null;

      The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.

      Parameters:
      key - key with which the specified value is associated
      value - value to be associated with the specified key
      Returns:
      the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map (optional)
      ClassCastException - if the class of the specified key or value prevents it from being stored in this map (optional)
      NullPointerException - if the specified key or value is null, and this map does not permit null keys or values
      IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map
      Since:
      1.8

    • computeIfAbsent

      default V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
      If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null.

      If the mapping function returns null, no mapping is recorded. If the mapping function itself throws an (unchecked) exception, the exception is rethrown, and no mapping is recorded. The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in:

       
 map.computeIfAbsent(key, k -> new Value(f(k)));

      Or to implement a multi-value map, Map<K,Collection<V>>, supporting multiple values per key:

       
 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);

      The mapping function should not modify this map during computation.

      实现要求:
      默认实现等同于为此map执行以下步骤，然后返回当前值或null（如果不存在）： 
       
 if (map.get(key) == null) {
     V newValue = mappingFunction.apply(key);
     if (newValue != null)
         map.put(key, newValue);
 }

      默认实现不保证检测映射函数在计算过程中是否修改了此映射，并在适当情况下报告错误。非并发实现应该覆盖此方法，并在尽力的基础上，如果检测到映射函数在计算过程中修改了此映射，则抛出ConcurrentModificationException。并发实现应该覆盖此方法，并在尽力的基础上，如果检测到映射函数在计算过程中修改了此映射，并且因此计算永远不会完成，则抛出IllegalStateException。

      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。特别是，所有子接口ConcurrentMap的实现必须记录是否仅在值不存在时一次原子地应用映射函数。

      参数:
      key - 要关联指定值的键
      mappingFunction - 用于计算值的映射函数
      返回:
      与指定键关联的当前（现有或计算的）值，如果计算的值为null，则返回null
      抛出:
      NullPointerException - 如果指定的键为null且此映射不支持null键，或映射函数为null
      UnsupportedOperationException - 如果此映射不支持put操作（可选）
      ClassCastException - 如果指定键或值的类别阻止将其存储在此映射中（可选）
      IllegalArgumentException - 如果指定键或值的某些属性阻止将其存储在此映射中（可选）
      自:
      1.8

    • computeIfPresent

      default V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      如果指定键的值存在且非null，则尝试根据键及其当前映射值计算新映射。

      如果重新映射函数返回null，则移除映射。如果重新映射函数本身抛出（未检查的）异常，则重新抛出该异常，并且当前映射保持不变。

      重新映射函数在计算过程中不应修改此映射。

      实现要求:
      默认实现等同于为此map执行以下步骤，然后返回当前值或null（如果不存在）： 
       
 if (map.get(key) != null) {
     V oldValue = map.get(key);
     V newValue = remappingFunction.apply(key, oldValue);
     if (newValue != null)
         map.put(key, newValue);
     else
         map.remove(key);
 }

      默认实现不保证检测重新映射函数在计算过程中是否修改了此映射，并在适当情况下报告错误。非并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，则抛出ConcurrentModificationException。并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，并且因此计算永远不会完成，则抛出IllegalStateException。

      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。特别是，所有子接口ConcurrentMap的实现必须记录是否仅在值不存在时一次原子地应用重新映射函数。

      参数:
      key - 要关联指定值的键
      remappingFunction - 用于计算值的重新映射函数
      返回:
      与指定键关联的新值，如果没有则返回null
      抛出:
      NullPointerException - 如果指定的键为null且此映射不支持null键，或重新映射函数为null
      UnsupportedOperationException - 如果此映射不支持put操作（可选）
      ClassCastException - 如果指定键或值的类别阻止将其存储在此映射中（可选）
      IllegalArgumentException - 如果指定键或值的某些属性阻止将其存储在此映射中（可选）
      自:
      1.8

    • compute

      default V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      尝试为指定键及其当前映射值（或null，如果没有当前映射）计算映射。例如，要创建或追加String msg到值映射： 
       
 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))
      （对于此类目的，通常更简单的方法是使用merge()方法。）

      如果重新映射函数返回null，则移除映射（如果最初不存在，则保持不变）。如果重新映射函数本身抛出（未检查的）异常，则重新抛出该异常，并且当前映射保持不变。

      重新映射函数在计算过程中不应修改此映射。

      实现要求:
      默认实现等同于为此map执行以下步骤： 
       
 V oldValue = map.get(key);
 V newValue = remappingFunction.apply(key, oldValue);
 if (newValue != null) {
     map.put(key, newValue);
 } else if (oldValue != null || map.containsKey(key)) {
     map.remove(key);
 }
 return newValue;

      默认实现不保证检测重新映射函数在计算过程中是否修改了此映射，并在适当情况下报告错误。非并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，则抛出ConcurrentModificationException。并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，并且因此计算永远不会完成，则抛出IllegalStateException。

      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。特别是，所有子接口ConcurrentMap的实现必须记录是否仅在值不存在时一次原子地应用重新映射函数。

      参数:
      key - 要关联指定值的键
      remappingFunction - 用于计算值的重新映射函数
      返回:
      与指定键关联的新值，如果没有则返回null
      抛出:
      NullPointerException - 如果指定的键为null且此映射不支持null键，或重新映射函数为null
      UnsupportedOperationException - 如果此映射不支持put操作（可选）
      ClassCastException - 如果指定键或值的类别阻止将其存储在此映射中（可选）
      IllegalArgumentException - 如果指定键或值的某些属性阻止将其存储在此映射中（可选）
      自:
      1.8

    • merge

      default V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
      如果指定键尚未与值关联或与null关联，则将其与给定的非null值关联。否则，将关联值替换为给定重新映射函数的结果，如果结果为null，则移除。当组合多个键映射值时，此方法可能有用。例如，要创建或追加String msg到值映射： 
       
 map.merge(key, msg, String::concat)

      如果重新映射函数返回null，则移除映射。如果重新映射函数本身抛出（未检查的）异常，则重新抛出该异常，并且当前映射保持不变。

      重新映射函数在计算过程中不应修改此映射。

      实现要求:
      默认实现等同于为此map执行以下步骤，然后返回当前值或null（如果不存在）： 
       
 V oldValue = map.get(key);
 V newValue = (oldValue == null) ? value :
              remappingFunction.apply(oldValue, value);
 if (newValue == null)
     map.remove(key);
 else
     map.put(key, newValue);

      默认实现不保证检测重新映射函数在计算过程中是否修改了此映射，并在适当情况下报告错误。非并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，则抛出ConcurrentModificationException。并发实现应该覆盖此方法，并在尽力的基础上，如果检测到重新映射函数在计算过程中修改了此映射，并且结果计算永远不会完成，则抛出IllegalStateException。

      默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现必须覆盖此方法并记录其并发属性。特别是，所有子接口ConcurrentMap的所有实现必须记录重新映射函数是否仅在值不存在时被原子地应用一次。

      参数:
      key - 要关联新值的键
      value - 与键关联的现有值合并的非空值，或者如果键关联的现有值为null或null值，则与键关联
      remappingFunction - 重新计算值的重新映射函数（如果存在）
      返回:
      与指定键关联的新值，如果键未关联任何值，则返回null
      抛出:
      UnsupportedOperationException - 如果此映射不支持put操作（可选）
      ClassCastException - 如果指定键或值的类别阻止其存储在此映射中（可选）
      IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（可选）
      NullPointerException - 如果指定键为null且此映射不支持null键，或者值或remappingFunction为null
      自:
      1.8

    • of

      static <K, V> Map<K,V> of()
      返回一个包含零个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      返回:
      一个空的Map
      自:
      9

    • of

      static <K, V> Map<K,V> of(K k1, V v1)
      返回一个包含单个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 映射的键
      v1 - 映射的值
      返回:
      包含指定映射的Map
      抛出:
      NullPointerException - 如果键或值为null
      自:
      9

    • of

      static <K, V> Map<K,V> of(K k1, V v1, K k2, V v2)
      返回一个包含两个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果键重复
      NullPointerException - 如果任何键或值为null
      自:
      9

    • of

      static <K, V> Map<K,V> of(K k1, V v1, K k2, V v2, K k3, V v3)
      返回一个包含三个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复键
      NullPointerException - 如果任何键或值为null
      自:
      9

    • of

      static <K, V> Map<K,V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
      返回一个包含四个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复键
      NullPointerException - 如果任何键或值为null
      自:
      9

    • of

      static <K, V> Map<K,V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
      返回一个包含五个映射的不可修改的映射。有关详细信息，请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复键
      NullPointerException - 如果任何键或值为null
      自:
      9

    • of

      static <K, V> Map<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 - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      k6 - 第六个映射的键
      v6 - 第六个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复键
      NullPointerException - 如果任何键或值为null
      自:
      9

    • of

      static <K, V> Map<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 - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      k6 - 第六个映射的键
      v6 - 第六个映射的值
      k7 - 第七个映射的键
      v7 - 第七个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复的键
      NullPointerException - 如果任何键或值为null
      自版本:
      9

    • of

      static <K, V> Map<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 - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      k6 - 第六个映射的键
      v6 - 第六个映射的值
      k7 - 第七个映射的键
      v7 - 第七个映射的值
      k8 - 第八个映射的键
      v8 - 第八个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复的键
      NullPointerException - 如果任何键或值为null
      自版本:
      9

    • of

      static <K, V> Map<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 - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      k6 - 第六个映射的键
      v6 - 第六个映射的值
      k7 - 第七个映射的键
      v7 - 第七个映射的值
      k8 - 第八个映射的键
      v8 - 第八个映射的值
      k9 - 第九个映射的键
      v9 - 第九个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复的键
      NullPointerException - 如果任何键或值为null
      自版本:
      9

    • of

      static <K, V> Map<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)
      返回一个包含十个映射的不可修改的映射。详情请参见不可修改的映射。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      k1 - 第一个映射的键
      v1 - 第一个映射的值
      k2 - 第二个映射的键
      v2 - 第二个映射的值
      k3 - 第三个映射的键
      v3 - 第三个映射的值
      k4 - 第四个映射的键
      v4 - 第四个映射的值
      k5 - 第五个映射的键
      v5 - 第五个映射的值
      k6 - 第六个映射的键
      v6 - 第六个映射的值
      k7 - 第七个映射的键
      v7 - 第七个映射的值
      k8 - 第八个映射的键
      v8 - 第八个映射的值
      k9 - 第九个映射的键
      v9 - 第九个映射的值
      k10 - 第十个映射的键
      v10 - 第十个映射的值
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复的键
      NullPointerException - 如果任何键或值为null
      自版本:
      9

    • ofEntries

      @SafeVarargs static <K, V> Map<K,V> ofEntries(Map.Entry<? extends K,? extends V>... entries)
      返回一个包含从给定条目中提取的键和值的不可修改的映射。这些条目本身不存储在映射中。详情请参见不可修改的映射。
      API注释:
      使用Map.entry()方法创建映射条目很方便。例如， 
      
     import static java.util.Map.entry;

     Map<Integer,String> map = Map.ofEntries(
         entry(1, "a"),
         entry(2, "b"),
         entry(3, "c"),
         ...
         entry(26, "z"));
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      entries - 包含用于填充映射的键和值的Map.Entry
      返回:
      包含指定映射的Map
      抛出:
      IllegalArgumentException - 如果存在任何重复的键
      NullPointerException - 如果任何条目、键或值为null，或者entries数组为null
      自版本:
      9
      参见:

    • entry

      static <K, V> Map.Entry<K,V> entry(K k, V v)
      返回一个包含给定键和值的不可修改的Map.Entry。这些条目适合使用Map.ofEntries()方法填充Map实例。此方法创建的Entry实例具有以下特征：
      • 它们不允许null键和值。尝试使用null键或值创建它们会导致NullPointerException。
      • 它们是不可修改的。对返回的Entry调用Entry.setValue()会导致UnsupportedOperationException。
      • 它们不可序列化。
      • 它们是基于值的。程序员应将相等的实例视为可互换的，不应将它们用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能失败。调用者不应对返回实例的标识做任何假设。此方法可以自由创建新实例或重用现有实例。
      API注释:
      对于可序列化的Entry，请参见AbstractMap.SimpleEntry或AbstractMap.SimpleImmutableEntry。
      类型参数:
      K - 键的类型
      V - 值的类型
      参数:
      k - 键
      v - 值
      返回:
      包含指定键和值的Entry
      抛出:
      NullPointerException - 如果键或值为null
      自版本:
      9
      参见:

    • copyOf

      static <K, V> Map<K,V> copyOf(Map<? extends K,? extends V> map)
      返回一个包含给定映射条目的不可修改的Map
      实现注意事项:
      如果给定的Map是一个不可修改的Map，调用copyOf通常不会创建副本。
      类型参数:
      K - Map的键类型
      V - Map的值类型
      参数:
      map - 从中提取条目的Map，必须非空
      返回值:
      包含给定Map的条目的Map
      抛出:
      NullPointerException - 如果map为null，或者它包含任何null键或值
      自版本:
      10