Class CustomConcurrentHashMap<K,V>
- Type Parameters:
K
- the type of keys maintained by this mapV
- the type of mapped values
- All Implemented Interfaces:
Serializable
,ConcurrentMap<K,
,V> Map<K,
V>
java.util.ConcurrentMap
supporting user-defined
equivalence comparisons, soft, weak, or strong keys and values, and
user-supplied computational methods for setting and updating
values. In particular: - Identity-based, Equality-based or User-definable
CustomConcurrentHashMap.Equivalence
-based comparisons controlling membership. - Soft, weak or strong (regular) keys and values.
- User-definable
MappingFunctions
that may be used in methodcomputeIfAbsent(K, extra166y.CustomConcurrentHashMap.MappingFunction<? super K, ? extends V>)
to atomically establish a computed value, along withRemappingFunctions
that can be used in methodcompute(K, extra166y.CustomConcurrentHashMap.RemappingFunction<? super K, V>)
to atomically replace values. - Factory methods returning specialized forms for int keys and/or values, that may be more space-efficient
identityMap = new CustomConcurrentHashMap<Person,Salary>
(STRONG, IDENTITY, STRONG, EQUALS, 0);
weakKeyMap = new CustomConcurrentHashMap<Person,Salary>
(WEAK, IDENTITY, STRONG, EQUALS, 0);
.weakKeys());
byNameMap = new CustomConcurrentHashMap<Person,Salary>
(STRONG,
new Equivalence<Person>() {
public boolean equal(Person k, Object x) {
return x instanceof Person && k.name.equals(((Person)x).name);
}
public int hash(Object x) {
return (x instanceof Person) ? ((Person)x).name.hashCode() : 0;
}
},
STRONG, EQUALS, 0);
The first usage above provides a replacement for IdentityHashMap
, and the second a replacement for WeakHashMap
, adding concurrency, asynchronous cleanup,
and identity-based equality for keys. The third usage
illustrates a map with a custom Equivalence that looks only at the
name field of a (fictional) Person class.
This class also includes nested class CustomConcurrentHashMap.KeySet
that provides space-efficient Set views of maps, also supporting
method intern
, which may be of use in canonicalizing
elements.
When used with (Weak or Soft) Reference keys and/or values,
elements that have asynchronously become null
are
treated as absent from the map and (eventually) removed from maps
via a background thread common across all maps. Because of the
potential for asynchronous clearing of References, methods such as
containsValue
have weaker guarantees than you might
expect even in the absence of other explicitly concurrent
operations. For example containsValue(value)
may
return true even if value
is no longer available upon
return from the method.
When Equivalences other than equality are used, the returned
collections may violate the specifications of Map and/or
Set interfaces, which mandate the use of the
equals method when comparing objects. The methods of this
class otherwise have properties similar to those of java.util.ConcurrentHashMap
under its default settings. To
adaptively maintain semantics and performance under varying
conditions, this class does not support load factor or
concurrency level parameters. This class does not permit null keys
or values. This class is serializable; however, serializing a map
that uses soft or weak references can give unpredictable results.
This class supports all optional operations of the
ConcurrentMap
interface. It supports have weakly consistent
iteration: an iterator over one of the map's view collections
may reflect some, all or none of the changes made to the collection
after the iterator was created.
This class is a member of the Java Collections Framework.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
An object performing equality comparisons, along with a hash function consistent with this comparison.static class
A hash-based set with properties identical to those ofCollections.newSetFromMap
applied to aCustomConcurrentHashMap
, but possibly more space-efficient.static interface
A function computing a mapping from the given key to a value, ornull
if there is no mapping.static interface
A function computing a new mapping from the given key and its current value to a new value, ornull
if there is no mappingstatic enum
The strength of keys and values that may be held by maps.Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K extends Object,
V extends Object>, AbstractMap.SimpleImmutableEntry<K extends Object, V extends Object> -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final CustomConcurrentHashMap.Equivalence<Object>
An Equivalence object performingObject.equals(java.lang.Object)
based comparisons and usingObject.hashCode()
hashingstatic final CustomConcurrentHashMap.Equivalence<Object>
An Equivalence object performing identity-based comparisons and usingSystem.identityHashCode(java.lang.Object)
for hashingstatic final CustomConcurrentHashMap.Strength
The strength of soft referencesstatic final CustomConcurrentHashMap.Strength
The strength of ordinary referencesstatic final CustomConcurrentHashMap.Strength
The strength of weak references -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new CustomConcurrentHashMap with strong keys and values, and equality-based equivalence.CustomConcurrentHashMap
(CustomConcurrentHashMap.Strength keyStrength, CustomConcurrentHashMap.Equivalence<? super K> keyEquivalence, CustomConcurrentHashMap.Strength valueStrength, CustomConcurrentHashMap.Equivalence<? super V> valueEquivalence, int expectedSize) Creates a new CustomConcurrentHashMap with the given parameters -
Method Summary
Modifier and TypeMethodDescriptionfinal void
clear()
Removes all of the mappings from this map.compute
(K key, CustomConcurrentHashMap.RemappingFunction<? super K, V> remappingFunction) Updates the mapping for the given key with the result of the given remappingFunction.computeIfAbsent
(K key, CustomConcurrentHashMap.MappingFunction<? super K, ? extends V> mappingFunction) If the specified key is not already associated with a value, computes its value using the given mappingFunction, and if non-null, enters it into the map.boolean
containsKey
(Object key) Returns true if this map contains a key equivalent to the given key with respect to this map's key Equivalence.final boolean
containsValue
(Object value) Returns true if this map maps one or more keys to a value equivalent to the given value with respect to this map's value Equivalence.entrySet()
Returns aSet
view of the mappings contained in this map.boolean
Compares the specified object with this map for equality.Returns the value associated with a key equivalent to the given key with respect to this map's key Equivalence, ornull
if no such mapping existsint
hashCode()
Returns the sum of the hash codes of each entry in this map's entrySet() view, which in turn are the hash codes computed using key and value Equivalences for this Map.final boolean
isEmpty()
Returns true if this map contains no key-value mappings.keySet()
Returns aSet
view of the keys contained in this map.static CustomConcurrentHashMap<Integer,
Integer> newIntKeyIntValueMap
(int expectedSize) Returns a new map using Integer keys and valuesstatic <ValueType>
CustomConcurrentHashMap<Integer,ValueType> newIntKeyMap
(CustomConcurrentHashMap.Strength valueStrength, CustomConcurrentHashMap.Equivalence<? super ValueType> valueEquivalence, int expectedSize) Returns a new map using Integer keys and the given value parametersstatic <KeyType> CustomConcurrentHashMap<KeyType,
Integer> newIntValueMap
(CustomConcurrentHashMap.Strength keyStrength, CustomConcurrentHashMap.Equivalence<? super KeyType> keyEquivalence, int expectedSize) Returns a new map using the given key parameters and Integer valuesMaps the specified key to the specified value in this map.void
Copies all of the mappings from the specified map to this one.putIfAbsent
(K key, V value) Removes the mapping for the specified key.boolean
boolean
final int
size()
Returns the number of key-value mappings in this map.values()
Returns aCollection
view of the values contained in this map.Methods inherited from class java.util.AbstractMap
clone, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.concurrent.ConcurrentMap
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll
-
Field Details
-
STRONG
The strength of ordinary references -
WEAK
The strength of weak references -
SOFT
The strength of soft references -
IDENTITY
An Equivalence object performing identity-based comparisons and usingSystem.identityHashCode(java.lang.Object)
for hashing -
EQUALS
An Equivalence object performingObject.equals(java.lang.Object)
based comparisons and usingObject.hashCode()
hashing
-
-
Constructor Details
-
CustomConcurrentHashMap
public CustomConcurrentHashMap(CustomConcurrentHashMap.Strength keyStrength, CustomConcurrentHashMap.Equivalence<? super K> keyEquivalence, CustomConcurrentHashMap.Strength valueStrength, CustomConcurrentHashMap.Equivalence<? super V> valueEquivalence, int expectedSize) Creates a new CustomConcurrentHashMap with the given parameters- Parameters:
keyStrength
- the strength for keyskeyEquivalence
- the Equivalence to use for keysvalueStrength
- the strength for valuesvalueEquivalence
- the Equivalence to use for valuesexpectedSize
- an estimate of the number of elements that will be held in the map. If no estimate is known, zero is an acceptable value.
-
CustomConcurrentHashMap
public CustomConcurrentHashMap()Creates a new CustomConcurrentHashMap with strong keys and values, and equality-based equivalence.
-
-
Method Details
-
newIntKeyMap
public static <ValueType> CustomConcurrentHashMap<Integer,ValueType> newIntKeyMap(CustomConcurrentHashMap.Strength valueStrength, CustomConcurrentHashMap.Equivalence<? super ValueType> valueEquivalence, int expectedSize) Returns a new map using Integer keys and the given value parameters- Parameters:
valueStrength
- the strength for valuesvalueEquivalence
- the Equivalence to use for valuesexpectedSize
- an estimate of the number of elements that will be held in the map. If no estimate is known, zero is an acceptable value.- Returns:
- the map
-
newIntValueMap
public static <KeyType> CustomConcurrentHashMap<KeyType,Integer> newIntValueMap(CustomConcurrentHashMap.Strength keyStrength, CustomConcurrentHashMap.Equivalence<? super KeyType> keyEquivalence, int expectedSize) Returns a new map using the given key parameters and Integer values- Parameters:
keyStrength
- the strength for keyskeyEquivalence
- the Equivalence to use for keysexpectedSize
- an estimate of the number of elements that will be held in the map. If no estimate is known, zero is an acceptable value.- Returns:
- the map
-
newIntKeyIntValueMap
Returns a new map using Integer keys and values- Parameters:
expectedSize
- an estimate of the number of elements that will be held in the map. If no estimate is known, zero is an acceptable value.- Returns:
- the map
-
containsKey
Returns true if this map contains a key equivalent to the given key with respect to this map's key Equivalence.- Specified by:
containsKey
in interfaceMap<K,
V> - Overrides:
containsKey
in classAbstractMap<K,
V> - Parameters:
key
- possible key- Returns:
- true if this map contains the specified key
- Throws:
NullPointerException
- if the specified key is null
-
get
Returns the value associated with a key equivalent to the given key with respect to this map's key Equivalence, ornull
if no such mapping exists- Specified by:
get
in interfaceMap<K,
V> - Overrides:
get
in classAbstractMap<K,
V> - Parameters:
key
- possible key- Returns:
- the value associated with the key or null if there is no mapping.
- Throws:
NullPointerException
- if the specified key is null
-
put
Maps the specified key to the specified value in this map.- Specified by:
put
in interfaceMap<K,
V> - Overrides:
put
in classAbstractMap<K,
V> - Parameters:
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified key- Returns:
- the previous value associated with key, or null if there was no mapping for key
- Throws:
NullPointerException
- if the specified key or value is null
-
putIfAbsent
- Specified by:
putIfAbsent
in interfaceConcurrentMap<K,
V> - Specified by:
putIfAbsent
in interfaceMap<K,
V> - Returns:
- the previous value associated with the specified key, or null if there was no mapping for the key
- Throws:
NullPointerException
- if the specified key or value is null
-
putAll
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. -
replace
- Specified by:
replace
in interfaceConcurrentMap<K,
V> - Specified by:
replace
in interfaceMap<K,
V> - Throws:
NullPointerException
- if any of the arguments are null
-
replace
- Specified by:
replace
in interfaceConcurrentMap<K,
V> - Specified by:
replace
in interfaceMap<K,
V> - Returns:
- the previous value associated with the specified key, or null if there was no mapping for the key
- Throws:
NullPointerException
- if the specified key or value is null
-
remove
Removes the mapping for the specified key.- Specified by:
remove
in interfaceMap<K,
V> - Overrides:
remove
in classAbstractMap<K,
V> - Parameters:
key
- the key to remove- Returns:
- the previous value associated with key, or null if there was no mapping for key
- Throws:
NullPointerException
- if the specified key is null
-
remove
- Specified by:
remove
in interfaceConcurrentMap<K,
V> - Specified by:
remove
in interfaceMap<K,
V> - Throws:
NullPointerException
- if the specified key is null
-
isEmpty
public final boolean isEmpty()Returns true if this map contains no key-value mappings. -
size
public final 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. -
containsValue
Returns true if this map maps one or more keys to a value equivalent to the given value with respect to this map's value Equivalence. Note: This method requires a full internal traversal of the hash table, and so is much slower than method containsKey.- Specified by:
containsValue
in interfaceMap<K,
V> - Overrides:
containsValue
in classAbstractMap<K,
V> - 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
- Throws:
NullPointerException
- if the specified value is null
-
clear
public final void clear()Removes all of the mappings from this map. -
computeIfAbsent
public V computeIfAbsent(K key, CustomConcurrentHashMap.MappingFunction<? super K, ? extends V> mappingFunction) If the specified key is not already associated with a value, computes its value using the given mappingFunction, and if non-null, enters it into the map. This is equivalent toif (map.containsKey(key)) return map.get(key); value = mappingFunction.map(key); if (value != null) return map.put(key, value); else return null;
except that the action is performed atomically. Some attempted operations on this map by other threads may be blocked while computation is in progress. Because this function is invoked within atomicity control, the computation should be short and simple. The most common usage is to construct a new object serving as an initial mapped value, or memoized result.- Parameters:
key
- key with which the specified value is to be associatedmappingFunction
- the function to compute a value- Returns:
- the current (existing or computed) value associated with the specified key, or null if the computation returned null.
- Throws:
NullPointerException
- if the specified key or mappingFunction is null,RuntimeException
- or Error if the mappingFunction does so, in which case the mapping is left unestablished.
-
compute
Updates the mapping for the given key with the result of the given remappingFunction. This is equivalent tovalue = remappingFunction.remap(key, get(key)); if (value != null) return put(key, value): else return remove(key);
except that the action is performed atomically. Some attempted operations on this map by other threads may be blocked while computation is in progress.Sample Usage. A remapping function can be used to perform frequency counting of words using code such as:
map.compute(word, new RemappingFunction<String,Integer>() { public Integer remap(String k, Integer v) { return (v == null) ? 1 : v + 1; }});
- Parameters:
key
- key with which the specified value is to be associatedremappingFunction
- the function to compute a value- Returns:
- the updated value or null if the computation returned null
- Throws:
NullPointerException
- if the specified key or remappingFunction is null,RuntimeException
- or Error if the remappingFunction does so, in which case the mapping is left in its previous state
-
keySet
Returns aSet
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 view's 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. -
values
Returns aCollection
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 view's 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. -
entrySet
Returns aSet
view of the mappings 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 the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.The view's 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. -
equals
Compares the specified object with this map for equality. Returns true if the given object is also a map of the same size, holding keys that are equal using this Map's key Equivalence, and which map to values that are equal according to this Map's value equivalence. -
hashCode
public int hashCode()Returns the sum of the hash codes of each entry in this map's entrySet() view, which in turn are the hash codes computed using key and value Equivalences for this Map.
-