com.opensymphony.xwork2.inject.util
Class ReferenceMap<K,V>

java.lang.Object
  com.opensymphony.xwork2.inject.util.ReferenceMap<K,V>

All Implemented Interfaces:

Serializable, Map<K,V>

Direct Known Subclasses:

ReferenceCache

public class ReferenceMap<K,V>
extends Object
implements Map<K,V>, Serializable

Concurrent hash map that wraps keys and/or values in soft or weak references. Does not support null keys or values. Uses identity equality for weak and soft keys.

The concurrent semantics of ConcurrentHashMap combined with the fact that the garbage collector can asynchronously reclaim and clean up after keys and values at any time can lead to some racy semantics. For example, size() returns an upper bound on the size, i.e. the actual size may be smaller in cases where the key or value has been reclaimed but the map entry has not been cleaned up yet.

Another example: If get(Object) cannot find an existing entry for a key, it will try to create one. This operation is not atomic. One thread could put(Object, Object) a value between the time another thread running get() checks for an entry and decides to create one. In this case, the newly created value will replace the put value in the map. Also, two threads running get() concurrently can potentially create duplicate values for a given key.

In other words, this class is great for caching but not atomicity.

Author:

crazybob@google.com (Bob Lee)

See Also:

Serialized Form

Nested Class Summary

(package private) class	ReferenceMap.Entry
(package private) static interface	ReferenceMap.InternalReference Marker interface to differentiate external and internal references.
(package private) static class	ReferenceMap.KeyReferenceAwareWrapper Used for keys.
private static class	ReferenceMap.PutStrategy
(package private) static class	ReferenceMap.ReferenceAwareWrapper Big hack.
(package private) class	ReferenceMap.SoftKeyReference
(package private) class	ReferenceMap.SoftValueReference
protected static interface	ReferenceMap.Strategy
(package private) class	ReferenceMap.WeakKeyReference
(package private) class	ReferenceMap.WeakValueReference

Field Summary

private static ReferenceMap.PutStrategy	defaultPutStrategy
(package private) ConcurrentMap<Object,Object>	delegate
(package private) ReferenceType	keyReferenceType
private static long	serialVersionUID
(package private) ReferenceType	valueReferenceType

Constructor Summary

ReferenceMap(ReferenceType keyReferenceType, ReferenceType valueReferenceType)
Concurrent hash map that wraps keys and/or values based on specified reference types.

Method Summary

void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
(package private) Object	dereference(ReferenceType referenceType, Object reference) Returns the refererent for reference given its reference type.
(package private) <T extends Collection<Object>> T	dereferenceCollection(ReferenceType referenceType, T in, T out) Dereferences elements in in using referenceType and puts them in out.
(package private) ReferenceMap.Entry	dereferenceEntry(Map.Entry<Object,Object> entry) Dereferences an entry.
(package private) K	dereferenceKey(Object o) Converts a reference to a key.
(package private) Set<K>	dereferenceKeySet(Set keyReferences) Dereferences a set of key references.
(package private) V	dereferenceValue(Object o) Converts a reference to a value.
(package private) Collection<V>	dereferenceValues(Collection valueReferences) Dereferences a collection of value references.
(package private) static void	ensureNotNull(Object... array)
(package private) static void	ensureNotNull(Object o)
Set<Map.Entry<K,V>>	entrySet() Returns an unmodifiable set view of the entries in this map.
(package private) V	execute(ReferenceMap.Strategy strategy, K key, V value)
V	get(Object key)
protected ReferenceMap.PutStrategy	getPutStrategy()
(package private) V	internalGet(K key)
boolean	isEmpty()
(package private) static int	keyHashCode(Object key)
Set<K>	keySet() Returns an unmodifiable set view of the keys in this map.
(package private) Object	makeKeyReferenceAware(Object o) Wraps key so it can be compared to a referenced key for equality.
(package private) Object	makeValueReferenceAware(Object o) Wraps value so it can be compared to a referenced value for equality.
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> t)
V	putIfAbsent(K key, V value)
protected ReferenceMap.Strategy	putIfAbsentStrategy()
protected ReferenceMap.Strategy	putStrategy()
private void	readObject(ObjectInputStream in)
(package private) static boolean	referenceEquals(Reference r, Object o) Tests weak and soft references for identity equality.
(package private) Object	referenceKey(K key) Creates a reference for a key.
(package private) Object	referenceValue(Object keyReference, Object value) Creates a reference for a value.
V	remove(Object key)
boolean	remove(Object key, Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
protected ReferenceMap.Strategy	replaceStrategy()
int	size()
Collection<V>	values() Returns an unmodifiable set view of the values in this map.
private void	writeObject(ObjectOutputStream out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

delegate

transient ConcurrentMap<Object,Object> delegate

keyReferenceType

final ReferenceType keyReferenceType

valueReferenceType

final ReferenceType valueReferenceType

defaultPutStrategy

private static ReferenceMap.PutStrategy defaultPutStrategy

Constructor Detail

ReferenceMap

public ReferenceMap(ReferenceType keyReferenceType,
                    ReferenceType valueReferenceType)

Concurrent hash map that wraps keys and/or values based on specified reference types.

Parameters:

keyReferenceType - key reference type

valueReferenceType - value reference type

Method Detail

internalGet

V internalGet(K key)

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

execute

V execute(ReferenceMap.Strategy strategy,
          K key,
          V value)

put

public V put(K key,
             V value)

Specified by:

put in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

putAll

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

Specified by:

putAll in interface Map<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

keySet

public Set<K> keySet()

Returns an unmodifiable set view of the keys in this map. As this method creates a defensive copy, the performance is O(n).

Specified by:

keySet in interface Map<K,V>

values

public Collection<V> values()

Returns an unmodifiable set view of the values in this map. As this method creates a defensive copy, the performance is O(n).

Specified by:

values in interface Map<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

remove

public boolean remove(Object key,
                      Object value)

replace

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

replace

public V replace(K key,
                 V value)

entrySet

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

Returns an unmodifiable set view of the entries in this map. As this method creates a defensive copy, the performance is O(n).

Specified by:

entrySet in interface Map<K,V>

dereferenceEntry

ReferenceMap.Entry dereferenceEntry(Map.Entry<Object,Object> entry)

Dereferences an entry. Returns null if the key or value has been gc'ed.

referenceKey

Object referenceKey(K key)

Creates a reference for a key.

dereferenceKey

K dereferenceKey(Object o)

Converts a reference to a key.

dereferenceValue

V dereferenceValue(Object o)

Converts a reference to a value.

dereference

Object dereference(ReferenceType referenceType,
                   Object reference)

Returns the refererent for reference given its reference type.

referenceValue

Object referenceValue(Object keyReference,
                      Object value)

Creates a reference for a value.

dereferenceKeySet

Set<K> dereferenceKeySet(Set keyReferences)

Dereferences a set of key references.

dereferenceValues

Collection<V> dereferenceValues(Collection valueReferences)

Dereferences a collection of value references.

makeKeyReferenceAware

Object makeKeyReferenceAware(Object o)

Wraps key so it can be compared to a referenced key for equality.

makeValueReferenceAware

Object makeValueReferenceAware(Object o)

Wraps value so it can be compared to a referenced value for equality.

dereferenceCollection

<T extends Collection<Object>> T dereferenceCollection(ReferenceType referenceType,
                                                       T in,
                                                       T out)

Dereferences elements in in using referenceType and puts them in out. Returns out.

keyHashCode

static int keyHashCode(Object key)

referenceEquals

static boolean referenceEquals(Reference r,
                               Object o)

Tests weak and soft references for identity equality. Compares references to other references and wrappers. If o is a reference, this returns true if r == o or if r and o reference the same non null object. If o is a wrapper, this returns true if r's referent is identical to the wrapped object.

putStrategy

protected ReferenceMap.Strategy putStrategy()

putIfAbsentStrategy

protected ReferenceMap.Strategy putIfAbsentStrategy()

replaceStrategy

protected ReferenceMap.Strategy replaceStrategy()

getPutStrategy

protected ReferenceMap.PutStrategy getPutStrategy()

ensureNotNull

static void ensureNotNull(Object o)

ensureNotNull

static void ensureNotNull(Object... array)

writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException

Throws:

IOException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException

Throws:

IOException

ClassNotFoundException