java.util.concurrent.ConcurrentHashMap<K, V>
A hash table supporting full concurrency of retrievals and
adjustable expected concurrency for updates. This class obeys the
same functional specification as Hashtable, and
includes versions of methods corresponding to each method of
Hashtable. However, even though all operations are
thread-safe, retrieval operations do not entail locking,
and there is not any support for locking the entire table
in a way that prevents all access. This class is fully
interoperable with Hashtable in programs that rely on its
thread safety but not on its synchronization details.
Retrieval operations (including get) generally do not
block, so may overlap with update operations (including
put and remove). Retrievals reflect the results
of the most recently completed update operations holding
upon their onset. For aggregate operations such as putAll
and clear, concurrent retrievals may reflect insertion or
removal of only some entries. Similarly, Iterators and
Enumerations return elements reflecting the state of the hash table
at some point at or since the creation of the iterator/enumeration.
They do not throw
ConcurrentModificationException. However, iterators are
designed to be used by only one thread at a time.
The allowed concurrency among update operations is guided by
the optional concurrencyLevel constructor argument
(default 16), which is used as a hint for internal sizing. The
table is internally partitioned to try to permit the indicated
number of concurrent updates without contention. Because placement
in hash tables is essentially random, the actual concurrency will
vary. Ideally, you should choose a value to accommodate as many
threads as will ever concurrently modify the table. Using a
significantly higher value than you need can waste space and time,
and a significantly lower value can lead to thread contention. But
overestimates and underestimates within an order of magnitude do
not usually have much noticeable impact. A value of one is
appropriate when it is known that only one thread will modify
and all others will only read.
This class implements 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.
Summary
Public Constructors
Public Methods
clear,
clone,
containsKey,
containsValue,
entrySet,
equals,
get,
hashCode,
isEmpty,
keySet,
put,
putAll,
remove,
size,
toString,
values
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Methods inherited
from interface
java.util.Map
clear,
containsKey,
containsValue,
entrySet,
equals,
get,
hashCode,
isEmpty,
keySet,
put,
putAll,
remove,
size,
values
Details
Public Constructors
public
ConcurrentHashMap(int initialCapacity, float loadFactor, int concurrencyLevel)
Creates a new, empty map with the specified initial
capacity and the specified load factor.
Parameters
initialCapacity
| the initial capacity. The implementation
performs internal sizing to accommodate this many elements. |
loadFactor
| the load factor threshold, used to control resizing. |
concurrencyLevel
| the estimated number of concurrently
updating threads. The implementation performs internal sizing
to try to accommodate this many threads. |
public
ConcurrentHashMap(int initialCapacity)
Creates a new, empty map with the specified initial
capacity, and with default load factor and concurrencyLevel.
Parameters
initialCapacity
| The implementation performs internal
sizing to accommodate this many elements. |
public
ConcurrentHashMap()
Creates a new, empty map with a default initial capacity,
load factor, and concurrencyLevel.
public
ConcurrentHashMap(Map<? extends K, ? extends V> t)
Creates a new map with the same mappings as the given map. The
map is created with a capacity of twice the number of mappings in
the given map or 11 (whichever is greater), and a default load factor.
Public Methods
public
void
clear()
Removes all mappings from this map.
public
boolean
contains(Object value)
Legacy method testing if some key maps into the specified value
in this table. This method is identical in functionality to
containsValue(Object), and exists solely to ensure
full compatibility with class
Hashtable,
which supported this method prior to introduction of the
Java Collections framework.
Parameters
value
| a value to search for. |
Returns
- true if and only if some key maps to the
value argument in this table as
determined by the equals method;
false otherwise.
public
boolean
containsKey(Object key)
Tests if the specified object is a key in this table.
Returns
- true if and only if the specified object
is a key in this table, as determined by the
equals method; false otherwise.
public
boolean
containsValue(Object value)
Returns
true if this map maps one or more keys to the
specified value. Note: This method requires a full internal
traversal of the hash table, and so is much slower than
method
containsKey.
Parameters
value
| value whose presence in this map is to be tested. |
Returns
- true if this map maps one or more keys to the
specified value.
Returns an enumeration of the values in this table.
Returns
- an enumeration of the values in this table.
public
Set<Entry<K, V>>
entrySet()
Returns a collection view of the mappings contained in this map. Each
element in the returned collection is a
Map.Entry. The
collection is backed by the map, so changes to the map are reflected in
the collection, and vice-versa. 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.
The returned
iterator is a "weakly consistent" iterator that
will never throw
ConcurrentModificationException,
and guarantees to traverse elements as they existed upon
construction of the iterator, and may (but is not guaranteed to)
reflect any modifications subsequent to construction.
Returns
- a collection view of the mappings contained in this map.
public
V
get(Object key)
Returns the value to which the specified key is mapped in this table.
Returns
- the value to which the key is mapped in this table;
null if the key is not mapped to any value in
this table.
public
boolean
isEmpty()
Returns if this Map has no elements, a size of zero.
Returns
- true if this Map has no elements, false otherwise
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. The set supports element removal, which removes the
corresponding mapping from this map, via the
Iterator.remove,
Set.remove,
removeAll,
retainAll, and
clear operations. It does not support the
add or
addAll operations.
The returned
iterator is a "weakly consistent" iterator that
will never throw
ConcurrentModificationException,
and guarantees to traverse elements as they existed upon
construction of the iterator, and may (but is not guaranteed to)
reflect any modifications subsequent to construction.
Returns
- a set view of the keys contained in this map.
Returns an enumeration of the keys in this table.
Returns
- an enumeration of the keys in this table.
public
V
put(K key, V value)
Maps the specified
key to the specified
value in this table. Neither the key nor the
value can be
null.
The value can be retrieved by calling the get method
with a key that is equal to the original key.
Parameters
key
| the table key. |
value
| the value. |
Returns
- the previous value of the specified key in this table,
or null if it did not have one.
public
void
putAll(Map<? extends K, ? extends V> t)
Copies all of the mappings from the specified map to this one.
These mappings replace any mappings that this map had for any of the
keys currently in the specified Map.
Parameters
t
| Mappings to be stored in this map.
|
public
V
putIfAbsent(K key, V value)
If the specified key is not already associated
with a value, associate it with the given value.
This is equivalent to
if (!map.containsKey(key))
return map.put(key, value);
else
return map.get(key);
Except that the action is performed atomically.
Parameters
key
| key with which the specified value is to be associated. |
value
| value to be associated with the specified key. |
Returns
- previous value associated with specified key, or null
if there was no mapping for key. A null return can
also indicate that the map previously associated null
with the specified key, if the implementation supports
null values.
public
boolean
remove(Object key, Object value)
Remove entry for key only if currently mapped to given value.
Acts as
if (map.get(key).equals(value)) {
map.remove(key);
return true;
} else return false;
except that the action is performed atomically.
Parameters
key
| key with which the specified value is associated. |
value
| value associated with the specified key. |
Returns
- true if the value was removed
public
V
remove(Object key)
Removes the key (and its corresponding value) from this
table. This method does nothing if the key is not in the table.
Parameters
key
| the key that needs to be removed. |
Returns
- the value to which the key had been mapped in this table,
or null if the key did not have a mapping.
public
boolean
replace(K key, V oldValue, V newValue)
Replace entry for key only if currently mapped to given value.
Acts as
if (map.get(key).equals(oldValue)) {
map.put(key, newValue);
return true;
} else return false;
except that the action is performed atomically.
Parameters
key
| key with which the specified value is associated. |
oldValue
| value expected to be associated with the specified key. |
newValue
| value to be associated with the specified key. |
Returns
- true if the value was replaced
public
V
replace(K key, V value)
Replace entry for key only if currently mapped to some value.
Acts as
if ((map.containsKey(key)) {
return map.put(key, value);
} else return null;
except that the action is performed atomically.
Parameters
key
| key with which the specified value is associated. |
value
| value to be associated with the specified key. |
Returns
- previous value associated with specified key, or null
if there was no mapping for key.
public
int
size()
Returns the number of elements in this Map.
Returns
- the number of elements in this Map
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. The collection supports element
removal, which removes the corresponding mapping from this map, via the
Iterator.remove,
Collection.remove,
removeAll,
retainAll, and
clear operations.
It does not support the
add or
addAll operations.
The returned
iterator is a "weakly consistent" iterator that
will never throw
ConcurrentModificationException,
and guarantees to traverse elements as they existed upon
construction of the iterator, and may (but is not guaranteed to)
reflect any modifications subsequent to construction.
Returns
- a collection view of the values contained in this map.