模块 java.base

包 java.util

接口 Map<K,V>

类型参数：

K - 此map维护的键类型

V - 映射值的类型

所有已知的子接口：

Bindings , ConcurrentMap<K,V> , ConcurrentNavigableMap<K,V> , NavigableMap<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>
      

将键映射到值的对象。map不能包含重复的键；每个键最多可以映射到一个值。

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

Map接口提供了三个集合视图，它允许将映射的内容视为一组键、值集合或一组键值映射。这-map的顺序定义为map集合视图上的迭代器返回其元素的顺序。一些map实现，比如TreeMap类，对它们的顺序做出了特定的保证；其他map实现，如 HashMap 类，则不不能保证。

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

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

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

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

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

一些执行map递归遍历的map操作可能会失败，但对于map直接或间接包含自身的自引用实例除外。这包括 clone()、equals()、hashCode() 和 toString() 方法。实现可以选择处理自引用场景，但是大多数当前实现不这样做。

不可修改的map

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

• 他们是不可修改的。不能添加、删除或更新键和值。在 Map 上调用任何 mutator 方法将始终导致抛出 UnsupportedOperationException。但是，如果包含的键或值本身是可变的，这可能会导致 Map 行为不一致或其内容看起来发生了变化。
• 他们不允许null键和值。尝试使用 null 键或值创建它们会导致 NullPointerException 。
• 如果所有键和值都是可序列化的，则它们是可序列化的。
• 他们在创建时拒绝重复的密钥。传递给静态工厂方法的重复键导致 IllegalArgumentException 。
• 映射的迭代顺序未指定，可能会发生变化。
• 他们是 value-based 。程序员应该将 equal 实例视为可互换的，不应将它们用于同步，否则可能会发生不可预测的行为。例如，在未来的版本中，同步可能会失败。调用者不应假设返回实例的身份。工厂可以自由创建新实例或重用现有实例。
• 它们按照 Serialized Form 页面上的指定进行序列化。

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

自从：

1.2

参见：

• HashMap
• TreeMap
• Hashtable
• SortedMap
• Collection
• Set

内部类总结

内部类

修饰符和类型	接口	描述
static interface	Map.Entry<K,V>	映射条目（键值对）。

方法总结

修饰符和类型	方法	描述
void	clear()	从此map中删除所有映射（可选操作）。
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 ），则尝试使用给定的映射函数计算其值并将其输入此map，除非 null 。
default V	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	如果指定键的值存在且非空，则尝试在给定键及其当前映射值的情况下计算新映射。
boolean	containsKey(Object key)	如果此map包含指定键的映射，则返回 true。
boolean	containsValue(Object value)	如果此map将一个或多个键映射到指定值，则返回 true。
static <K, V> Map<K,V>	copyOf(Map<? extends K,? extends V> map)	返回包含给定 Map 条目的 不可修改的map。
static <K, V> Map.Entry<K,V>	entry(K k, V v)	返回包含给定键和值的不可修改的 Map.Entry 。
Set<Map.Entry<K,V>>	entrySet()	返回此map中包含的映射的 Set 视图。
boolean	equals(Object o)	比较指定对象与此map是否相等。
default void	forEach(BiConsumer<? super K,? super V> action)	对此map中的每个条目执行给定的操作，直到处理完所有条目或操作引发异常。
V	get(Object key)	返回指定键映射到的值，如果此map不包含键的映射，则返回 null。
default V	getOrDefault(Object key, V defaultValue)	返回指定键映射到的值，如果此map不包含键的映射，则返回 defaultValue。
int	hashCode()	返回此map的哈希码值。
boolean	isEmpty()	如果此map不包含键值映射，则返回 true。
Set<K>	keySet()	返回此map中包含的键的 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()	返回包含零映射的不可修改的map。
static <K, V> Map<K,V>	of(K k1, V v1)	返回包含单个映射的不可修改的map。
static <K, V> Map<K,V>	of(K k1, V v1, K k2, V v2)	返回包含两个映射的不可修改的map。
static <K, V> Map<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3)	返回包含三个映射的不可修改的map。
static <K, V> Map<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)	返回包含四个映射的不可修改的map。
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)	返回包含五个映射的不可修改的map。
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)	返回包含六个映射的不可修改的map。
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)	返回包含七个映射的不可修改的map。
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)	返回包含八个映射的不可修改的map。
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)	返回包含九个映射的不可修改的map。
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)	返回包含十个映射的不可修改的map。
static <K, V> Map<K,V>	ofEntries(Map.Entry<? extends K,? extends V>... entries)	返回一个不可修改的map，其中包含从给定条目中提取的键和值。
V	put(K key, V value)	将指定值与此map中的指定键相关联（可选操作）。
void	putAll(Map<? extends K,? extends V> m)	将指定map中的所有值复制到此map（可选操作）。
default V	putIfAbsent(K key, V value)	如果指定的键尚未与值关联（或映射到 null ），则将其与给定值关联并返回 null ，否则返回当前值。
V	remove(Object key)	如果存在，则从此map中删除键的映射（可选操作）。
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()	返回此map中键值映射的数量。
Collection<V>	values()	返回此map中包含的值的 Collection 视图。

方法详情

size

int size()
            

返回此map中键值映射的数量。如果map包含超过 Integer.MAX_VALUE 个元素，则返回 Integer.MAX_VALUE 。

返回：

此map中键值映射的数量

isEmpty

boolean isEmpty()
            

如果此map不包含键值映射，则返回 true。

返回：

true 如果此map不包含键值映射

containsKey

boolean containsKey(Object  key)
            

如果此map包含指定键的映射，则返回 true。更正式地说，返回 true 当且仅当此map包含键 k 的映射使得 Objects.equals(key, k) 。 （最多可以有一个这样的映射。）

参数：

key - 要测试其在此map中是否存在的键

返回：

true 如果此map包含指定键的映射

抛出：

ClassCastException - 如果键的类型不适合此map (optional)

NullPointerException - 如果指定的键为空且此map不允许空键 (optional)

containsValue

boolean containsValue(Object  value)
            

如果此map将一个或多个键映射到指定值，则返回 true。更正式地说，返回 true 当且仅当此map包含至少一个映射到值 v 使得 Objects.equals(value, v) 。对于 Map 接口的大多数实现，此操作可能需要与映射大小成线性关系的时间。

参数：

value - 要测试其在此map中是否存在的值

返回：

true 如果此map将一个或多个键映射到指定值

抛出：

ClassCastException - 如果该值的类型不适合此map (optional)

NullPointerException - 如果指定值为空且此map不允许空值 (optional)

get

V  get(Object  key)
            

返回指定键映射到的值，如果此map不包含键的映射，则返回 null。

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

如果此map允许空值，则 null 的返回值不允许一定指示映射不包含键的映射；map也可能将密钥显式映射到 null 。 containsKey 操作可用于区分这两种情况。

参数：

key - 要返回其关联值的键

返回：

指定键映射到的值，如果此map不包含键的映射，则返回 null

抛出：

ClassCastException - 如果键的类型不适合此map (optional)

NullPointerException - 如果指定的键为空且此map不允许空键 (optional)

put

V  put(K  key, V  value)
            

将指定值与此map中的指定键相关联（可选操作）。如果map先前包含键的映射，则旧值将替换为指定值。 （据说映射 m 包含键 k 的映射当且仅当 m.containsKey(k) 将返回 true 。）

参数：

key - 与指定值关联的键

value - 与指定键关联的值

返回：

与 key 关联的先前值，如果没有 key 的映射，则为 null 。 （如果实现支持 null 值，则 null 返回还可以指示之前将 null 与 key 相关联的映射。）

抛出：

UnsupportedOperationException - 如果此map不支持 put 操作

ClassCastException - 如果指定键或值的类阻止它存储在此map中

NullPointerException - 如果指定的键或值是 null 并且此map不允许 null 键或值

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中

remove

V  remove(Object  key)
            

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

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

如果此map允许空值，则 null 的返回值不允许一定指示映射不包含键的映射；map也可能将密钥显式映射到 null 。

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

参数：

key - 要从map中删除其映射的键

返回：

与 key 关联的先前值，如果没有 key 的映射，则为 null 。

抛出：

UnsupportedOperationException - 如果此map不支持 remove 操作

ClassCastException - 如果键的类型不适合此map (optional)

NullPointerException - 如果指定的键为空且此map不允许空键 (optional)

putAll

void putAll(Map <? extends K ,? extends V > m)
            

将指定map中的所有映射复制到此map（可选操作）。此调用的效果等同于针对指定map中从键 k 到值 v 的每个映射在该map上调用一次 put(k, v) 。如果指定的map在操作过程中被修改，则此操作的行为是未定义的。

参数：

m - 要存储在此map中的映射

抛出：

UnsupportedOperationException - 如果此map不支持 putAll 操作

ClassCastException - 如果指定map中的键或值的类阻止将其存储在此map中

NullPointerException - 如果指定的map为空，或者如果此map不允许空键或值，并且指定的map包含空键或值

IllegalArgumentException - 如果指定map中键或值的某些属性阻止它存储在此map中

clear

void clear()
            

从此map中删除所有映射（可选操作）。此调用返回后map将为空。

抛出：

UnsupportedOperationException - 如果此map不支持 clear 操作

keySet

Set <K > keySet()
            

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

返回：

此map中包含的键的集合视图

values

Collection <V > values()
            

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

返回：

此map中包含的值的集合视图

entrySet

Set <Map.Entry <K ,V >> entrySet()
            

返回此map中包含的映射的 Set 视图。该集合由map支持，因此对map的更改会反映在集合中，反之亦然。如果在对集合进行迭代时映射被修改（除了通过迭代器自己的 remove 操作，或通过迭代器返回的映射条目上的 setValue 操作），迭代的结果是未定义的。该集合支持元素移除，即通过 Iterator.remove 、 Set.remove 、 removeAll 、 retainAll 和 clear 操作从map中移除相应的映射。它不支持 add 或 addAll 操作。

返回：

此map中包含的映射的集合视图

equals

boolean equals(Object  o)
            

比较指定对象与此map是否相等。如果给定对象也是一个映射并且两个映射表示相同的映射，则返回 true。更正式地说，两个映射 m1 和 m2 表示相同的映射，如果 m1.entrySet().equals(m2.entrySet()) 。这可确保 equals 方法在 Map 接口的不同实现中正常工作。

重写：

equals 在类 Object 中

参数：

o - 要与此map进行相等比较的对象

返回：

true 如果指定的对象等于这个map

参见：

• Object.hashCode()
• HashMap

hashCode

int hashCode()
            

返回此map的哈希码值。映射的哈希码定义为映射的entrySet()视图中每个条目的哈希码之和。这确保 m1.equals(m2) 暗示 m1.hashCode()==m2.hashCode() 对于任何两个映射 m1 和 m2，正如 Object.hashCode() 的总合同所要求的那样。

重写：

hashCode 在类 Object 中

返回：

此map的哈希码值

参见：

• Map.Entry.hashCode()
• Object.equals(Object)
• equals(Object)

getOrDefault

default V  getOrDefault(Object  key, V  defaultValue)
            

返回指定键映射到的值，如果此map不包含键的映射，则返回 defaultValue。

实现要求：

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

key - 要返回其关联值的键

defaultValue - 键的默认映射

返回：

指定键映射到的值，或者 defaultValue 如果此map不包含键的映射

抛出：

ClassCastException - 如果键的类型不适合此map (optional)

NullPointerException - 如果指定的键为空且此map不允许空键 (optional)

自从：

1.8

forEach

default void forEach(BiConsumer <? super K ,? super V > action)
            

对此map中的每个条目执行给定的操作，直到处理完所有条目或操作引发异常。除非实现类另有指定，否则操作将按照条目集迭代的顺序执行（如果指定了迭代顺序）。操作抛出的异常将传递给调用者。

实现要求：

对于此 map，默认实现等效于：

 
 for (Map.Entry<K, V> entry : map.entrySet())
   action.accept(entry.getKey(), entry.getValue());
  

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须覆盖此方法并记录其并发属性。

参数：

action - 每个条目要执行的操作

抛出：

NullPointerException - 如果指定的操作为空

ConcurrentModificationException - 如果在迭代过程中发现条目被删除

自从：

1.8

replaceAll

default void replaceAll(BiFunction <? super K ,? super V ,? extends V > function)
            

将每个条目的值替换为对该条目调用给定函数的结果，直到处理完所有条目或函数抛出异常。函数抛出的异常被转发给调用者。

实现要求：

对于这个 map，默认实现等效于：

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

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

function - 应用于每个条目的函数

抛出：

UnsupportedOperationException - 如果此map的条目集迭代器不支持 set 操作。

ClassCastException - 如果替换值的类阻止它存储在此map中 (optional)

NullPointerException - 如果指定的函数为空，或者替换值为空并且此map不允许空值 (optional)

IllegalArgumentException - 如果替换值的某些属性阻止它存储在此map中 (optional)

ConcurrentModificationException - 如果在迭代过程中发现条目被删除

自从：

1.8

putIfAbsent

default V  putIfAbsent(K  key, V  value)
            

如果指定的键尚未与值关联（或映射到 null ），则将其与给定值关联并返回 null ，否则返回当前值。

实现要求：

对于这个 map，默认实现等效于：

 
 V v = map.get(key);
 if (v == null)
   v = map.put(key, value);

 return v;
  

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

key - 与指定值关联的键

value - 与指定键关联的值

返回：

与指定键关联的先前值，或者 null 如果键没有映射。 （如果实现支持空值，则 null 返回还可以指示之前将 null 与键相关联的映射。）

抛出：

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果键或值的类型不适合此map (optional)

NullPointerException - 如果指定的键或值为空，并且此map不允许空键或值 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中 (optional)

自从：

1.8

remove

default boolean remove(Object  key, Object  value)
            

仅当指定键当前映射到指定值时才删除该条目。

实现要求：

对于这个 map，默认实现等效于：

 
 if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
   map.remove(key);
   return true;
 } else
   return false;
  

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

key - 与指定值关联的键

value - 预期与指定键关联的值

返回：

true 如果值被删除

抛出：

UnsupportedOperationException - 如果此map不支持 remove 操作 (optional )

ClassCastException - 如果键或值的类型不适合此map (optional)

NullPointerException - 如果指定的键或值为空，并且此map不允许空键或值 (optional)

自从：

1.8

replace

default boolean replace(K  key, V  oldValue, V  newValue)
            

仅当当前映射到指定值时才替换指定键的条目。

实现要求：

对于此 map，默认实现等效于：

 
 if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
   map.put(key, newValue);
   return true;
 } else
   return false;
  

如果 oldValue 为 null，则默认实现不会为不支持 null 值的映射抛出 NullPointerException，除非 newValue 也为 null。

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

key - 与指定值关联的键

oldValue - 预期与指定键关联的值

newValue - 与指定键关联的值

返回：

true 如果值被替换

抛出：

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中

NullPointerException - 如果指定键或 newValue 为 null，并且此map不允许 null 键或值

NullPointerException - 如果 oldValue 为空且此map不允许空值 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中

自从：

1.8

replace

default V  replace(K  key, V  value)
            

仅在当前映射到某个值时才替换指定键的条目。

实现要求：

对于这个 map，默认实现等效于：

 
 if (map.containsKey(key)) {
   return map.put(key, value);
 } else
   return null;
  

默认实现不保证此方法的同步或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发属性。

参数：

key - 与指定值关联的键

value - 与指定键关联的值

返回：

与指定键关联的先前值，或者 null 如果键没有映射。 （如果实现支持空值，则 null 返回还可以指示之前将 null 与键相关联的映射。）

抛出：

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中 (optional)

NullPointerException - 如果指定的键或值为空，并且此map不允许空键或值

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中

自从：

1.8

computeIfAbsent

default V  computeIfAbsent(K  key, Function <? super K ,? extends V > mappingFunction)
            

如果指定的键尚未与值关联（或映射到 null ），则尝试使用给定的映射函数计算其值并将其输入此map，除非 null 。

如果map函数返回 null ，则不记录任何映射。如果map函数本身抛出（未经检查的）异常，则重新抛出异常，并且不记录任何映射。最常见的用法是构造一个新对象作为初始映射值或记忆结果，如下所示：

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

或者实现多值映射 Map<K,Collection<V>> ，支持每个键多个值：

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

映射函数不应在计算期间修改此map。

实现要求：

默认实现等效于此 map 的以下步骤，然后返回当前值或 null（如果现在不存在）：

 
 if (map.get(key) == null) {
   V newValue = mappingFunction.apply(key);
   if (newValue != null)
     map.put(key, newValue);
 }
  

默认实现不保证检测映射函数是否在计算期间修改此map，并且在适当时报告错误。非并发实现应该重写此方法，并且在尽力而为的基础上，如果检测到映射函数在计算期间修改此map，则抛出 ConcurrentModificationException。如果检测到映射函数在计算期间修改此map并且因此计算永远无法完成，则并发实现应重写此方法并尽最大努力抛出 IllegalStateException。

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

参数：

key - 与指定值关联的键

mappingFunction - 计算值的映射函数

返回：

与指定键关联的当前（现有或计算）值，如果计算值为 null，则为 null

抛出：

NullPointerException - 如果指定键为空且此map不支持空键，或者 mappingFunction 为空

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中 (optional)

自从：

1.8

computeIfPresent

default V  computeIfPresent(K  key, BiFunction <? super K ,? super V ,? extends V > remappingFunction)
            

如果指定键的值存在且非空，则尝试在给定键及其当前映射值的情况下计算新映射。

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

重新映射函数不应在计算期间修改此map。

实现要求：

默认实现等效于为此 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);
 }
  

默认实现不保证检测重新映射函数是否在计算期间修改此map，并在适当时报告错误。非并发实现应该重写此方法，并且在尽力而为的基础上，如果检测到重新映射函数在计算期间修改此map，则抛出 ConcurrentModificationException。如果检测到重新映射函数在计算期间修改了此map，并且因此计算永远无法完成，则并发实现应覆盖此方法，并尽最大努力抛出 IllegalStateException。

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

参数：

key - 与指定值关联的键

remappingFunction - 计算值的重映射函数

返回：

与指定键关联的新值，如果没有则为 null

抛出：

NullPointerException - 如果指定键为空且此map不支持空键，或者 remappingFunction 为空

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中 (optional)

自从：

1.8

compute

default V  compute(K  key, BiFunction <? super K ,? super V ,? extends V > remappingFunction)
            

尝试计算指定键及其当前映射值的映射（如果没有当前映射，则为 null）。例如，要创建或将 String 消息附加到值映射：

 
 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg)) 

（方法 merge() 通常更易于用于此类目的。）

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

重新映射函数不应在计算期间修改此map。

实现要求：

默认实现相当于为此 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;
  

默认实现不保证检测重新映射函数是否在计算期间修改此map，并在适当时报告错误。非并发实现应该重写此方法，并且在尽力而为的基础上，如果检测到重新映射函数在计算期间修改此map，则抛出 ConcurrentModificationException。如果检测到重新映射函数在计算期间修改了此map，并且因此计算永远无法完成，则并发实现应覆盖此方法，并尽最大努力抛出 IllegalStateException。

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

参数：

key - 与指定值关联的键

remappingFunction - 计算值的重映射函数

返回：

与指定键关联的新值，如果没有则为 null

抛出：

NullPointerException - 如果指定键为空且此map不支持空键，或者 remappingFunction 为空

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中 (optional)

自从：

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。

实现要求：

默认实现等效于为此 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);
  

默认实现不保证检测重新映射函数是否在计算期间修改此map，并在适当时报告错误。非并发实现应该重写此方法，并且在尽力而为的基础上，如果检测到重新映射函数在计算期间修改此map，则抛出 ConcurrentModificationException。如果检测到重新映射函数在计算期间修改了此map，并且因此计算永远无法完成，则并发实现应覆盖此方法，并尽最大努力抛出 IllegalStateException。

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

参数：

key - 与结果值关联的键

value - 要与键关联的现有值合并的非空值，或者，如果没有现有值或空值与键关联，则与键关联

remappingFunction - 重新映射函数以重新计算值（如果存在）

返回：

与指定键关联的新值，如果没有值与该键关联，则返回 null

抛出：

UnsupportedOperationException - 如果此map不支持 put 操作 (optional )

ClassCastException - 如果指定键或值的类阻止它存储在此map中 (optional)

IllegalArgumentException - 如果指定键或值的某些属性阻止它存储在此map中 (optional)

NullPointerException - 如果指定键为空且此map不支持空键或值或 remappingFunction 为空

自从：

1.8

of

static <K, V> Map <K,V> of()
            

返回包含零映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

返回：

一个空的Map

自从：

9

of

static <K, V> Map <K,V> of(K k1, V v1)
            

返回包含单个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 映射的键

v1 - 映射的值

返回：

包含指定map的 Map

抛出：

NullPointerException - 如果键或值是 null

自从：

9

of

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

返回包含两个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

返回：

包含指定map的 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)
            

返回包含三个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

返回：

包含指定map的 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)
            

返回包含四个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

返回：

包含指定map的 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)
            

返回包含五个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

返回：

包含指定map的 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)
            

返回包含六个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

k6 - 第六个映射的键

v6 - 第六个映射的值

返回：

包含指定map的 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)
            

返回包含七个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

k6 - 第六个映射的键

v6 - 第六个映射的值

k7 - 第七个映射的键

v7 - 第七个映射的值

返回：

包含指定map的 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)
            

返回包含八个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

k6 - 第六个映射的键

v6 - 第六个映射的值

k7 - 第七个映射的键

v7 - 第七个映射的值

k8 - 第八个映射的键

v8 - 第八个映射的值

返回：

包含指定map的 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)
            

返回包含九个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

k6 - 第六个映射的键

v6 - 第六个映射的值

k7 - 第七个映射的键

v7 - 第七个映射的值

k8 - 第八个映射的键

v8 - 第八个映射的值

k9 - 第九个映射的键

v9 - 第九个映射的值

返回：

包含指定map的 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)
            

返回包含十个映射的不可修改的映射。有关详细信息，请参阅 不可修改的map。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

k1 - 第一个映射的键

v1 - 第一个映射的值

k2 - 第二个映射的键

v2 - 第二个映射的值

k3 - 第三个映射的键

v3 - 第三个映射的值

k4 - 第四个映射的键

v4 - 第四个映射的值

k5 - 第五个映射的键

v5 - 第五个映射的值

k6 - 第六个映射的键

v6 - 第六个映射的值

k7 - 第七个映射的键

v7 - 第七个映射的值

k8 - 第八个映射的键

v8 - 第八个映射的值

k9 - 第九个映射的键

v9 - 第九个映射的值

k10 - 第 10 个映射的键

v10 - 第 10 个映射的值

返回：

包含指定map的 Map

抛出：

IllegalArgumentException - 如果有任何重复键

NullPointerException - 如果任何键或值是 null

自从：

9

ofEntries

@SafeVarargs static <K, V> Map <K,V> ofEntries(Map.Entry <? extends K,? extends V>... entries)
            

返回一个不可修改的映射，其中包含从给定条目中提取的键和值。条目本身不存储在map中。有关详细信息，请参阅 不可修改的map。

API 注意：

使用Map.entry() 方法创建map条目很方便。例如，

   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 s 包含从中填充映射的键和值

返回：

包含指定map的 Map

抛出：

IllegalArgumentException - 如果有任何重复键

NullPointerException - 如果任何条目、键或值是 null ，或者如果 entries 数组是 null

自从：

9

参见：

• Map.entry()

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。
• 它们不可序列化。
• 他们是 value-based 。程序员应该将 equal 实例视为可互换的，不应将它们用于同步，否则可能会发生不可预测的行为。例如，在未来的版本中，同步可能会失败。调用者不应假设返回实例的身份。此方法可自由创建新实例或重用现有实例。

API 注意：

对于可序列化的 Entry，请参见 AbstractMap.SimpleEntry 或 AbstractMap.SimpleImmutableEntry 。

类型参数：

K - 键的类型

V - 值的类型

参数：

k - 关键

v - 值

返回：

包含指定键和值的 Entry

抛出：

NullPointerException - 如果键或值是 null

自从：

9

参见：

• Map.ofEntries()

copyOf

static <K, V> Map <K,V> copyOf(Map <? extends K,? extends V> map)
            

返回包含给定 Map 条目的 不可修改的map。给定的 Map 不能为 null，并且它不能包含任何 null 键或值。如果给定的 Map 随后被修改，则返回的 Map 将不会反映此类修改。

实现注意事项：

如果给定的 Map 是 不可修改的map ，调用 copyOf 通常不会创建副本。

类型参数：

K - Map 的键类型

V - Map 的值类型

参数：

map - 从中提取条目的 Map 必须为非空

返回：

一个 Map 包含给定 Map 的条目

抛出：

NullPointerException - 如果map为空，或者它包含任何空键或值

自从：

10