com.google.common.collect
Class ReferenceMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      com.google.common.collect.ReferenceMap<K,V>

All Implemented Interfaces:

java.io.Serializable, java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>

public final class ReferenceMap<K,V>
extends java.util.AbstractMap<K,V>
implements java.util.concurrent.ConcurrentMap<K,V>, java.io.Serializable

A ConcurrentMap implementation that internally utilizes your choice of strong, soft or weak references for its keys and for its values. As soon as any key or value is reclaimed by the garbage collector, the corresponding entry automatically disappears from the map.

All nine possible combinations of reference types are supported, although using strong keys with strong values provides no benefit over using a Map or ConcurrentMap directly. This implementation does not permit null keys or values.

Note: because garbage collection happens concurrently to your program, it follows that this map is always subject to concurrent modifications, whether or not the caller exposes it to multiple application threads. The usual caveats about the reliability of methods such as size() and Map.equals(java.lang.Object) apply; for example, size() may be observed to remain unchanged for a short time after an entry was reclaimed.

To determine equality to a key, this implementation uses Object.equals(java.lang.Object) for strong references, and identity-based equality for soft and weak references. In other words, for a map with weak or soft key references, get(java.lang.Object) returns null when passed an object that equals a map key, but isn't the same instance. This behavior is similar to the way IdentityHashMap handles key lookups. However, to determine value equality, as occurs when containsValue(java.lang.Object) is called, the ReferenceMap always uses equals, regardless of the value reference type.

Note: new ReferenceMap(WEAK, STRONG) is very nearly a drop-in replacement for WeakHashMap, but improves upon this by using only identity-based equality for keys. When possible, ReferenceMap should be preferred over the JDK collection, for its concurrency and greater flexibility.

Though this class implements Serializable, serializing reference maps with weak or soft references leads to unpredictable results.

Author:

Bob Lee, Kevin Bourrillion

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

ReferenceMap(ReferenceType keyReferenceType, ReferenceType valueReferenceType)
Constructs an empty instance, using the given reference types for keys and values.

ReferenceMap(ReferenceType keyReferenceType, ReferenceType valueReferenceType, java.util.concurrent.ConcurrentMap<java.lang.Object,java.lang.Object> backingMap)
Constructs an empty instance, using the given backing map and the given reference types for keys and values.

Method Summary

void	clear() Removes all of the mappings from this map.
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet()
V	get(java.lang.Object key) Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
V	put(K key, V value) Associates the specified value with the specified key in this map.
V	putIfAbsent(K key, V value)
V	remove(java.lang.Object key) Removes the mapping for a key from this map if it is present.
boolean	remove(java.lang.Object key, java.lang.Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
int	size() Returns the number of key-value mappings in this map.

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, keySet, putAll, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode, keySet, putAll, values

Constructor Detail

ReferenceMap

public ReferenceMap(ReferenceType keyReferenceType,
                    ReferenceType valueReferenceType)

Constructs an empty instance, using the given reference types for keys and values.

ReferenceMap

public ReferenceMap(ReferenceType keyReferenceType,
                    ReferenceType valueReferenceType,
                    java.util.concurrent.ConcurrentMap<java.lang.Object,java.lang.Object> backingMap)

Constructs an empty instance, using the given backing map and the given reference types for keys and values.

Method Detail

size

public int size()

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

Specified by:

size in interface java.util.Map<K,V>

Overrides:

size in class java.util.AbstractMap<K,V>

isEmpty

public boolean isEmpty()

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

Specified by:

isEmpty in interface java.util.Map<K,V>

Overrides:

isEmpty in class java.util.AbstractMap<K,V>

containsKey

public boolean containsKey(java.lang.Object key)

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

Specified by:

containsKey in interface java.util.Map<K,V>

Overrides:

containsKey in class java.util.AbstractMap<K,V>

containsValue

public boolean containsValue(java.lang.Object value)

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

Specified by:

containsValue in interface java.util.Map<K,V>

Overrides:

containsValue in class java.util.AbstractMap<K,V>

get

public V get(java.lang.Object key)

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

Specified by:

get in interface java.util.Map<K,V>

Overrides:

get in class java.util.AbstractMap<K,V>

put

public V put(K key,
             V value)

Associates the specified value with the specified key in this map.

Specified by:

put in interface java.util.Map<K,V>

Overrides:

put in class java.util.AbstractMap<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface java.util.concurrent.ConcurrentMap<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

replace

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

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

remove

public V remove(java.lang.Object key)

Removes the mapping for a key from this map if it is present.

Specified by:

remove in interface java.util.Map<K,V>

Overrides:

remove in class java.util.AbstractMap<K,V>

remove

public boolean remove(java.lang.Object key,
                      java.lang.Object value)

Specified by:

remove in interface java.util.concurrent.ConcurrentMap<K,V>

clear

public void clear()

Removes all of the mappings from this map.

Specified by:

clear in interface java.util.Map<K,V>

Overrides:

clear in class java.util.AbstractMap<K,V>

entrySet

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

Note: Regardless of the choice of key and value reference types, an entry in the entry set always has strong references to both key and value. You should avoid any lingering strong references to Entry objects.

Specified by:

entrySet in interface java.util.Map<K,V>

Specified by:

entrySet in class java.util.AbstractMap<K,V>