@ThreadSafe
public final class ConcurrentLinkedHashMap<K, V>
extends AbstractMap
implements ConcurrentMap, SerializableA hash table supporting full concurrency of retrievals, adjustable expected concurrency for updates, and a maximum capacity to bound the map by. This implementation differs from ConcurrentHashMap in that it maintains a page replacement algorithm that is used to evict an entry when the map has exceeded its capacity. Unlike the Java Collections Framework, this map does not have a publicly visible constructor and instances are created through a Builder.
An entry is evicted from the map when the weighted capacity exceeds its maximum weighted capacity threshold. A EntryWeigher determines how many units of capacity that an entry consumes. The default weigher assigns each value a weight of 1 to bound the map by the total number of key-value pairs. A map that holds collections may choose to weigh values by the number of elements in the collection and bound the map by the total number of elements that it contains. A change to a value that modifies its weight requires that an update operation is performed on the map.
An EvictionListener may be supplied for notification when an entry is evicted from the map. This listener is invoked on a caller's thread and will not block other threads from operating on the map. An implementation should be aware that the caller's thread will not expect long execution times or failures as a side effect of the listener being notified. Execution safety and a fast turn around time can be achieved by performing the operation asynchronously, such as by submitting a task to an ExecutorService.
The concurrency level determines the number of threads that can concurrently modify the table. Using a significantly higher or lower value than needed can waste space or lead to thread contention, but an estimate within an order of magnitude of the ideal value does not usually have a noticeable impact. Because placement in hash tables is essentially random, the actual concurrency will vary.
This class and its views and iterators implement all of the optional methods of the Map and Iterator interfaces.
Like Hashtable but unlike HashMap, this class does not allow null to be used as a key or value. Unlike LinkedHashMap, this class does not provide predictable iteration order. A snapshot of the keys and entries may be obtained in ascending and descending order of retention.
K - the type of keys maintained by this mapV - the type of mapped values| Modifiers | Name | Description |
|---|---|---|
static class |
ConcurrentLinkedHashMap.Builder |
A builder that creates ConcurrentLinkedHashMap instances. |
| Type Params | Return Type | Name and description |
|---|---|---|
|
public Set<K> |
ascendingKeySet()Returns an unmodifiable snapshot Set view of the keys contained in this map. |
|
public Set<K> |
ascendingKeySetWithLimit(int limit)Returns an unmodifiable snapshot Set view of the keys contained in this map. |
|
public Map<K, V> |
ascendingMap()Returns an unmodifiable snapshot Map view of the mappings contained in this map. |
|
public Map<K, V> |
ascendingMapWithLimit(int limit)Returns an unmodifiable snapshot Map view of the mappings contained in this map. |
|
public long |
capacity()Retrieves the maximum weighted capacity of the map. |
|
public void |
clear()Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.
|
|
public V |
computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)If the specified key is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this map unless null. |
|
public boolean |
containsKey(Object key)Returns true if this map contains a mapping for the specified
key. More formally, returns true if and only if
this map contains a mapping for a key k such that
Objects.equals(key, k). (There can be
at most one such mapping.)
|
|
public boolean |
containsValue(Object value)Returns true if this map maps one or more keys to the
specified value. More formally, returns true if and only if
this map contains at least one mapping to a value v such that
Objects.equals(value, v). This operation
will probably require time linear in the map size for most
implementations of the Map interface.
|
|
public Set<K> |
descendingKeySet()Returns an unmodifiable snapshot Set view of the keys contained in this map. |
|
public Set<K> |
descendingKeySetWithLimit(int limit)Returns an unmodifiable snapshot Set view of the keys contained in this map. |
|
public Map<K, V> |
descendingMap()Returns an unmodifiable snapshot Map view of the mappings contained in this map. |
|
public Map<K, V> |
descendingMapWithLimit(int limit)Returns an unmodifiable snapshot Map view of the mappings contained in this map. |
|
public Set<Entry<K, V>> |
entrySet() |
|
public V |
get(Object key)Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
More formally, if this map contains a mapping from a key
If this map permits null values, then a return value of
|
|
public V |
getQuietly(Object key)Returns the value to which the specified key is mapped, or null
if this map contains no mapping for the key. |
|
public boolean |
isEmpty()Returns true if this map contains no key-value mappings.
|
|
public Set<K> |
keySet()Returns a Set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of
the iteration are undefined. The set supports element removal,
which removes the corresponding mapping from the map, via the
Iterator.remove, Set.remove,
removeAll, retainAll, and clear
operations. It does not support the add or addAll
operations.
|
|
public V |
put(K key, V value)Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)
|
|
public V |
putIfAbsent(K key, V value)If the specified key is not already associated with a value, associates it with the given value. This is equivalent to, for this map:
|
|
public V |
remove(Object key)Removes the mapping for a key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that
Objects.equals(key, k), that mapping
is removed. (The map can contain at most one such mapping.)
Returns the value to which this map previously associated the key,
or If this map permits null values, then a return value of
The map will not contain a mapping for the specified key once the call returns.
|
|
public boolean |
remove(Object key, Object value)Removes the entry for a key only if currently mapped to a given value. This is equivalent to, for this map:
|
|
public V |
replace(K key, V value)Replaces the entry for a key only if currently mapped to some value. This is equivalent to, for this map:
|
|
public boolean |
replace(K key, V oldValue, V newValue)Replaces the entry for a key only if currently mapped to a given value. This is equivalent to, for this map:
|
|
public void |
setCapacity(long capacity)Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size. |
|
public int |
size()Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns
Integer.MAX_VALUE.
|
|
public Collection<V> |
values()Returns a Collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation),
the results of the iteration are undefined. The collection
supports element removal, which removes the corresponding
mapping from the map, via the Iterator.remove,
Collection.remove, removeAll,
retainAll and clear operations. It does not
support the add or addAll operations.
|
|
public long |
weightedSize()Returns the weighted size of this map. |
| Methods inherited from class | Name |
|---|---|
class AbstractMap |
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getClass, getOrDefault, hashCode, isEmpty, keySet, merge, notify, notifyAll, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, toString, values, wait, wait, wait |
Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.
Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.
Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.
Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.
limit - the maximum size of the returned setReturns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.
Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.
Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.
Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.
limit - the maximum size of the returned mapRetrieves the maximum weighted capacity of the map.
Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.
clear operation
is not supported by this mapclear operation
is not supported by this mapentrySet().clear().
Note that this implementation throws an
UnsupportedOperationException if the entrySet
does not support the clear operation.
If the specified key is not already associated with a value,
attempts to compute its value using the given mapping function
and enters it into this map unless null. The entire
method invocation is performed atomically, so the function is
applied at most once per key. Some attempted update operations
on this map by other threads may be blocked while computation
is in progress, so the computation should be short and simple,
and must not attempt to update any other mappings of this map.
key - key with which the specified value is to be associatedmappingFunction - the function to compute a value Returns true if this map contains a mapping for the specified
key. More formally, returns true if and only if
this map contains a mapping for a key k such that
Objects.equals(key, k). (There can be
at most one such mapping.)
true if this map contains a mapping for the specified
key. More formally, returns true if and only if
this map contains a mapping for a key k such that
Objects.equals(key, k). (There can be
at most one such mapping.)true if this map contains a mapping for the specified
key. More formally, returns true if and only if
this map contains a mapping for a key k such that
Objects.equals(key, k). (There can be
at most one such mapping.)key - key whose presence in this map is to be testedkey - key whose presence in this map is to be testedkey - key whose presence in this map is to be testedtrue if this map contains a mapping for the specified
keytrue if this map contains a mapping for the specified
keytrue if this map contains a mapping for the specified
keyentrySet() searching
for an entry with the specified key. If such an entry is found,
true is returned. If the iteration terminates without
finding such an entry, false is returned. Note that this
implementation requires linear time in the size of the map; many
implementations will override this method. Returns true if this map maps one or more keys to the
specified value. More formally, returns true if and only if
this map contains at least one mapping to a value v such that
Objects.equals(value, v). This operation
will probably require time linear in the map size for most
implementations of the Map interface.
true if this map maps one or more keys to the
specified value. More formally, returns true if and only if
this map contains at least one mapping to a value v such that
Objects.equals(value, v). This operation
will probably require time linear in the map size for most
implementations of the Map interface.true if this map maps one or more keys to the
specified value. More formally, returns true if and only if
this map contains at least one mapping to a value v such that
Objects.equals(value, v). This operation
will probably require time linear in the map size for most
implementations of the Map interface.value - value whose presence in this map is to be testedvalue - value whose presence in this map is to be testedvalue - value whose presence in this map is to be testedtrue if this map maps one or more keys to the
specified valuetrue if this map maps one or more keys to the
specified valuetrue if this map maps one or more keys to the
specified valueentrySet() searching
for an entry with the specified value. If such an entry is found,
true is returned. If the iteration terminates without
finding such an entry, false is returned. Note that this
implementation requires linear time in the size of the map.Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.
Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.
Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.
Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.
limit - the maximum size of the returned setReturns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.
Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.
Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.
Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.
limit - the maximum size of the returned map
Returns the value to which the specified key is mapped,
or null if this map contains no mapping for the key.
More formally, if this map contains a mapping from a key
k to a value v such that
Objects.equals(key, k),
then this method returns v; otherwise
it returns null. (There can be at most one such mapping.)
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contains no mapping for the key; it's also possible that the map
explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
null if this map contains no mapping for the key.
More formally, if this map contains a mapping from a key
k to a value v such that
Objects.equals(key, k),
then this method returns v; otherwise
it returns null. (There can be at most one such mapping.)
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contains no mapping for the key; it's also possible that the map
explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
null if this map contains no mapping for the key.
More formally, if this map contains a mapping from a key
k to a value v such that
Objects.equals(key, k),
then this method returns v; otherwise
it returns null. (There can be at most one such mapping.)
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contains no mapping for the key; it's also possible that the map
explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
key - the key whose associated value is to be returnedkey - the key whose associated value is to be returnedkey - the key whose associated value is to be returnednull if this map contains no mapping for the keynull if this map contains no mapping for the keynull if this map contains no mapping for the keyentrySet() searching
for an entry with the specified key. If such an entry is found,
the entry's value is returned. If the iteration terminates without
finding such an entry, null is returned. Note that this
implementation requires linear time in the size of the map; many
implementations will override this method. Returns the value to which the specified key is mapped, or null
if this map contains no mapping for the key. This method differs from
get(Object) in that it does not record the operation with the
page replacement policy.
key - the key whose associated value is to be returnednull if this map contains no mapping for the key Returns true if this map contains no key-value mappings.
true if this map contains no key-value mappingssize() == 0. Returns a Set view of the keys contained in this map.
The set is backed by the map, so changes to the map are
reflected in the set, and vice-versa. If the map is modified
while an iteration over the set is in progress (except through
the iterator's own remove operation), the results of
the iteration are undefined. The set supports element removal,
which removes the corresponding mapping from the map, via the
Iterator.remove, Set.remove,
removeAll, retainAll, and clear
operations. It does not support the add or addAll
operations.
entrySet() iterator. The size method
delegates to this map's size method and the
contains method delegates to this map's
containsKey method.
The set is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same set.
Associates the specified value with the specified key in this map
(optional operation). If the map previously contained a mapping for
the key, the old value is replaced by the specified value. (A map
m is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)
put operation
is not supported by this mapm is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)put operation
is not supported by this mapm is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)put operation
is not supported by this mapm is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)put operation
is not supported by this mapm is said to contain a mapping for a key k if and only
if containsKey(Object) m.containsKey(k) would return
true.)put operation
is not supported by this mapkey - key with which the specified value is to be associatedvalue - value to be associated with the specified keykey - key with which the specified value is to be associatedvalue - value to be associated with the specified keykey - key with which the specified value is to be associatedvalue - value to be associated with the specified keykey - key with which the specified value is to be associatedvalue - value to be associated with the specified keykey - key with which the specified value is to be associatedvalue - value to be associated with the specified keykey, or
null if there was no mapping for key.
(A null return can also indicate that the map
previously associated null with key,
if the implementation supports null values.)key, or
null if there was no mapping for key.
(A null return can also indicate that the map
previously associated null with key,
if the implementation supports null values.)key, or
null if there was no mapping for key.
(A null return can also indicate that the map
previously associated null with key,
if the implementation supports null values.)key, or
null if there was no mapping for key.
(A null return can also indicate that the map
previously associated null with key,
if the implementation supports null values.)key, or
null if there was no mapping for key.
(A null return can also indicate that the map
previously associated null with key,
if the implementation supports null values.)UnsupportedOperationException. 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);put operation
is not supported by this mapMap.key - key with which the specified value is to be associatedvalue - value to be associated with the specified keynull 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.) Removes the mapping for a key from this map if it is present
(optional operation). More formally, if this map contains a mapping
from key k to value v such that
Objects.equals(key, k), that mapping
is removed. (The map can contain at most one such mapping.)
Returns the value to which this map previously associated the key,
or null if the map contained no mapping for the key.
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contained no mapping for the key; it's also possible that the map
explicitly mapped the key to null.
The map will not contain a mapping for the specified key once the call returns.
remove operation
is not supported by this mapk to value v such that
Objects.equals(key, k), that mapping
is removed. (The map can contain at most one such mapping.)
Returns the value to which this map previously associated the key,
or null if the map contained no mapping for the key.
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contained no mapping for the key; it's also possible that the map
explicitly mapped the key to null.
The map will not contain a mapping for the specified key once the call returns.
remove operation
is not supported by this mapk to value v such that
Objects.equals(key, k), that mapping
is removed. (The map can contain at most one such mapping.)
Returns the value to which this map previously associated the key,
or null if the map contained no mapping for the key.
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contained no mapping for the key; it's also possible that the map
explicitly mapped the key to null.
The map will not contain a mapping for the specified key once the call returns.
remove operation
is not supported by this mapk to value v such that
Objects.equals(key, k), that mapping
is removed. (The map can contain at most one such mapping.)
Returns the value to which this map previously associated the key,
or null if the map contained no mapping for the key.
If this map permits null values, then a return value of
null does not necessarily indicate that the map
contained no mapping for the key; it's also possible that the map
explicitly mapped the key to null.
The map will not contain a mapping for the specified key once the call returns.
remove operation
is not supported by this mapkey - key whose mapping is to be removed from the mapkey - key whose mapping is to be removed from the mapkey - key whose mapping is to be removed from the mapkey - key whose mapping is to be removed from the mapkey, or
null if there was no mapping for key.key, or
null if there was no mapping for key.key, or
null if there was no mapping for key.key, or
null if there was no mapping for key.entrySet() searching for an
entry with the specified key. If such an entry is found, its value is
obtained with its getValue operation, the entry is removed
from the collection (and the backing map) with the iterator's
remove operation, and the saved value is returned. If the
iteration terminates without finding such an entry, null is
returned. Note that this implementation requires linear time in the
size of the map; many implementations will override this method.
Note that this implementation throws an
UnsupportedOperationException if the entrySet
iterator does not support the remove method and this map
contains a mapping for the specified key.
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;
}}remove operation
is not supported by this mapMap.key - key with which the specified value is associatedvalue - value expected to be associated with the specified keytrue if the value was removed 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;put operation
is not supported by this mapMap.key - key with which the specified value is associatedvalue - value to be associated with the specified keynull 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.) 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;
}}put operation
is not supported by this mapMap.key - key with which the specified value is associatedoldValue - value expected to be associated with the specified keynewValue - value to be associated with the specified keytrue if the value was replacedSets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
capacity - the maximum weighted capacity of the map Returns the number of key-value mappings in this map. If the
map contains more than Integer.MAX_VALUE elements, returns
Integer.MAX_VALUE.
entrySet().size(). Returns a Collection view of the values contained in this map.
The collection is backed by the map, so changes to the map are
reflected in the collection, and vice-versa. If the map is
modified while an iteration over the collection is in progress
(except through the iterator's own remove operation),
the results of the iteration are undefined. The collection
supports element removal, which removes the corresponding
mapping from the map, via the Iterator.remove,
Collection.remove, removeAll,
retainAll and clear operations. It does not
support the add or addAll operations.
entrySet() iterator.
The size method delegates to this map's size
method and the contains method delegates to this map's
containsValue method.
The collection is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same collection.
Returns the weighted size of this map.