Интерфейс 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 не может содержать 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-ключей или 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-ключей или 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-ключей или 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-ключей или 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 не может содержать нулевые значения и 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, 2021, 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/17/docs/api/java.base/java/util/concurrent/ConcurrentMap.html