Module java.base
Package java.util.concurrent

Interface ConcurrentMap<K,V>

类型参数:
K - 此映射维护的键的类型
V - 映射值的类型
所有超接口:
Map<K,V>
所有已知子接口:
ConcurrentNavigableMap<K,V>
所有已知实现类:
ConcurrentHashMap, ConcurrentSkipListMap
public interface ConcurrentMap<K,V> extends Map<K,V>
一个提供线程安全性和原子性保证的Map。

为了保持指定的保证，必须通过此接口的实现重写从Map继承的包括putIfAbsent(K, V)在内的方法的默认实现。类似地，通过方法Map.keySet()、Map.values()和Map.entrySet()返回的集合的实现必须在必要时重写诸如removeIf之类的方法以保留原子性保证。

内存一致性效果: 与其他并发集合一样，在将对象放入ConcurrentMap作为键或值之前的线程中的操作先行发生于在另一个线程中从ConcurrentMap访问或移除该对象的操作。

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

自 JDK 版本:
1.5

  • Nested Class Summary

    Nested classes/interfaces declared in interface java.util.Map

    Map.Entry<K,V>

  • Method Summary

    Modifier and Type
    Method
    Description
    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 declared in interface java.util.Map

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

  • Method Details

    • getOrDefault

      default V getOrDefault(Object key, V defaultValue)
      返回指定键映射到的值，如果此映射不包含键的映射，则返回defaultValue。
      指定者:
      getOrDefault 在接口 Map<K,V>中
      实现注意:
      此实现假定ConcurrentMap不能包含null值，并且get()返回null明确表示键不存在。支持null值的实现必须重写此默认实现。
      参数:
      key - 要返回其关联值的键
      defaultValue - 键的默认映射
      返回:
      指定键映射到的值，如果此映射不包含键的映射，则返回defaultValue
      异常:
      ClassCastException - 如果键对于此映射的类型不合适（可选）
      NullPointerException - 如果指定的键为null且此映射不允许null键（可选）
      自 JDK 版本:
      1.8

    • forEach

      default void forEach(BiConsumer<? super K,? super V> action)
      对此映射中的每个条目执行给定操作，直到所有条目都已处理完毕或操作引发异常。除非实现类另有规定，操作按照条目集合迭代的顺序执行（如果指定了迭代顺序）。操作引发的异常将传递给调用者。
      指定者:
      forEach 在接口 Map<K,V>中
      实现要求:
      默认实现等效于，对于此map： 
       
 for (Map.Entry<K,V> entry : map.entrySet()) {
   action.accept(entry.getKey(), entry.getValue());
 }
      实现注意:
      默认实现假定getKey()或getValue()抛出的IllegalStateException表示条目已被移除且无法处理。操作将继续进行下一个条目。
      参数:
      action - 要对每个条目执行的操作
      异常:
      NullPointerException - 如果指定的操作为null
      自 JDK 版本:
      1.8

    • putIfAbsent

      V putIfAbsent(K key, V value)
      如果指定的键尚未与值关联，则将其与给定值关联。对于此map，这相当于： 
       
 if (!map.containsKey(key))
   return map.put(key, value);
 else
   return map.get(key);
      除了该操作是原子执行的。
      指定者:
      putIfAbsent 在接口 Map<K,V>中
      实现注意:
      此实现有意重新抽象了Map中提供的不合适的默认值。
      参数:
      key - 要将指定值关联的键
      value - 要与指定键关联的值
      返回:
      与指定键关联的先前值，如果该键没有映射，则返回null。（如果实现支持null值，则null返回还可以表示该映射先前将null与该键关联。）
      异常:
      UnsupportedOperationException - 如果此映射不支持put操作
      ClassCastException - 如果指定键或值的类阻止其存储在此映射中
      NullPointerException - 如果指定的键或值为null，并且此映射不允许null键或值
      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;
 }
      除了该操作是原子执行的。
      指定者:
      remove 在接口 Map<K,V>中
      实现注意:
      此实现有意重新抽象了Map中提供的不合适的默认值。
      参数:
      key - 与指定值关联的键
      value - 预期与指定键关联的值
      返回:
      如果值已被移除，则true
      异常:
      UnsupportedOperationException - 如果此映射不支持remove操作
      ClassCastException - 如果键或值对于此映射的类型不合适（可选）
      NullPointerException - 如果指定的键或值为null，并且此映射不允许null键或值（可选）

    • 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;
 }
      除了该操作是原子执行的。
      指定者：
      replace 在接口 Map<K,V>
      实现注意：
      此实现有意重新抽象了Map中提供的不合适的默认值。
      参数：
      key - 指定值关联的键
      oldValue - 预期与指定键关联的值
      newValue - 要与指定键关联的值
      返回：
      如果值已被替换，则返回true
      抛出：
      UnsupportedOperationException - 如果此映射不支持put操作
      ClassCastException - 如果指定键或值的类别阻止其存储在此映射中
      NullPointerException - 如果指定键或值为null，并且此映射不允许null键或值
      IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中

    • replace

      V replace(K key, V value)
      仅当键当前映射到某个值时才替换该键的条目。这相当于对于这个map： 
       
 if (map.containsKey(key))
   return map.put(key, value);
 else
   return null;
      除了该操作是原子执行的。
      指定者：
      replace 在接口 Map<K,V>
      实现注意：
      此实现有意重新抽象了Map中提供的不合适的默认值。
      参数：
      key - 指定值关联的键
      value - 要与指定键关联的值
      返回：
      与指定键关联的先前值，如果键没有映射，则返回null。（如果实现支持null值，则null返回还可以表示映射先前将null与键关联。）
      抛出：
      UnsupportedOperationException - 如果此映射不支持put操作
      ClassCastException - 如果指定键或值的类别阻止其存储在此映射中
      NullPointerException - 如果指定键或值为null，并且此映射不允许null键或值
      IllegalArgumentException - 如果指定键或值的某些属性阻止其存储在此映射中

    • replaceAll

      default void replaceAll(BiFunction<? super K,? super V,? extends V> function)
      用给定函数在每个条目上调用，直到所有条目都被处理或函数抛出异常为止，用结果替换每个条目的值。函数抛出的异常将被传递给调用者。
      指定者：
      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不能包含null值，并且get()返回null明确表示键不存在。支持null值的实现必须覆盖此默认实现。

      参数：
      function - 要应用于每个条目的函数
      抛出：
      UnsupportedOperationException - 如果此映射的条目集迭代器不支持set操作。
      NullPointerException - 如果指定函数为null，或者替换值为null且此映射不允许null值（可选）
      ClassCastException - 如果替换值的类别阻止其存储在此映射中（可选）
      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);

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

      指定者：
      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不能包含null值，并且get()返回null明确表示键不存在。支持null值的实现必须覆盖此默认实现。

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

    • computeIfPresent

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

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

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

      指定由:
      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;
      当多个线程尝试更新时，可能多次调用map操作和重新映射函数。

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

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

      指定由:
      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;
   }
 }
      当多个线程尝试更新时，可能多次调用map操作和重新映射函数。

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

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

      指定由:
      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;
   }
 }
      当多个线程尝试更新时，可能多次调用map操作和重新映射函数。

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

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