Интерфейс ConcurrentMap<K,V>

Параметры типа:: K - тип ключей, поддерживаемых этой картой; V - тип сопоставленных значений

Все суперинтерфейсы:: Map<K,V>

Все известные подинтерфейсы:: ConcurrentNavigableMap<K,V>

Все известные реализующие классы:: ConcurrentHashMap, ConcurrentSkipListMap

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

A Map обеспечивающий безопасность потоков и гарантии атомарности.

Для поддержания указанных гарантий, реализация методов по умолчанию, включая putIfAbsent(K, V) унаследованные от Map, должны быть переопределены реализациями этого интерфейса. Аналогично, реализации коллекций, возвращаемых методами Map.keySet(), Map.values() и Map.entrySet(), должны переопределять методы, такие как removeIf, когда это необходимо, для сохранения гарантий атомарности.

Влияние согласованности памяти: Как и в других коллекциях для конкурентного доступа, действия в потоке до помещения объекта в ConcurrentMap в качестве ключа или значения предшествуют действиям, последующим за доступом или удалением этого объекта из ConcurrentMap в другом потоке.

Этот интерфейс является членом Java Collections Framework.

С:: 1.5

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.Map

Map.Entry<K,V>

Краткое описание методов

Модификатор и тип	Метод	Описание
`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)`	Если значение для указанного ключа присутствует и не равно null, пытается вычислить новое отображение, учитывая ключ и его текущее сопоставленное значение (необязательная операция).
`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)`	Заменяет значение каждой записи результатом вызова заданной функции для этой записи, пока все записи не будут обработаны или функция не выбросит исключение (необязательная операция).

Методы, объявленные в интерфейсе java.util.Map

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

END_OF_DOCUMENT_MARKER

Подробное описание методов

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-ключей (необязательно)
С:: 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());
 }

Примечание реализации:

Реализация по умолчанию предполагает, что IllegalStateException, выброшенное getKey() или getValue(), указывает, что запись была удалена и не может быть обработана. Обработка продолжается для последующих записей.

Параметры:

action - действие, которое должно выполняться для каждой записи

Исключения:

NullPointerException - если указанное действие равно null

С:

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 - если операция replaceAll не поддерживается этой картой (необязательно)

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

Функция отображения не должна изменять эту карту во время вычисления.

Specified by:

computeIfAbsent в интерфейсе Map<K,V>

Implementation Requirements:

Реализация по умолчанию эквивалентна выполнению следующих шагов для этой 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 однозначно означает, что ключ отсутствует. Реализации, поддерживающие нулевые значения, обязаны переопределить эту реализацию по умолчанию.

Parameters:

key - ключ, с которым должно быть связано указанное значение

mappingFunction - функция отображения для вычисления значения

Returns:

текущее (существующее или вычисленное) значение, связанное с указанным ключом, или null, если вычисленное значение равно null

Throws:

UnsupportedOperationException - если операция computeIfAbsent не поддерживается этой картой (необязательно)

ClassCastException - если класс указанного ключа или значения препятствует его хранению в этой карте (необязательно)

NullPointerException - если указанный ключ равен null, и эта карта не поддерживает нулевые ключи, или mappingFunction равен null

IllegalArgumentException - если какое-либо свойство указанного ключа или значения препятствует его хранению в этой карте (необязательно)

Since:

1.8

computeIfPresent

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

Если значение для указанного ключа присутствует и не равно null, пытается вычислить новое отображение, заданное ключом и его текущим сопоставленным значением (необязательная операция).

Если функция переназначения возвращает null, отображение удаляется. Если сама функция переназначения вызывает (непроверенное) исключение, исключение повторно выбрасывается, и текущее отображение остается неизменным.

Функция переназначения не должна изменять эту карту во время вычисления.

Specified by:

computeIfPresent в интерфейсе Map<K,V>

Implementation Requirements:

Реализация по умолчанию эквивалентна выполнению следующих шагов для этой 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;

Когда несколько потоков пытаются выполнить обновления, операции с картой и функция переназначения могут вызываться многократно.

Parameters:

key - ключ, с которым должно быть связано указанное значение

remappingFunction - функция переназначения для вычисления значения

Returns:

новое значение, связанное с указанным ключом, или null, если нет

Throws:

UnsupportedOperationException - если операция computeIfPresent не поддерживается этой картой (необязательно)

ClassCastException - если класс указанного ключа или значения препятствует его хранению в этой карте (необязательно)

NullPointerException - если указанный ключ равен null, и эта карта не поддерживает нулевые ключи, или remappingFunction равен null

Since:

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>

Implementation Requirements:

Реализация по умолчанию эквивалентна выполнению следующих шагов для этой 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 однозначно означает, что ключ отсутствует. Реализации, поддерживающие нулевые значения, обязаны переопределить эту реализацию по умолчанию.

Parameters:

key - ключ, с которым должно быть связано указанное значение

remappingFunction - функция переназначения для вычисления значения

Returns:

новое значение, связанное с указанным ключом, или null, если нет

Throws:

UnsupportedOperationException - если операция compute не поддерживается этой картой (необязательно)

ClassCastException - если класс указанного ключа или значения препятствует его хранению в этой карте (необязательно)

NullPointerException - если указанный ключ равен null, и эта карта не поддерживает нулевые ключи, или remappingFunction равен null

Since:

1.8

merge

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

Если указанный ключ ещё не связан со значением или связан с null, связывает его с заданным ненулевым значением (необязательная операция). В противном случае, заменяет связанное значение результатом заданной функции переназначения или удаляет его, если результат равен null. Этот метод может быть полезен для объединения нескольких сопоставленных значений для ключа. Например, для создания или добавления String msg к отображению значения:

 
 map.merge(key, msg, String::concat)

Если функция переназначения возвращает null, отображение удаляется. Если сама функция переназначения вызывает (непроверенное) исключение, исключение повторно выбрасывается, а текущее отображение остается неизменным.

Функция переназначения не должна изменять эту карту во время вычисления.

Specified by:

merge в интерфейсе Map<K,V>

Implementation Requirements:

Реализация по умолчанию эквивалентна выполнению следующих шагов для этой 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;
   }
 }

Parameters:

key - ключ, с которым должно быть связано результирующее значение

value - ненулевое значение, которое должно быть объединено с существующим значением, связанным с ключом, или, если с ключом не связано ни одного значения или значение равно null, должно быть связано с ключом

remappingFunction - функция переназначения для повторного вычисления значения, если оно присутствует

Returns:

новое значение, связанное с указанным ключом, или null, если с ключом не связано ни одного значения

Throws:

UnsupportedOperationException - если операция merge не поддерживается этой картой (необязательно)

ClassCastException - если класс указанного ключа или значения препятствует его хранению в этой карте (необязательно)

NullPointerException - если указанный ключ равен null, и эта карта не поддерживает нулевые ключи, или значение или remappingFunction равно null

Since:

1.8

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/concurrent/ConcurrentMap.html