Class SoftCache<K,V>
- java.lang.Object
-
- java.util.AbstractMap<K,V>
-
- org.glassfish.pfl.basic.concurrent.SoftCache<K,V>
-
- All Implemented Interfaces:
java.util.Map<K,V>
public class SoftCache<K,V> extends java.util.AbstractMap<K,V> implements java.util.Map<K,V>
A memory-sensitive implementation of theMap
interface.A
SoftCache
object usessoft references
to implement a memory-sensitive hash map. If the garbage collector determines at a certain point in time that a value object in aSoftCache
entry is no longer strongly reachable, then it may remove that entry in order to release the memory occupied by the value object. AllSoftCache
objects are guaranteed to be completely cleared before the virtual machine will throw anOutOfMemoryError
. Because of this automatic clearing feature, the behavior of this class is somewhat different from that of otherMap
implementations.Both null values and the null key are supported. This class has the same performance characteristics as the
HashMap
class, and has the same efficiency parameters of initial capacity and load factor.Like most collection classes, this class is not synchronized. A synchronized
SoftCache
may be constructed using theCollections.synchronizedMap
method.In typical usage this class will be subclassed and the
fill
method will be overridden. When theget
method is invoked on a key for which there is no mapping in the cache, it will in turn invoke thefill
method on that key in an attempt to construct a corresponding value. If thefill
method returns such a value then the cache will be updated and the new value will be returned. Thus, for example, a simple URL-content cache can be constructed as follows:public class URLCache extends SoftCache { protected Object fill(Object key) { return ((URL)key).getContent(); } }
The behavior of the
SoftCache
class depends in part upon the actions of the garbage collector, so several familiar (though not required)Map
invariants do not hold for this class.Because entries are removed from a
SoftCache
in response to dynamic advice from the garbage collector, aSoftCache
may behave as though an unknown thread is silently removing entries. In particular, even if you synchronize on aSoftCache
instance and invoke none of its mutator methods, it is possible for thesize
method to return smaller values over time, for theisEmpty
method to returnfalse
and thentrue
, for thecontainsKey
method to returntrue
and laterfalse
for a given key, for theget
method to return a value for a given key but later returnnull
, for theput
method to returnnull
and theremove
method to returnfalse
for a key that previously appeared to be in the map, and for successive examinations of the key set, the value set, and the entry set to yield successively smaller numbers of elements.I copied this from JDK 1.4.2 to avoid introducing another sun.misc dependency in the ORB. (Ken Cavanaugh)
- Since:
- JDK1.2
- Version:
- 1.6, 03/01/23
- See Also:
HashMap
,SoftReference
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private class
SoftCache.Entry
private class
SoftCache.EntrySet
private static class
SoftCache.ValueCell<K,V>
-
Field Summary
Fields Modifier and Type Field Description private java.util.Set<java.util.Map.Entry<K,V>>
entrySet
private java.util.Map<K,SoftCache.ValueCell<K,V>>
hash
private static int
PROCESS_QUEUE_INTERVAL
private int
processQueueCount
private java.lang.ref.ReferenceQueue<V>
queue
-
Constructor Summary
Constructors Constructor Description SoftCache()
Construct a new, emptySoftCache
with the default capacity and the default load factor.SoftCache(int initialCapacity)
Construct a new, emptySoftCache
with the given initial capacity and the default load factor.SoftCache(int initialCapacity, float loadFactor)
Construct a new, emptySoftCache
with the given initial capacity and the given load factor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clear()
Remove all mappings from this cache.boolean
containsKey(java.lang.Object key)
Returntrue
if this cache contains a mapping for the specified key.java.util.Set<java.util.Map.Entry<K,V>>
entrySet()
Return aSet
view of the mappings in this cache.protected V
fill(java.lang.Object key)
Create a value object for the givenkey
.V
get(java.lang.Object key)
Return the value to which this cache maps the specifiedkey
.boolean
isEmpty()
Returntrue
if this cache contains no key-value mappings.private void
processQueue()
V
put(K key, V value)
Update this cache so that the givenkey
maps to the givenvalue
.V
remove(java.lang.Object key)
Remove the mapping for the givenkey
from this cache, if present.int
size()
Return the number of key-value mappings in this cache.private static boolean
valEquals(java.lang.Object o1, java.lang.Object o2)
-
Methods inherited from class java.util.AbstractMap
clone, containsValue, equals, hashCode, keySet, putAll, toString, values
-
-
-
-
Field Detail
-
PROCESS_QUEUE_INTERVAL
private static final int PROCESS_QUEUE_INTERVAL
- See Also:
- Constant Field Values
-
processQueueCount
private int processQueueCount
-
hash
private java.util.Map<K,SoftCache.ValueCell<K,V>> hash
-
queue
private java.lang.ref.ReferenceQueue<V> queue
-
-
Constructor Detail
-
SoftCache
public SoftCache(int initialCapacity, float loadFactor)
Construct a new, emptySoftCache
with the given initial capacity and the given load factor.- Parameters:
initialCapacity
- The initial capacity of the cacheloadFactor
- A number between 0.0 and 1.0- Throws:
java.lang.IllegalArgumentException
- If the initial capacity is less than or equal to zero, or if the load factor is less than zero
-
SoftCache
public SoftCache(int initialCapacity)
Construct a new, emptySoftCache
with the given initial capacity and the default load factor.- Parameters:
initialCapacity
- The initial capacity of the cache- Throws:
java.lang.IllegalArgumentException
- If the initial capacity is less than or equal to zero
-
SoftCache
public SoftCache()
Construct a new, emptySoftCache
with the default capacity and the default load factor.
-
-
Method Detail
-
processQueue
private void processQueue()
-
size
public int size()
Return the number of key-value mappings in this cache. The time required by this operation is linear in the size of the map.
-
isEmpty
public boolean isEmpty()
Returntrue
if this cache contains no key-value mappings.
-
containsKey
public boolean containsKey(java.lang.Object key)
Returntrue
if this cache contains a mapping for the specified key. If there is no mapping for the key, this method will not attempt to construct one by invoking thefill
method.
-
fill
protected V fill(java.lang.Object key)
Create a value object for the givenkey
. This method is invoked by theget
method when there is no entry forkey
. If this method returns a non-null
value, then the cache will be updated to mapkey
to that value, and that value will be returned by theget
method.The default implementation of this method simply returns
null
for everykey
value. A subclass may override this method to provide more useful behavior.- Parameters:
key
- The key for which a value is to be computed- Returns:
- A value for
key
, ornull
if one could not be computed - See Also:
get(java.lang.Object)
-
get
public V get(java.lang.Object key)
Return the value to which this cache maps the specifiedkey
. If the cache does not presently contain a value for this key, then invoke thefill
method in an attempt to compute such a value. If that method returns a non-null
value, then update the cache and return the new value. Otherwise, returnnull
.Note that because this method may update the cache, it is considered a mutator and may cause
ConcurrentModificationException
s to be thrown if invoked while an iterator is in use.- Specified by:
get
in interfacejava.util.Map<K,V>
- Overrides:
get
in classjava.util.AbstractMap<K,V>
- Parameters:
key
- The key whose associated value, if any, is to be returned- See Also:
fill(java.lang.Object)
-
put
public V put(K key, V value)
Update this cache so that the givenkey
maps to the givenvalue
. If the cache previously contained a mapping forkey
then that mapping is replaced and the old value is returned.- Specified by:
put
in interfacejava.util.Map<K,V>
- Overrides:
put
in classjava.util.AbstractMap<K,V>
- Parameters:
key
- The key that is to be mapped to the givenvalue
value
- The value to which the givenkey
is to be mapped- Returns:
- The previous value to which this key was mapped, or
null
if if there was no mapping for the key
-
remove
public V remove(java.lang.Object key)
Remove the mapping for the givenkey
from this cache, if present.
-
clear
public void clear()
Remove all mappings from this cache.
-
valEquals
private static boolean valEquals(java.lang.Object o1, java.lang.Object o2)
-
-