Module java.base

软件包 java.util

Interface Map<K,V>

参数类型

K - 由此地图维护的键的类型

V - 映射值的类型

All Known Subinterfaces:

Bindings ， ConcurrentMap<K,V> ， ConcurrentNavigableMap<K,V> ， LogicalMessageContext ， MessageContext ， NavigableMap<K,V> ， ObservableMap<K,V> ， ObservableMapValue<K,V> ， SOAPMessageContext ， SortedMap<K,V> ， WritableMapValue<K,V>

所有已知实现类：

AbstractMap ， Attributes ， AuthProvider ， ClipboardContent ， ConcurrentHashMap ， ConcurrentSkipListMap ， EnumMap ， HashMap ， Hashtable ， Headers ， IdentityHashMap ， LinkedHashMap ， MapBinding ， MapExpression ， MapProperty ， MapPropertyBase ， MultiMapResult ， PrinterStateReasons ， Properties ， Provider ， ReadOnlyMapProperty ， ReadOnlyMapPropertyBase ， ReadOnlyMapWrapper ， RenderingHints ， ScriptObjectMirror ， SimpleBindings ， SimpleMapProperty ， TabularDataSupport ， TreeMap ， UIDefaults ， WeakHashMap

public interface Map<K,V>

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

该接口代替了Dictionary类，它是一个完全抽象的类而不是接口。

Map接口提供了三个集合视图 ，允许将映射的内容视为一组键，值的集合或键值映射集合。 地图的顺序被定义为其中在地图上的集合视图迭代返回元素的顺序。 一些地图实现，如TreeMap类，对其顺序做出特定的保证; 其他人，像HashMap类，不要。

注意：如果使用可变对象作为地图键，必须非常小心。 如果对象的值以影响equals比较的方式更改，而对象是地图中的键，则不会指定映射的行为。 这个禁令的一个特殊情况是，地图不允许将自己包含在内。 虽然地图可以将其本身作为一个值，但建议您非常小心： equals和hashCode方法在这样的地图上已经不太明确。

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

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

一些地图实现对它们可能包含的键和值有限制。 例如，一些实现禁止空键和值，有些对键的类型有限制。 尝试插入不合格的键或值会引发未经检查的异常，通常为NullPointerException或ClassCastException 。 尝试查询不合格键或值的存在可能会引发异常，或者可能只是返回false; 一些实现将展现出前者的行为，一些实现将展现出后者。 更一般来说，尝试对不符合条件的密钥或值的操作，其完成不会导致将不合格元素插入到地图中可能会导致异常或可能成功执行该选项。 此异常在此接口的规范中标记为“可选”。

Collections Framework接口中的许多方法都是按照equals方法进行定义的。 例如， containsKey(Object key)方法的规范说：“当且仅当此映射包含k的映射关系true时才返回(key==null ? k==null : key.equals(k)) 。 该规范不应该被解释为意味着调用Map.containsKey与非空参数key会导致key.equals(k)被调用的任意键k 。 实现可以自由地实现优化，从而避免equals调用，例如，首先比较两个密钥的哈希码。 （ Object.hashCode()规范保证具有不等的哈希码的两个对象不能相等。）更一般地，各种Collections Framework接口的实现可以随意利用底层的Object方法的指定行为，无论执行者认为合适。

执行递归遍历地图的一些地图操作可能会失败，并且地图直接或间接包含自身的自引用实例有异常。 这包括clone() ， equals() ， hashCode()和toString()方法。 实现可以可选地处理自引用场景，然而大多数当前实现不这样做。

Immutable Map Static Factory Methods

Map.of()和Map.ofEntries()静态工厂方法提供了创建不可变地图的便捷方式。 由这些方法创建的Map实例具有以下特征：

• 它们在结构上是不可变的 。 无法添加，删除或更新密钥和值。 调用任何mutator方法将始终导致UnsupportedOperationException被抛出。 但是，如果包含的键或值本身是可变的，则可能会导致地图行为不一致或其内容似乎更改。
• 他们不允许使用null键和值。 尝试使用null键或值创建它们将导致NullPointerException 。
• 如果所有键和值都是可序列化的，它们是可序列化的。
• 他们在创建时拒绝重复的键。 传递给静态工厂方法的重复键将导致IllegalArgumentException 。
• 映射的迭代顺序是未指定的，可能会发生变化。
• 他们是value-based 。 调用者不应该对返回的实例的身份进行假设。 工厂可以自由创建新的实例或重用现有的实例。 因此，对这些实例的身份敏感操作（引用等式（ == ），身份哈希码和同步）是不可靠的，应该避免。
• 它们按照Serialized Form页面的规定进行序列化。

此接口是Java Collections Framework的成员。

从以下版本开始：

1.2

另请参见：

HashMap ， TreeMap ， Hashtable ， SortedMap ， Collection ， Set

Nested Class Summary

Nested Classes

Modifier and Type	接口	描述
static interface	Map.Entry<K,V>	地图条目（键值对）。

方法摘要

Modifier and Type	方法	描述
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.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相关联，则将其与给定的非空值相关联。
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视图。

方法详细信息

size

int size()

返回此地图中键值映射的数量。 如果地图包含Integer.MAX_VALUE元素，返回Integer.MAX_VALUE 。

结果

该地图中键值映射的数量

isEmpty

boolean isEmpty()

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

结果

true如果该地图不包含键值映射

containsKey

boolean containsKey(Object key)

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

参数

key - 要在此地图中存在的密钥要进行测试

结果

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

异常

ClassCastException - 如果密钥对于该地图是不合适的类型（ optional ）

NullPointerException - 如果指定的键为空，并且此映射不允许空键（ optional ）

containsValue

boolean containsValue(Object value)

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

参数

value - 要在此地图中存在的值要进行测试

结果

true如果该地图将一个或多个键映射到指定的值

异常

ClassCastException - 如果该值是该地图的不当类型（ optional ）

NullPointerException - 如果指定的值为空，并且此映射不允许空值（ optional ）

get

V get(Object key)

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

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

如果此映射允许空值，则返回值null并不一定表示该映射不包含该映射关键字; 地图也可能明确地将密钥映射到null 。 可以使用containsKey操作来区分这两种情况。

参数

key - 要返回其关联值的键

结果

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

异常

ClassCastException - 如果密钥对于该地图是不合适的类型（ optional ）

NullPointerException - 如果指定的键为空，并且此映射不允许空键（ optional ）

put

V put(K key,
      V value)

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

参数

key - 指定值与之关联的键

value - 与指定键相关联的值

结果

与key相关联的上一个值，如果null没有映射， key 。 （A null返回也可以指示以前关联的地图null与key ，如果实现支持null值。）

异常

UnsupportedOperationException - 如果此地图不支持 put操作

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

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

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

remove

V remove(Object key)

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

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

如果此映射允许空值，则返回值为null并不一定表示该映射不包含该映射关键字; 映射也可能将密钥明确映射到null 。

一旦呼叫返回，该映射将不包含指定键的映射。

参数

key - 要从地图中删除其映射的密钥

结果

先前的值相关联 key ，或 null如果没有映射 key 。

异常

UnsupportedOperationException - 如果此地图不支持 remove操作

ClassCastException - 如果密钥对于该地图是不合适的类型（ optional ）

NullPointerException - 如果指定的键为空，并且此映射不允许空键（ optional ）

putAll

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

将指定地图的所有映射复制到此映射（可选操作）。 此通话的效果与从映射关键字k到指定地图值v每个映射一次调用put(k, v)一样 。 如果在操作进行中修改了指定的地图，则此操作的行为是未定义的。

参数

m - 要存储在此地图中的映射

异常

UnsupportedOperationException - 如果此地图不支持 putAll操作

ClassCastException - 如果指定地图中的键或值的类阻止它存储在此映射中

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

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操作），迭代的结果是未定义的。 该collection支持元素移除，即从映射中相应的映射，经由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.entrySet().equals(m2.entrySet()) ，两个地图m1和m2表示相同的映射。 这可以确保equals方法在Map接口的不同实现中正常工作。

重写：

equals在 Object

参数

o - 要与该地图相等的对象

结果

true如果指定的对象等于此映射

另请参见：

Object.hashCode() ， HashMap

hashCode

int hashCode()

返回此地图的哈希码值。 地图的哈希码被定义为地图entrySet()视图中每个条目的哈希码的总和。 这确保了m1.equals(m2)意味着m1.hashCode()==m2.hashCode()对于任何两个地图m1和m2 ，所要求的一般合同Object.hashCode() 。

重写：

hashCode在 Object

结果

该地图的哈希码值

另请参见：

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

getOrDefault

default V getOrDefault(Object key,
                       V defaultValue)

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

实现要求：

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

参数

key - 要返回其关联值的键

defaultValue - 键的默认映射

结果

映射指定键的值，如果此映射不包含该键的映射， defaultValue

异常

ClassCastException - 如果密钥对于此地图是不合适的类型（ optional ）

NullPointerException - 如果指定的键为空，并且此映射不允许空键（ optional ）

从以下版本开始：

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 - 如果指定的操作为空

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 - 如果此地图的条目集迭代器不支持 set操作。

ClassCastException - 如果替换值的类阻止它存储在此映射中

NullPointerException - 如果指定的函数为空，或指定的替换值为空，并且此映射不允许为空值

ClassCastException - 如果替代值对于该地图是不合适的类型（ optional ）

NullPointerException - 如果函数或替换值为空，并且此映射不允许空值或值（ optional ）

IllegalArgumentException - 如果替换值的某些属性阻止其存储在此映射中（ 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 。 （A null返回也可以指示映射以前关联的是null ，如果实现支持空值）。

异常

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果该地图的键或值不合适（ optional ）

NullPointerException - 如果指定的键或值为空，并且此映射不允许空键或值（ optional ）

IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（ 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 - 如果此地图不支持 remove操作（ optional ）

ClassCastException - 如果该地图的键或值不合适（ optional ）

NullPointerException - 如果指定的键或值为空，并且此映射不允许空值或值（ optional ）

从以下版本开始：

1.8

replace

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

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

实现要求：

默认实现相当于，对于这个map ：

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

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

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

参数

key - 与指定值相关联的键

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

newValue - 与指定键相关联的值

结果

true如果值被替换

异常

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

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

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

NullPointerException - 如果oldValue为空，并且此映射不允许空值（ optional ）

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

从以下版本开始：

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 。 （A null返回也可以指示映射以前关联的是null的关键字，如果实现支持空值）。

异常

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果指定的键或值的类阻止它存储在此映射中（ optional ）

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

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

从以下版本开始：

1.8

computeIfAbsent

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

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

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

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

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

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

映射函数在计算过程中不应该修改该映射。

实现要求：

默认实现等同于此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

异常

NullPointerException - 如果指定的键为空，此映射不支持空键，或者mappingFunction为空

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果指定的键或值的类阻止它存储在此映射中（ optional ）

IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（ optional ）

从以下版本开始：

1.8

computeIfPresent

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

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

如果重映射函数返回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 - 如果指定的键为空，此映射不支持空键，或者remappingFunction为空

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果指定的键或值的类阻止它存储在此映射中（ optional ）

IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（ optional ）

从以下版本开始：

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执行以下步骤，然后返回当前值，如果缺少则返回null ：

   V oldValue = map.get(key); V newValue = remappingFunction.apply(key, oldValue); if (oldValue != null) { if (newValue != null) map.put(key, newValue); else map.remove(key); } else { if (newValue != null) map.put(key, newValue); else return null; }  

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

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

参数

key - 要与其关联的指定值的键

remappingFunction - 计算值的重映射函数

结果

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

异常

NullPointerException - 如果指定的键为空，此映射不支持空键，或者remappingFunction为空

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果指定的键或值的类阻止它存储在此映射中（ optional ）

IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（ 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执行以下步骤，然后返回当前值或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 - 要与与密钥相关联的现有值合并的非空值，或者如果没有与密钥相关联的现有值或空值与密钥相关联

remappingFunction - 如果存在重新计算值的重映射功能

结果

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

异常

UnsupportedOperationException - 如果此地图不支持 put操作（ optional ）

ClassCastException - 如果指定的键或值的类阻止它存储在此映射中（ optional ）

IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中（ optional ）

NullPointerException - 如果指定的键为空，并且此映射不支持空键或值或remappingFunction为空

从以下版本开始：

1.8

of

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

返回一个包含零映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

K - Map的关键类型

V - Map的值类型

结果

一个空的 Map

从以下版本开始：

9

of

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

返回包含单个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含两个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含三个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含四个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

K - Map的关键类型

V - Map的值类型

参数

k1 - 第一个映射的关键

v1 - 第一个映射的值

k2 - 第二个映射的关键

v2 - 第二个映射的值

k3 - k3 - k3 - k3 - k3 - 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)

返回一个包含五个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含六个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含七个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含八个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含九个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含十个映射的不可变地图。 详见Immutable Map Static Factory Methods 。

参数类型

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)

返回包含从给定条目提取的键和值的不可变地图。 条目本身不存储在地图中。 详见Immutable Map Static Factory Methods 。

API Note:

使用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

另请参见：

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.setValue()在返回Entry结果UnsupportedOperationException 。
• 它们不是可序列化的。
• 他们是value-based 。 调用者不应该对返回的实例的身份进行假设。 此方法可以自由创建新实例或重用现有实例。 因此，对这些实例的身份敏感操作（引用等式（ == ），身份哈希码和同步）是不可靠的，应该避免。

API Note:

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

参数类型

K - 键的类型

V - 值的类型

参数

k - 关键

v - 值

结果

一个 Entry包含指定的键和值

异常

NullPointerException - 如果键值是 null

从以下版本开始：

9

另请参见：

Map.ofEntries()