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

java.lang.Object
  extended by 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


Copyright © 2000-2009 Apache Software Foundation. All Rights Reserved.