APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.lang

pack-priv final Class WeakPairMap<K1, K2, V>

extends Object
Class Inheritance
Type Parameters
<K1>
the type of 1st key in key pair
<K2>
the type of 2nd key in key pair
<V>
the type of value
Imports
java.lang.ref.Reference, .ReferenceQueue, .WeakReference, java.util.Collection, .Objects, java.util.concurrent.ConcurrentHashMap, java.util.function.BiFunction
A WeakHashMap-like data structure that uses a pair of weakly-referenced keys with identity equality semantics to associate a strongly-referenced value. Unlike WeakHashMap, this data structure is thread-safe.
Author
Peter Levart

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static interface
WeakPairMap.Pair<K1, K2>

Common interface of both Weak and Lookup key pairs.

private abstract static class
WeakPairMap.WeakRefPeer<K>

Common abstract supertype of a pair of WeakReference peers.

Field Summary

Modifier and TypeField and Description
private final ConcurrentHashMap<WeakPairMap.Pair<K1, K2>, V>
map

private final ReferenceQueue<Object>
queue

Constructor Summary

AccessConstructor and Description
pack-priv
WeakPairMap()

Method Summary

Modifier and TypeMethod and Description
public V

Returns:

the current (existing or computed) value associated with the specified key pair, or null if the computed value is null
computeIfAbsent(K1
the 1st of the pair of keys with which the computed value is to be associated
k1, K2
the 2nd of the pair of keys with which the computed value is to be associated
k2, BiFunction<? super K1, ? super K2, ? extends V>
the function to compute a value
mappingFunction)

If the specified key pair is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this WeakPairMap unless null.

public boolean

Returns:

true if and only if the specified key pair is in this WeakPairMap, as determined by the identity comparison; false otherwise
containsKeyPair(K1
the 1st of the pair of keys
k1, K2
the 2nd of the pair of keys
k2)

Tests if the specified pair of keys are associated with a value in the WeakPairMap.

private void
expungeStaleAssociations()

Removes associations from this WeakPairMap for which at least one of the keys in key pair has been found weakly-reachable and corresponding WeakRefPeer(s) enqueued.

public V

Returns:

the value to which the specified key pair is mapped, or null if this map contains no mapping for the key pair
get(K1
the 1st of the pair of keys for which the mapped value is to be returned
k1, K2
the 2nd of the pair of keys for which the mapped value is to be returned
k2)

Returns the value to which the specified pair of keys is mapped, or null if this WeakPairMap contains no mapping for the key pair.

public V

Returns:

the previous value associated with key pair, or null if there was no mapping for key pair
put(K1
the 1st of the pair of keys with which the specified value is to be associated
k1, K2
the 2nd of the pair of keys with which the specified value is to be associated
k2, V
value to be associated with the specified key pair
v)

Maps the specified key pair to the specified value in this WeakPairMap.

public V

Returns:

the previous value associated with key pair, or null if there was no mapping for key pair
putIfAbsent(K1
the 1st of the pair of keys with which the specified value is to be associated
k1, K2
the 2nd of the pair of keys with which the specified value is to be associated
k2, V
value to be associated with the specified key pair
v)

If the specified key pair is not already associated with a value, associates it with the given value and returns null, else does nothing and returns the currently associated value.

public Collection<V>

Returns:

the collection view
values()

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

mapback to summary
private final ConcurrentHashMap<WeakPairMap.Pair<K1, K2>, V> map
queueback to summary
private final ReferenceQueue<Object> queue

Constructor Detail

WeakPairMapback to summary
pack-priv WeakPairMap()

Method Detail

computeIfAbsentback to summary
public V computeIfAbsent(K1 k1, K2 k2, BiFunction<? super K1, ? super K2, ? extends V> mappingFunction)

If the specified key pair is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this WeakPairMap unless null. The entire method invocation is performed atomically, so the function is applied at most once per key pair. Some attempted update operations on this WeakPairMap 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 WeakPairMap.

Parameters
k1:K1

the 1st of the pair of keys with which the computed value is to be associated

k2:K2

the 2nd of the pair of keys with which the computed value is to be associated

mappingFunction:BiFunction<? super K1, ? super K2, ? extends V>

the function to compute a value

Returns:V

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

Exceptions
NullPointerException:
if any of the specified keys or mappingFunction is null
IllegalStateException:
if the computation detectably attempts a recursive update to this map that would otherwise never complete
RuntimeException:
or Error if the mappingFunction does so, in which case the mapping is left unestablished
containsKeyPairback to summary
public boolean containsKeyPair(K1 k1, K2 k2)

Tests if the specified pair of keys are associated with a value in the WeakPairMap.

Parameters
k1:K1

the 1st of the pair of keys

k2:K2

the 2nd of the pair of keys

Returns:boolean

true if and only if the specified key pair is in this WeakPairMap, as determined by the identity comparison; false otherwise

Exceptions
NullPointerException:
if any of the specified keys is null
expungeStaleAssociationsback to summary
private void expungeStaleAssociations()

Removes associations from this WeakPairMap for which at least one of the keys in key pair has been found weakly-reachable and corresponding WeakRefPeer(s) enqueued. Called as part of each public operation.

getback to summary
public V get(K1 k1, K2 k2)

Returns the value to which the specified pair of keys is mapped, or null if this WeakPairMap contains no mapping for the key pair.

More formally, if this WeakPairMap contains a mapping from a key pair (_k1, _k2) to a value v such that k1 == _k1 && k2 == _k2, then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

Parameters
k1:K1

the 1st of the pair of keys for which the mapped value is to be returned

k2:K2

the 2nd of the pair of keys for which the mapped value is to be returned

Returns:V

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

Exceptions
NullPointerException:
if any of the specified keys is null
putback to summary
public V put(K1 k1, K2 k2, V v)

Maps the specified key pair to the specified value in this WeakPairMap. Neither the keys nor the value can be null.

The value can be retrieved by calling the get method with the same keys (compared by identity).

Parameters
k1:K1

the 1st of the pair of keys with which the specified value is to be associated

k2:K2

the 2nd of the pair of keys with which the specified value is to be associated

v:V

value to be associated with the specified key pair

Returns:V

the previous value associated with key pair, or null if there was no mapping for key pair

Exceptions
NullPointerException:
if any of the specified keys or value is null
putIfAbsentback to summary
public V putIfAbsent(K1 k1, K2 k2, V v)

If the specified key pair is not already associated with a value, associates it with the given value and returns null, else does nothing and returns the currently associated value.

Parameters
k1:K1

the 1st of the pair of keys with which the specified value is to be associated

k2:K2

the 2nd of the pair of keys with which the specified value is to be associated

v:V

value to be associated with the specified key pair

Returns:V

the previous value associated with key pair, or null if there was no mapping for key pair

Exceptions
NullPointerException:
if any of the specified keys or value is null
valuesback to summary
public Collection<V> values()

Returns a Collection view of the values contained in this WeakPairMap. The collection is backed by the WeakPairMap, 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.

Returns:Collection<V>

the collection view

java.lang back to summary

private Interface WeakPairMap.Pair<K1, K2>

Known Direct Implementers
java.lang.WeakPairMap.Pair.Weak, java.lang.WeakPairMap.Pair.Lookup
Common interface of both Weak and Lookup key pairs.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
WeakPairMap.Pair.Lookup<K1, K2>

Optimized lookup Pair, used as lookup key in methods like java.util.Map#get(Object) or java.util.Map#containsKey(Object)) where there is a great chance its allocation is eliminated by escape analysis when such lookups are inlined by JIT.

public static class
WeakPairMap.Pair.Weak<K1, K2>

A Pair where both keys are weakly-referenced.

Method Summary

Modifier and TypeMethod and Description
public static boolean
equals(Object first, Object second, WeakPairMap.Pair<?, ?> p)

public K1
first()

Returns: The 1st of the pair of keys (may be null for Weak when it gets cleared)

public static int
hashCode(Object first, Object second)

public static <K1, K2> WeakPairMap.Pair<K1, K2>
lookup(K1 k1, K2 k2)

public K2
second()

Returns: The 2nd of the pair of keys (may be null for Weak when it gets cleared)

public static <K1, K2> WeakPairMap.Pair<K1, K2>
weak(K1 k1, K2 k2, ReferenceQueue<Object> queue)

Method Detail

equalsback to summary
public static boolean equals(Object first, Object second, WeakPairMap.Pair<?, ?> p)
firstback to summary
public K1 first()
Returns:K1

The 1st of the pair of keys (may be null for Weak when it gets cleared)

hashCodeback to summary
public static int hashCode(Object first, Object second)
lookupback to summary
public static <K1, K2> WeakPairMap.Pair<K1, K2> lookup(K1 k1, K2 k2)
secondback to summary
public K2 second()
Returns:K2

The 2nd of the pair of keys (may be null for Weak when it gets cleared)

weakback to summary
public static <K1, K2> WeakPairMap.Pair<K1, K2> weak(K1 k1, K2 k2, ReferenceQueue<Object> queue)
java.lang back to summary

public final Class WeakPairMap.Pair.Lookup<K1, K2>

extends Object
implements WeakPairMap.Pair<K1, K2>
Class Inheritance
All Implemented Interfaces
java.lang.WeakPairMap.Pair
Optimized lookup Pair, used as lookup key in methods like java.util.Map#get(Object) or java.util.Map#containsKey(Object)) where there is a great chance its allocation is eliminated by escape analysis when such lookups are inlined by JIT. All its methods are purposely designed so that 'this' is never passed to any other method or used as identity.

Field Summary

Modifier and TypeField and Description
private final K1
k1

private final K2
k2

Constructor Summary

AccessConstructor and Description
pack-priv
Lookup(K1 k1, K2 k2)

Method Summary

Modifier and TypeMethod and Description
public boolean
equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public K1
first()

Implements java.lang.WeakPairMap.Pair.first.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public K2
second()

Implements java.lang.WeakPairMap.Pair.second.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

k1back to summary
private final K1 k1
k2back to summary
private final K2 k2

Constructor Detail

Lookupback to summary
pack-priv Lookup(K1 k1, K2 k2)

Method Detail

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Annotations
@Override
firstback to summary
public K1 first()

Implements java.lang.WeakPairMap.Pair.first.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Annotations
@Override
secondback to summary
public K2 second()

Implements java.lang.WeakPairMap.Pair.second.

Annotations
@Override
java.lang back to summary

public final Class WeakPairMap.Pair.Weak<K1, K2>

extends WeakPairMap.WeakRefPeer<K1>
implements WeakPairMap.Pair<K1, K2>
Class Inheritance
All Implemented Interfaces
java.lang.WeakPairMap.Pair
A Pair where both keys are weakly-referenced. It is composed of two instances of WeakRefPeers: 
+-referent-> [K1]                +-referent-> [K2]
    |                                |
  +----------------+               +----------------+
  | Pair.Weak <:   |-----peer----->| (anonymous) <: |
  | WeakRefPeer,   |               | WeakRefPeer    |
  | Pair           |<--weakPair()--|                |
  +----------------+               +----------------+
    |            ^
    |            |
    +-weakPair()-+

Pair.Weak is used for CHM keys. Both peers are associated with the same ReferenceQueue so when either of their referents becomes weakly-reachable, the corresponding entries can be expunged from the map.

Field Summary

Modifier and TypeField and Description
private final int
hash

private final WeakPairMap.WeakRefPeer<K2>
peer

Constructor Summary

AccessConstructor and Description
pack-priv
Weak(K1 k1, K2 k2, ReferenceQueue<Object> queue)

Method Summary

Modifier and TypeMethod and Description
public boolean
equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public K1
first()

Implements java.lang.WeakPairMap.Pair.first.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public K2
second()

Implements java.lang.WeakPairMap.Pair.second.

pack-priv WeakPairMap.Pair.Weak<?, ?>
weakPair()

Implements abstract java.lang.WeakPairMap.WeakRefPeer.weakPair.

Field Detail

hashback to summary
private final int hash
peerback to summary
private final WeakPairMap.WeakRefPeer<K2> peer

Constructor Detail

Weakback to summary
pack-priv Weak(K1 k1, K2 k2, ReferenceQueue<Object> queue)

Method Detail

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Annotations
@Override
firstback to summary
public K1 first()

Implements java.lang.WeakPairMap.Pair.first.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Annotations
@Override
secondback to summary
public K2 second()

Implements java.lang.WeakPairMap.Pair.second.

Annotations
@Override
weakPairback to summary
pack-priv WeakPairMap.Pair.Weak<?, ?> weakPair()

Implements abstract java.lang.WeakPairMap.WeakRefPeer.weakPair.

Annotations
@Override
java.lang back to summary

private abstract Class WeakPairMap.WeakRefPeer<K>

extends WeakReference<K>
Class Inheritance
Known Direct Subclasses
java.lang.WeakPairMap.Pair.Weak
Common abstract supertype of a pair of WeakReference peers.

Constructor Summary

AccessConstructor and Description
pack-priv
WeakRefPeer(K k, ReferenceQueue<Object> queue)

Method Summary

Modifier and TypeMethod and Description
pack-priv abstract WeakPairMap.Pair.Weak<?, ?>
weakPair()

Returns: the Pair.Weak side of the pair of peers.

Constructor Detail

WeakRefPeerback to summary
pack-priv WeakRefPeer(K k, ReferenceQueue<Object> queue)

Method Detail

weakPairback to summary
pack-priv abstract WeakPairMap.Pair.Weak<?, ?> weakPair()
Returns:WeakPairMap.Pair.Weak<?, ?>

the Pair.Weak side of the pair of peers.