Интерфейс 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

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

getOrDefault

default V getOrDefault(Object key, V defaultValue)

Возвращает значение, связанное с заданным ключом, или defaultValue , если в этом отображении нет сопоставления для ключа.

Указано:: getOrDefault в интерфейсе Map<K,V>
Примечание реализации:: Эта реализация предполагает, что ConcurrentMap не может содержать нулевые значения и get() возвращение null однозначно означает, что ключ отсутствует. Реализации, которые поддерживают нулевые значения, обязаны переопределить эту реализацию по умолчанию.
Параметры:: key - ключ, связанное значение которого должно быть возвращено; defaultValue - значение по умолчанию для ключа
Возвращает:: значение, связанное с заданным ключом, или defaultValue , если в этом отображении нет сопоставления для ключа
Выбрасывает:: ClassCastException - если ключ неподходящего типа для этого отображения (необязательно); NullPointerException - если указанный ключ равен 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 с ключом, если реализация поддерживает нулевые значения.)
Выбрасывает:: UnsupportedOperationException - если операция put не поддерживается этим отображением; ClassCastException - если класс указанного ключа или значения препятствует его хранению в этом отображении; NullPointerException - если указанный ключ или значение равно 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, а это отображение не допускает нулевых ключей или значений (необязательно)

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, а это отображение не допускает нулевых ключей или значений; 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 с ключом, если реализация поддерживает нулевые значения.)
Выбрасывает:: UnsupportedOperationException - если операция put не поддерживается этим отображением; ClassCastException - если класс указанного ключа или значения препятствует его хранению в этом отображении; NullPointerException - если указанный ключ или значение равно 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 не может содержать нулевых значений и get() возвращение null однозначно означает, что ключ отсутствует. Реализации, которые поддерживают нулевые значения, обязаны переопределить эту реализацию по умолчанию.

Параметры:

function - функция, применяемая к каждой записи

Выбрасывает:

UnsupportedOperationException - если операция set не поддерживается итератором набора записей этого отображения.

NullPointerException - если указанная функция равна 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 не может содержать нулевые значения и get() возвращение null однозначно означает, что ключ отсутствует. Реализации, которые поддерживают нулевые значения, должны переопределить эту реализацию по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

NullPointerException - если указанный ключ равен 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;

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

С:

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

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

Указано в:

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

С:

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)

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

Указано в:

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

Параметры:

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

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

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

Возвращает:

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

Исключения:

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

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

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

С:

1.8

© 1993, 2023, 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://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/ConcurrentMap.html