APIdia Launch Partner
Top Description Fields Constructors Methods
jdk.internal.util

public final Class ReferencedKeyMap<K, V>

extends Object
implements Map<K, V>
Class Inheritance
All Implemented Interfaces
java.util.Map
Type Parameters
<K>
the type of keys maintained by this map
<V>
the type of mapped values
Imports
java.lang.ref.Reference, .ReferenceQueue, .SoftReference, .WeakReference, java.util.AbstractMap, .Collection, .HashMap, .Objects, .Map, .Set, java.util.concurrent.ConcurrentHashMap, java.util.function.Supplier, .UnaryOperator, java.util.stream.Collectors, .Stream, jdk.internal.access.SharedSecrets, jdk.internal.misc.CDS

This class provides management of maps where it is desirable to remove entries automatically when the key is garbage collected. This is accomplished by using a backing map where the keys are either a WeakReference or a SoftReference.

To create a ReferencedKeyMap the user must provide a Supplier of the backing map and whether WeakReference or SoftReference is to be used.

// Use HashMap and WeakReference Map<Long, String> map = ReferencedKeyMap.create(false, HashMap::new); map.put(10_000_000L, "a"); map.put(10_000_001L, "b"); map.put(10_000_002L, "c"); map.put(10_000_003L, "d"); map.put(10_000_004L, "e"); // Use ConcurrentHashMap and SoftReference map = ReferencedKeyMap.create(true, ConcurrentHashMap::new); map.put(20_000_000L, "v"); map.put(20_000_001L, "w"); map.put(20_000_002L, "x"); map.put(20_000_003L, "y"); map.put(20_000_004L, "z");
// Use HashMap and WeakReference
Map<Long, String> map = ReferencedKeyMap.create(false, HashMap::new);
map.put(10_000_000L, "a");
map.put(10_000_001L, "b");
map.put(10_000_002L, "c");
map.put(10_000_003L, "d");
map.put(10_000_004L, "e");

// Use ConcurrentHashMap and SoftReference
map = ReferencedKeyMap.create(true, ConcurrentHashMap::new);
map.put(20_000_000L, "v");
map.put(20_000_001L, "w");
map.put(20_000_002L, "x");
map.put(20_000_003L, "y");
map.put(20_000_004L, "z");

Implementation Note

Care must be given that the backing map does replacement by replacing the value in the map entry instead of deleting the old entry and adding a new entry, otherwise replaced entries may end up with a strongly referenced key. HashMap and ConcurrentHashMap are known to be safe.

Since
21

Field Summary

Modifier and TypeField and Description
private final boolean
isSoft

true if SoftReference keys are to be used, WeakReference otherwise.

private final Map<ReferenceKey<K>, V>
map

Backing Map.

private final ReferenceQueue<K>
stale

ReferenceQueue for cleaning up entries.

Constructor Summary

AccessConstructor and Description
private
ReferencedKeyMap(boolean
true if SoftReference keys are to be used, WeakReference otherwise.
isSoft
,
Map<ReferenceKey<K>, V>
backing map
map
,
ReferenceQueue<K>
ReferenceQueue for cleaning up entries
stale
)

Private constructor.

Method Summary

Modifier and TypeMethod and Description
public void
clear()

Implements java.util.Map.clear.

Removes all of the mappings from this map (optional operation).

public static <
the type of keys maintained by the new map
K
,
the type of mapped values
V
>
Supplier<Map<ReferenceKey<K>, V>>
concurrentHashMapSupplier()

Returns: a supplier to create a ConcurrentHashMap appropriate for use in the create methods.

public boolean
containsKey(Object key)

Implements java.util.Map.containsKey.

Returns true if this map contains a mapping for the specified key.

public boolean
containsValue(Object value)

Implements java.util.Map.containsValue.

Returns true if this map maps one or more keys to the specified value.

public static <
the type of keys maintained by the new map
K
,
the type of mapped values
V
>
ReferencedKeyMap<K, V>

Returns:

a new map with Reference keys
create
(boolean
true if SoftReference keys are to be used, WeakReference otherwise.
isSoft
,
Supplier<Map<ReferenceKey<K>, V>>
Supplier of the backing map
supplier
)

Create a new ReferencedKeyMap map.

private ReferenceKey<K>

Returns:

a key suitable for a map entry
entryKey
(Object
unwrapped key
key
)

Returns a key suitable for a map entry.

public Set<Map.Entry<K, V>>
entrySet()

Implements java.util.Map.entrySet.

Returns a Set view of the mappings contained in this map.

private static <
type of key
T
>
T

Returns:

key if found otherwise null
existingKey
(ReferencedKeyMap<T, ReferenceKey<T>>
ReferencedKeyMap where interning takes place
setMap
,
T
key to test
key
)

Check if the key already exists in the map.

private Stream<K>

Returns:

Stream of valid keys (unwrapped)
filterKeySet
()

Common routine for collecting the current set of keys.

public V
get(Object key)

Implements java.util.Map.get.

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

private V
pack-priv static <
type of key
T
>
T

Returns:

the old key instance if found otherwise the new key instance
intern
(ReferencedKeyMap<T, ReferenceKey<T>>
ReferencedKeyMap where interning takes place
setMap
,
T
key to add
key
)

Puts an entry where the key and the value are the same.

pack-priv static <
type of key
T
>
T

Returns:

the old key instance if found otherwise the new key instance
intern
(ReferencedKeyMap<T, ReferenceKey<T>>
ReferencedKeyMap where interning takes place
setMap
,
T
key to add
key
,
UnaryOperator<T>
operation to apply to key before adding to map
interner
)

Puts an entry where the key and the value are the same.

pack-priv static <
type of key
T
>
boolean

Returns:

true if the key was added
internAddKey
(ReferencedKeyMap<T, ReferenceKey<T>>
ReferencedKeyMap where interning takes place
setMap
,
T
key to add
key
)

Attempt to add key to map if absent.

private static <
type of key
T
>
T

Returns:

the old key instance if found otherwise the new key instance
internKey
(ReferencedKeyMap<T, ReferenceKey<T>>
ReferencedKeyMap where interning takes place
setMap
,
T
key to add
key
)

Attempt to add key to map.

public boolean
isEmpty()

Implements java.util.Map.isEmpty.

Returns true if this map contains no key-value mappings.

public Set<K>
keySet()

Implements java.util.Map.keySet.

Returns a Set view of the keys contained in this map.

private ReferenceKey<K>

Returns:

a key suitable for lookup
lookupKey
(Object
unwrapped key
key
)

Returns a key suitable for lookup.

public void
public V
put(K key, V newValue)

Implements java.util.Map.put.

Associates the specified value with the specified key in this map (optional operation).

public void
putAll(Map<? extends K, ? extends V> m)

Implements java.util.Map.putAll.

Copies all of the mappings from the specified map to this map (optional operation).

public V
putIfAbsent(K key, V newValue)

Overrides default java.util.Map.putIfAbsent.

If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value (optional operation).

public V
remove(Object key)

Implements java.util.Map.remove.

Removes the mapping for a key from this map if it is present (optional operation).

public boolean
remove(Object key, Object value)

Overrides default java.util.Map.remove.

Removes the entry for the specified key only if it is currently mapped to the specified value (optional operation).

public void
removeStaleReferences()

Removes enqueued weak references from map.

public boolean
replace(K key, V oldValue, V newValue)

Overrides default java.util.Map.replace.

Replaces the entry for the specified key only if currently mapped to the specified value (optional operation).

public V
replace(K key, V value)

Overrides default java.util.Map.replace.

Replaces the entry for the specified key only if it is currently mapped to some value (optional operation).

public int
size()

Implements java.util.Map.size.

Returns the number of key-value mappings in this map.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

public Collection<V>
values()

Implements java.util.Map.values.

Returns a Collection view of the values contained in this map.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

isSoftback to summary
private final boolean isSoft

true if SoftReference keys are to be used, WeakReference otherwise.

mapback to summary
private final Map<ReferenceKey<K>, V> map

Backing Map.

staleback to summary
private final ReferenceQueue<K> stale

ReferenceQueue for cleaning up entries.

Constructor Detail

ReferencedKeyMapback to summary
private ReferencedKeyMap(boolean isSoft, Map<ReferenceKey<K>, V> map, ReferenceQueue<K> stale)

Private constructor.

Parameters
isSoft:boolean

true if SoftReference keys are to be used, WeakReference otherwise.

map:Map<ReferenceKey<K>, V>

backing map

stale:ReferenceQueue<K>

ReferenceQueue for cleaning up entries

Method Detail

clearback to summary
public void clear()

Implements java.util.Map.clear.

Doc from java.util.Map.clear.

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Annotations
@Override
concurrentHashMapSupplierback to summary
public static <K, V> Supplier<Map<ReferenceKey<K>, V>> concurrentHashMapSupplier()
Parameters
<K>
the type of keys maintained by the new map
<V>
the type of mapped values
Returns:Supplier<Map<ReferenceKey<K>, V>>

a supplier to create a ConcurrentHashMap appropriate for use in the create methods.

containsKeyback to summary
public boolean containsKey(Object key)

Implements java.util.Map.containsKey.

Doc from java.util.Map.containsKey.

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.)

Annotations
@Override
containsValueback to summary
public boolean containsValue(Object value)

Implements java.util.Map.containsValue.

Doc from java.util.Map.containsValue.

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.

Annotations
@Override
createback to summary
public static <K, V> ReferencedKeyMap<K, V> create(boolean isSoft, Supplier<Map<ReferenceKey<K>, V>> supplier)

Create a new ReferencedKeyMap map.

Parameters
<K>
the type of keys maintained by the new map
<V>
the type of mapped values
isSoft:boolean

true if SoftReference keys are to be used, WeakReference otherwise.

supplier:Supplier<Map<ReferenceKey<K>, V>>

Supplier of the backing map

Returns:ReferencedKeyMap<K, V>

a new map with Reference keys

entryKeyback to summary
private ReferenceKey<K> entryKey(Object key)

Returns a key suitable for a map entry.

Parameters
key:Object

unwrapped key

Returns:ReferenceKey<K>

a key suitable for a map entry

Annotations
@SuppressWarnings:unchecked
entrySetback to summary
public Set<Map.Entry<K, V>> entrySet()

Implements java.util.Map.entrySet.

Doc from java.util.Map.entrySet.

Returns a Set 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. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) 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.

Annotations
@Override
existingKeyback to summary
private static <T> T existingKey(ReferencedKeyMap<T, ReferenceKey<T>> setMap, T key)

Check if the key already exists in the map.

Parameters
<T>
type of key
setMap:ReferencedKeyMap<T, ReferenceKey<T>>

ReferencedKeyMap where interning takes place

key:T

key to test

Returns:T

key if found otherwise null

filterKeySetback to summary
private Stream<K> filterKeySet()

Common routine for collecting the current set of keys.

Returns:Stream<K>

Stream of valid keys (unwrapped)

getback to summary
public V get(Object key)

Implements java.util.Map.get.

Doc from java.util.Map.get.

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.

Annotations
@Override
getNoCheckStaleback to summary
private V getNoCheckStale(Object key)
internback to summary
pack-priv static <T> T intern(ReferencedKeyMap<T, ReferenceKey<T>> setMap, T key)

Puts an entry where the key and the value are the same. Used for interning values in a set.

Implementation Note

Requires a ReferencedKeyMap whose V type is a ReferenceKey<K>. Otherwise, a ClassCastException will be thrown.

Parameters
<T>
type of key
setMap:ReferencedKeyMap<T, ReferenceKey<T>>

ReferencedKeyMap where interning takes place

key:T

key to add

Returns:T

the old key instance if found otherwise the new key instance

Exceptions
ClassCastException:
if V is not EntryKey<T>
internback to summary
pack-priv static <T> T intern(ReferencedKeyMap<T, ReferenceKey<T>> setMap, T key, UnaryOperator<T> interner)

Puts an entry where the key and the value are the same. Used for interning values in a set.

Implementation Note

Requires a ReferencedKeyMap whose V type is a ReferenceKey<K>. Otherwise, a ClassCastException will be thrown.

Implementation Note

This version of intern should not be called during phase1 using a lambda. Use an UnaryOperator instance instead.

Parameters
<T>
type of key
setMap:ReferencedKeyMap<T, ReferenceKey<T>>

ReferencedKeyMap where interning takes place

key:T

key to add

interner:UnaryOperator<T>

operation to apply to key before adding to map

Returns:T

the old key instance if found otherwise the new key instance

Exceptions
ClassCastException:
if V is not EntryKey<T>
internAddKeyback to summary
pack-priv static <T> boolean internAddKey(ReferencedKeyMap<T, ReferenceKey<T>> setMap, T key)

Attempt to add key to map if absent.

Parameters
<T>
type of key
setMap:ReferencedKeyMap<T, ReferenceKey<T>>

ReferencedKeyMap where interning takes place

key:T

key to add

Returns:boolean

true if the key was added

internKeyback to summary
private static <T> T internKey(ReferencedKeyMap<T, ReferenceKey<T>> setMap, T key)

Attempt to add key to map.

Parameters
<T>
type of key
setMap:ReferencedKeyMap<T, ReferenceKey<T>>

ReferencedKeyMap where interning takes place

key:T

key to add

Returns:T

the old key instance if found otherwise the new key instance

isEmptyback to summary
public boolean isEmpty()

Implements java.util.Map.isEmpty.

Doc from java.util.Map.isEmpty.

Returns true if this map contains no key-value mappings.

Annotations
@Override
keySetback to summary
public Set<K> keySet()

Implements java.util.Map.keySet.

Doc from java.util.Map.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.

Annotations
@Override
lookupKeyback to summary
private ReferenceKey<K> lookupKey(Object key)

Returns a key suitable for lookup.

Parameters
key:Object

unwrapped key

Returns:ReferenceKey<K>

a key suitable for lookup

Annotations
@SuppressWarnings:unchecked
prepareForAOTCacheback to summary
public void prepareForAOTCache()
Annotations
@SuppressWarnings:unchecked
putback to summary
public V put(K key, V newValue)

Implements java.util.Map.put.

Doc from java.util.Map.put.

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 m.containsKey(k) would return true.)

Annotations
@Override
putAllback to summary
public void putAll(Map<? extends K, ? extends V> m)

Implements java.util.Map.putAll.

Doc from java.util.Map.putAll.

Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress. If the specified map has a defined encounter order, processing of its mappings generally occurs in that order.

Annotations
@Override
putIfAbsentback to summary
public V putIfAbsent(K key, V newValue)

Overrides default java.util.Map.putIfAbsent.

Doc from java.util.Map.putIfAbsent.

If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value (optional operation).

Annotations
@Override
removeback to summary
public V remove(Object key)

Implements java.util.Map.remove.

Doc from java.util.Map.remove.

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.

Annotations
@Override
removeback to summary
public boolean remove(Object key, Object value)

Overrides default java.util.Map.remove.

Doc from java.util.Map.remove.

Removes the entry for the specified key only if it is currently mapped to the specified value (optional operation).

Annotations
@Override
removeStaleReferencesback to summary
public void removeStaleReferences()

Removes enqueued weak references from map.

replaceback to summary
public boolean replace(K key, V oldValue, V newValue)

Overrides default java.util.Map.replace.

Doc from java.util.Map.replace.

Replaces the entry for the specified key only if currently mapped to the specified value (optional operation).

Annotations
@Override
replaceback to summary
public V replace(K key, V value)

Overrides default java.util.Map.replace.

Doc from java.util.Map.replace.

Replaces the entry for the specified key only if it is currently mapped to some value (optional operation).

Annotations
@Override
sizeback to summary
public int size()

Implements java.util.Map.size.

Doc from java.util.Map.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.

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations
@Override
valuesback to summary
public Collection<V> values()

Implements java.util.Map.values.

Doc from java.util.Map.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.

Annotations
@Override