Top Description Methods
java.util.concurrent

public Interface ConcurrentMap<K, V>

extends Map<K, V>
Known Direct Subinterfaces
java.util.concurrent.ConcurrentNavigableMap
Known Direct Implementers
java.util.concurrent.ConcurrentHashMap
Type Parameters
<K>
the type of keys maintained by this map
<V>
the type of mapped values
Imports
java.util.Map, .Objects, java.util.function.BiConsumer, .BiFunction, .Function
A Map providing thread safety and atomicity guarantees.

To maintain the specified guarantees, default implementations of methods including putIfAbsent inherited from Map must be overridden by implementations of this interface. Similarly, implementations of the collections returned by methods keySet, values, and entrySet must override methods such as removeIf when necessary to preserve atomicity guarantees.

Memory consistency effects: As with other concurrent collections, actions in a thread prior to placing an object into a ConcurrentMap as a key or value happen-before actions subsequent to the access or removal of that object from the ConcurrentMap in another thread.

This interface is a member of the Java Collections Framework.

Author
Doug Lea
Since
1.5

Method Summary

Modifier and TypeMethod and Description
public default V
compute(K
key with which the specified value is to be associated
key, BiFunction<? super K, ? super V, ? extends V>
the remapping function to compute a value
remappingFunction)

Overrides default java.util.Map.compute.

Attempts to compute a mapping for the specified key and its current mapped value, or null if there is no current mapping (optional operation).

public default V
computeIfAbsent(K
key with which the specified value is to be associated
key, Function<? super K, ? extends V>
the mapping function to compute a value
mappingFunction)

Overrides default java.util.Map.computeIfAbsent.

If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null (optional operation).

public default V
computeIfPresent(K
key with which the specified value is to be associated
key, BiFunction<? super K, ? super V, ? extends V>
the remapping function to compute a value
remappingFunction)

Overrides default java.util.Map.computeIfPresent.

If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value (optional operation).

public default void
forEach(BiConsumer<? super K, ? super V>
The action to be performed for each entry
action)

Overrides default java.util.Map.forEach.

Performs the given action for each entry in this map until all entries have been processed or the action throws an exception.

public default V
getOrDefault(Object
the key whose associated value is to be returned
key, V
the default mapping of the key
defaultValue)

Overrides default java.util.Map.getOrDefault.

Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.

public default V
merge(K
key with which the resulting value is to be associated
key, V
the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the key
value, BiFunction<? super V, ? super V, ? extends V>
the remapping function to recompute a value if present
remappingFunction)

Overrides default java.util.Map.merge.

If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value (optional operation).

public V

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)
putIfAbsent(K
key with which the specified value is to be associated
key, V
value to be associated with the specified key
value)

Redeclares as abstract: java.util.Map.putIfAbsent.

If the specified key is not already associated with a value, associates it with the given value.

public boolean

Returns:

true if the value was removed
remove(Object
key with which the specified value is associated
key, Object
value expected to be associated with the specified key
value)

Redeclares as abstract: java.util.Map.remove.

Removes the entry for a key only if currently mapped to a given value.

public boolean

Returns:

true if the value was replaced
replace(K
key with which the specified value is associated
key, V
value expected to be associated with the specified key
oldValue, V
value to be associated with the specified key
newValue)

Redeclares as abstract: java.util.Map.replace.

Replaces the entry for a key only if currently mapped to a given value.

public V

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)
replace(K
key with which the specified value is associated
key, V
value to be associated with the specified key
value)

Redeclares as abstract: java.util.Map.replace.

Replaces the entry for a key only if currently mapped to some value.

public default void
replaceAll(BiFunction<? super K, ? super V, ? extends V>
the function to apply to each entry
function)

Overrides default java.util.Map.replaceAll.

Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception (optional operation).

Inherited from java.util.Map:
clearcontainsKeycontainsValuecopyOfentryentrySetequalsgethashCodeisEmptykeySetofofofofofofofofofofofofEntriesputputAllremovesizevalues

Method Detail

computeback to summary
public default V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Overrides default java.util.Map.compute.

Doc from java.util.Map.compute.

Attempts to compute a mapping for the specified key and its current mapped value, or null if there is no current mapping (optional operation). For example, to either create or append a String msg to a value mapping: 

 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))
(Method merge() is often simpler to use for such purposes.)

If the remapping function returns null, the mapping is removed (or remains absent if initially absent). If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

The remapping function should not modify this map during computation.

Implementation Specification

The default implementation is equivalent to performing the following steps for this 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;
  }
}
When multiple threads attempt updates, map operations and the remapping function may be called multiple times.

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
key:K

key with which the specified value is to be associated

remappingFunction:BiFunction<? super K, ? super V, ? extends V>

the remapping function to compute a value

Returns:V

the new value associated with the specified key, or null if none

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the compute operation is not supported by this map (optional)
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map (optional)
NullPointerException:
if the specified key is null and this map does not support null keys, or the remappingFunction is null
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map (optional)
Since
1.8
computeIfAbsentback to summary
public default V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)

Overrides default java.util.Map.computeIfAbsent.

Doc from java.util.Map.computeIfAbsent.

If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null (optional operation).

If the mapping function returns null, no mapping is recorded. If the mapping function itself throws an (unchecked) exception, the exception is rethrown, and no mapping is recorded. The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in: 

 map.computeIfAbsent(key, k -> new Value(f(k)));

Or to implement a multi-value map, Map<K,Collection<V>>, supporting multiple values per key: 

 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);

The mapping function should not modify this map during computation.

Implementation Specification

The default implementation is equivalent to the following steps for this map: 

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

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
key:K

key with which the specified value is to be associated

mappingFunction:Function<? super K, ? extends V>

the mapping function to compute a value

Returns:V

the current (existing or computed) value associated with the specified key, or null if the computed value is null

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the computeIfAbsent operation is not supported by this map (optional)
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map (optional)
NullPointerException:
if the specified key is null and this map does not support null keys, or the mappingFunction is null
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map (optional)
Since
1.8
computeIfPresentback to summary
public default V computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Overrides default java.util.Map.computeIfPresent.

Doc from java.util.Map.computeIfPresent.

If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value (optional operation).

If the remapping function returns null, the mapping is removed. If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

The remapping function should not modify this map during computation.

Implementation Specification

The default implementation is equivalent to performing the following steps for this 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;
When multiple threads attempt updates, map operations and the remapping function may be called multiple times.

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
key:K

key with which the specified value is to be associated

remappingFunction:BiFunction<? super K, ? super V, ? extends V>

the remapping function to compute a value

Returns:V

the new value associated with the specified key, or null if none

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the computeIfPresent operation is not supported by this map (optional)
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map (optional)
NullPointerException:
if the specified key is null and this map does not support null keys, or the remappingFunction is null
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map (optional)
Since
1.8
forEachback to summary
public default void forEach(BiConsumer<? super K, ? super V> action)

Overrides default java.util.Map.forEach.

Doc from java.util.Map.forEach.

Performs the given action for each entry in this map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller.

Implementation Specification

The default implementation is equivalent to, for this map: 

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

Implementation Note

The default implementation assumes that IllegalStateException thrown by getKey() or getValue() indicates that the entry has been removed and cannot be processed. Operation continues for subsequent entries.

Parameters
action:BiConsumer<? super K, ? super V>

The action to be performed for each entry

Annotations
@Override
Exceptions
NullPointerException:
if the specified action is null
Since
1.8
getOrDefaultback to summary
public default V getOrDefault(Object key, V defaultValue)

Overrides default java.util.Map.getOrDefault.

Doc from java.util.Map.getOrDefault.

Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.

Implementation Note

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
key:Object

the key whose associated value is to be returned

defaultValue:V

the default mapping of the key

Returns:V

the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key

Annotations
@Override
Exceptions
ClassCastException:
if the key is of an inappropriate type for this map (optional)
NullPointerException:
if the specified key is null and this map does not permit null keys (optional)
Since
1.8
mergeback to summary
public default V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)

Overrides default java.util.Map.merge.

Doc from java.util.Map.merge.

If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value (optional operation). Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is null. This method may be of use when combining multiple mapped values for a key. For example, to either create or append a String msg to a value mapping: 

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

If the remapping function returns null, the mapping is removed. If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

The remapping function should not modify this map during computation.

Implementation Specification

The default implementation is equivalent to performing the following steps for this 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;
  }
}
When multiple threads attempt updates, map operations and the remapping function may be called multiple times.

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
key:K

key with which the resulting value is to be associated

value:V

the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the key

remappingFunction:BiFunction<? super V, ? super V, ? extends V>

the remapping function to recompute a value if present

Returns:V

the new value associated with the specified key, or null if no value is associated with the key

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the merge operation is not supported by this map (optional)
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map (optional)
NullPointerException:
if the specified key is null and this map does not support null keys or the value or remappingFunction is null
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map (optional)
Since
1.8
putIfAbsentback to summary
public V putIfAbsent(K key, V value)

Redeclares as abstract: java.util.Map.putIfAbsent.

If the specified key is not already associated with a value, associates it with the given value. This is equivalent to, for this map: 

 if (!map.containsKey(key))
  return map.put(key, value);
else
  return map.get(key);
except that the action is performed atomically.

Implementation Note

This implementation intentionally re-abstracts the inappropriate default provided in Map.

Parameters
key:K

key with which the specified value is to be associated

value:V

value to be associated with the specified key

Returns:V

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)

Exceptions
UnsupportedOperationException:
if the put operation is not supported by this map
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map
NullPointerException:
if the specified key or value is null, and this map does not permit null keys or values
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map
removeback to summary
public boolean remove(Object key, Object value)

Redeclares as abstract: java.util.Map.remove.

Removes the entry for a key only if currently mapped to a given value. This is equivalent to, for this map: 

 if (map.containsKey(key)
    && Objects.equals(map.get(key), value)) {
  map.remove(key);
  return true;
} else {
  return false;
}
except that the action is performed atomically.

Implementation Note

This implementation intentionally re-abstracts the inappropriate default provided in Map.

Parameters
key:Object

key with which the specified value is associated

value:Object

value expected to be associated with the specified key

Returns:boolean

true if the value was removed

Exceptions
UnsupportedOperationException:
if the remove operation is not supported by this map
ClassCastException:
if the key or value is of an inappropriate type for this map (optional)
NullPointerException:
if the specified key or value is null, and this map does not permit null keys or values (optional)
replaceback to summary
public boolean replace(K key, V oldValue, V newValue)

Redeclares as abstract: java.util.Map.replace.

Replaces the entry for a key only if currently mapped to a given value. This is equivalent to, for this map: 

 if (map.containsKey(key)
    && Objects.equals(map.get(key), oldValue)) {
  map.put(key, newValue);
  return true;
} else {
  return false;
}
except that the action is performed atomically.

Implementation Note

This implementation intentionally re-abstracts the inappropriate default provided in Map.

Parameters
key:K

key with which the specified value is associated

oldValue:V

value expected to be associated with the specified key

newValue:V

value to be associated with the specified key

Returns:boolean

true if the value was replaced

Exceptions
UnsupportedOperationException:
if the put operation is not supported by this map
ClassCastException:
if the class of a specified key or value prevents it from being stored in this map
NullPointerException:
if a specified key or value is null, and this map does not permit null keys or values
IllegalArgumentException:
if some property of a specified key or value prevents it from being stored in this map
replaceback to summary
public V replace(K key, V value)

Redeclares as abstract: java.util.Map.replace.

Replaces the entry for a key only if currently mapped to some value. This is equivalent to, for this map: 

 if (map.containsKey(key))
  return map.put(key, value);
else
  return null;
except that the action is performed atomically.

Implementation Note

This implementation intentionally re-abstracts the inappropriate default provided in Map.

Parameters
key:K

key with which the specified value is associated

value:V

value to be associated with the specified key

Returns:V

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)

Exceptions
UnsupportedOperationException:
if the put operation is not supported by this map
ClassCastException:
if the class of the specified key or value prevents it from being stored in this map
NullPointerException:
if the specified key or value is null, and this map does not permit null keys or values
IllegalArgumentException:
if some property of the specified key or value prevents it from being stored in this map
replaceAllback to summary
public default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)

Overrides default java.util.Map.replaceAll.

Doc from java.util.Map.replaceAll.

Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception (optional operation). Exceptions thrown by the function are relayed to the caller.

Implementation Specification

The default implementation is equivalent to, for this 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)));
}
The default implementation may retry these steps when multiple threads attempt updates including potentially calling the function repeatedly for a given key.

This implementation assumes that the ConcurrentMap cannot contain null values and get() returning null unambiguously means the key is absent. Implementations which support null values must override this default implementation.

Parameters
function:BiFunction<? super K, ? super V, ? extends V>

the function to apply to each entry

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the replaceAll operation is not supported by this map (optional)
NullPointerException:
if the specified function is null, or if a replacement value is null and this map does not permit null values (optional)
ClassCastException:
if the class of a replacement value prevents it from being stored in this map (optional)
IllegalArgumentException:
if some property of a replacement value prevents it from being stored in this map (optional)
Since
1.8