Module java.base

软件包 java.util.concurrent

Interface ConcurrentMap<K,V>

参数类型

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

V - 映射值的类型

All Superinterfaces:

Map<K,V>

All Known Subinterfaces:

ConcurrentNavigableMap<K,V>

所有已知实现类：

ConcurrentHashMap ， ConcurrentSkipListMap

public interface ConcurrentMap<K,V>
extends Map<K,V>

A Map提供线程安全和原子性保证。

为了保持指定的保证，从Map继承的包括putIfAbsent(K, V)在内的方法的默认实现必须被该接口的实现覆盖。 类似的，集合的实现返回的方法Map.keySet() ， Map.values() ，并Map.entrySet()必须覆盖的方法，如removeIf必要时保留原子性保证。

内存一致性效果：与其他并发集合一样，在将对象放入ConcurrentMap作为键或happen-before之后的线程中的ConcurrentMap在另一个线程中的ConcurrentMap访问或删除该对象之后。

此接口是Java Collections Framework的成员。

从以下版本开始：

1.5

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

方法摘要

Modifier and Type	方法	描述
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)	如果指定的密钥的值存在且非空，则尝试计算给定密钥及其当前映射值的新映射。
default void	forEach(BiConsumer<? super K,? super V> action)	对此映射中的每个条目执行给定的操作，直到所有条目都被处理或操作引发异常。
default V	getOrDefault(Object key, V defaultValue)	返回指定键映射到的值，如果此映射不包含键的映射，则返回 defaultValue 。
default V	merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)	如果指定的键尚未与值相关联或与null相关联，则将其与给定的非空值相关联。
V	putIfAbsent(K key, V value)	如果指定的键尚未与值相关联，则将其与给定值相关联。
boolean	remove(Object key, Object value)	仅当当前映射到给定值时才删除密钥的条目。
V	replace(K key, V value)	仅当当前映射到某个值时才替换该项的条目。
boolean	replace(K key, V oldValue, V newValue)	仅当当前映射到给定值时才替换密钥的条目。
default void	replaceAll(BiFunction<? super K,? super V,? extends V> function)	将每个条目的值替换为对该条目调用给定函数的结果，直到所有条目都被处理或该函数抛出异常。

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entry, entrySet, equals, get, hashCode, isEmpty, keySet, of, of, of, of, of, of, of, of, of, of, of, ofEntries, put, putAll, remove, size, values

方法详细信息

getOrDefault

default V getOrDefault(Object key,
                       V defaultValue)

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

Specified by:

getOrDefault在接口 Map<K,V>

Implementation Note:

此实现假定ConcurrentMap不能包含空值，而get()返回null明确表示该键不存在。 支持空值的实现必须覆盖此默认实现。

参数

key - 要返回其关联值的键

defaultValue - 键的默认映射

结果

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

异常

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

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

从以下版本开始：

1.8

forEach

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

对此映射中的每个条目执行给定的操作，直到所有条目都被处理或操作引发异常。 除非实现类另有指定，否则按照进入设置迭代的顺序执行操作（如果指定了迭代顺序）。操作引发的异常被转发给调用者。

Specified by:

forEach在接口 Map<K,V>

实现要求：

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

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

Implementation Note:

默认实现假定IllegalStateException被抛出getKey()或者getValue()表示该条目已被删除，无法处理。 继续进行操作。

参数

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

异常

NullPointerException - 如果指定的操作为空

从以下版本开始：

1.8

putIfAbsent

V putIfAbsent(K key,
              V value)

如果指定的键尚未与值相关联，则将其与给定值相关联。 这相当于，对于这个map ：

   if (!map.containsKey(key)) return map.put(key, value); else return map.get(key); 

除了动作以原子方式执行。

Specified by:

putIfAbsent在接口 Map<K,V>

Implementation Note:

该实现有意地重新提取了 Map提供的不正确的默认值。

参数

key - 指定值与之关联的键

value - 与指定键相关联的值

结果

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

异常

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

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

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

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

remove

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; } 

除了动作以原子方式执行。

Specified by:

remove在接口 Map<K,V>

Implementation Note:

该实现有意地重新提取了 Map提供的不正确的默认值。

参数

key - 与指定值相关联的键

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

结果

true如果该值被删除

异常

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

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

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

replace

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; } 

除了动作以原子方式执行。

Specified by:

replace在接口 Map<K,V>

Implementation Note:

此实现有意地重新提取了 Map提供的不正确的默认值。

参数

key - 与指定值相关联的键

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

newValue - 与指定键相关联的值

结果

true如果该值被替换

异常

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

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

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

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

replace

V replace(K key,
          V value)

仅当当前映射到某个值时才替换该项的条目。 这相当于，对于这个map ：

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

除了动作以原子方式执行。

Specified by:

replace在接口 Map<K,V>

Implementation Note:

该实现有意地重新提取了 Map提供的不正确的默认值。

参数

key - 与指定值相关联的键

value - 与指定键相关联的值

结果

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

异常

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

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

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

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

replaceAll

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

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

Specified by:

replaceAll在接口 Map<K,V>

实现要求：

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

   for (Map.Entry<K,V> entry : map.entrySet()) { K k; V v; do { k = entry.getKey(); v = entry.getValue(); } while (!map.replace(k, v, function.apply(k, v))); } 

当多个线程尝试更新时，默认实现可能会重试这些步骤，包括针对给定的密钥重复地调用该功能。

此实现假定ConcurrentMap不能包含空值，而get()返回null明确地表示密钥不存在。 支持空值的实现必须覆盖此默认实现。

参数

function - 应用于每个条目的功能

异常

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

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

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

IllegalArgumentException - 如果替换值的某些属性阻止其存储在此映射中（ optional ）

从以下版本开始：

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

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

Specified by:

computeIfAbsent在接口 Map<K,V>

实现要求：

默认实现相当于此map的以下步骤：

   V oldValue, newValue; return ((oldValue = map.get(key)) == null && (newValue = mappingFunction.apply(key)) != null && (oldValue = map.putIfAbsent(key, newValue)) == null) ? newValue : oldValue; 

此实现假定ConcurrentMap不能包含空值，而get()明确地返回null表示密钥不存在。 支持空值的实现必须覆盖此默认实现。

参数

key - 指定值与之关联的键

mappingFunction - 计算值的映射函数

结果

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

异常

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

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

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

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

从以下版本开始：

1.8

computeIfPresent

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

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

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

重映射功能在计算过程中不应修改此映射。

Specified by:

computeIfPresent接口 Map<K,V>

实现要求：

默认实现相当于为此执行以下步骤： map ：

   for (V oldValue; (oldValue = map.get(key)) != null; ) { V newValue = remappingFunction.apply(key, oldValue); if ((newValue == null) ? map.remove(key, oldValue) : map.replace(key, oldValue, newValue)) return newValue; } return null; 

当多个线程尝试更新时，可以多次调用映射操作和重映射功能。

此实现假定ConcurrentMap不能包含空值，而get()返回null明确表示该键不存在。 支持空值的实现必须覆盖此默认实现。

参数

key - 与该值相关联的键

remappingFunction - 计算值的重映射函数

结果

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

异常

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

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

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

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 ，映射将被删除（如果最初缺少，则保持不存在）。 如果重映射函数本身引发（未检查）异常，则重新引导异常，并且当前映射保持不变。

重映射功能在计算过程中不应修改此映射。

Specified by:

compute接口 Map<K,V>

实现要求：

默认实现等同于为此map执行以下步骤：

   for (;;) { V oldValue = map.get(key); V newValue = remappingFunction.apply(key, oldValue); if (newValue != null) { if ((oldValue != null) ? map.replace(key, oldValue, newValue) : map.putIfAbsent(key, newValue) == null) return newValue; } else if (oldValue == null || map.remove(key, oldValue)) { return null; } } 

当多个线程尝试更新时，可以多次调用映射操作和重映射功能。

此实现假定ConcurrentMap不能包含空值，而get()返回null明确表示该键不存在。 支持空值的实现必须覆盖此默认实现。

参数

key - 指定值与之关联的键

remappingFunction - 计算值的重映射函数

结果

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

异常

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

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

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

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 ，则映射将被删除。 如果重映射函数本身引发（未检查）异常，则重新引导异常，并且当前映射保持不变。

重映射功能在计算过程中不应修改此映射。

Specified by:

merge在接口 Map<K,V>

实现要求：

默认实现相当于为此执行以下步骤： map ：

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

当多个线程尝试更新时，可以多次调用映射操作和重映射功能。

此实现假定ConcurrentMap不能包含空值，而get()明确地返回null表示密钥不存在。 支持空值的实现必须覆盖此默认实现。

参数

key - 与结果值相关联的键

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

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

结果

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

异常

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

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

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

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

从以下版本开始：

1.8