com.vladium.util
Class SoftValueMap

java.lang.Object
  extended by com.vladium.util.SoftValueMap
All Implemented Interfaces:
java.util.Map

public final class SoftValueMap
extends java.lang.Object
implements java.util.Map

MT-safety: an instance of this class is not safe for access from multiple concurrent threads [even if access is done by a single thread at a time]. The caller is expected to synchronize externally on an instance [the implementation does not do internal synchronization for the sake of efficiency]. java.util.ConcurrentModificationException is not supported either.

Author:
(C) 2002, Vlad Roubtsov

Nested Class Summary
(package private) static class SoftValueMap.IndexedSoftReference
          An extension of WeakReference that can store an index of the bucket it is associated with.
(package private) static class SoftValueMap.SoftEntry
          The structure used for chaining colliding keys.
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Field Summary
private static boolean DEBUG
           
private static boolean ENQUEUE_FOUND_CLEARED_ENTRIES
           
private static java.lang.String EOL
           
private static boolean IDENTITY_OPTIMIZATION
           
private  SoftValueMap.SoftEntry[] m_buckets
           
private  float m_loadFactor
           
private  int m_readAccessCount
           
private  int m_readClearCheckFrequency
           
private  int m_size
           
private  int m_sizeThreshold
           
private  java.lang.ref.ReferenceQueue m_valueReferenceQueue
           
private  int m_writeAccessCount
           
private  int m_writeClearCheckFrequency
           
 
Constructor Summary
SoftValueMap()
          Equivalent to SoftValueMap(1, 1).
SoftValueMap(int initialCapacity, float loadFactor, int readClearCheckFrequency, int writeClearCheckFrequency)
          Constructs a SoftValueMap with specified initial capacity, load factor, and cleared value removal frequencies.
SoftValueMap(int readClearCheckFrequency, int writeClearCheckFrequency)
          Equivalent to SoftValueMap(11, 0.75F, getClearCheckFrequency, putClearCheckFrequency).
 
Method Summary
 void clear()
           
 boolean containsKey(java.lang.Object key)
           
 boolean containsValue(java.lang.Object value)
           
(package private)  void debugDump(java.lang.StringBuffer out)
           
 java.util.Set entrySet()
           
 boolean equals(java.lang.Object rhs)
           
 java.lang.Object get(java.lang.Object key)
          Returns the value that is mapped to a given 'key'.
 int hashCode()
           
 boolean isEmpty()
          Returns 'false' is this map contains key-value mappings (even if some of the values may have been cleared already but not removed from the table).
 java.util.Set keySet()
           
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          Updates the table to map 'key' to 'value'.
 void putAll(java.util.Map map)
           
private  void rehash()
          Re-hashes the table into a new array of buckets.
 java.lang.Object remove(java.lang.Object key)
           
private  void removeClearedValues()
          Removes all entries whose soft values have been cleared _and_ enqueued.
 int size()
          Returns the number of key-value mappings in this map.
 java.lang.String toString()
          Overrides Object.toString() for debug purposes.
 java.util.Collection values()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

m_valueReferenceQueue

private final java.lang.ref.ReferenceQueue m_valueReferenceQueue

m_loadFactor

private final float m_loadFactor

m_readClearCheckFrequency

private final int m_readClearCheckFrequency

m_writeClearCheckFrequency

private final int m_writeClearCheckFrequency

m_buckets

private SoftValueMap.SoftEntry[] m_buckets

m_size

private int m_size

m_sizeThreshold

private int m_sizeThreshold

m_readAccessCount

private int m_readAccessCount

m_writeAccessCount

private int m_writeAccessCount

EOL

private static final java.lang.String EOL

IDENTITY_OPTIMIZATION

private static final boolean IDENTITY_OPTIMIZATION
See Also:
Constant Field Values

ENQUEUE_FOUND_CLEARED_ENTRIES

private static final boolean ENQUEUE_FOUND_CLEARED_ENTRIES
See Also:
Constant Field Values

DEBUG

private static final boolean DEBUG
See Also:
Constant Field Values
Constructor Detail

SoftValueMap

public SoftValueMap()
Equivalent to SoftValueMap(1, 1).


SoftValueMap

public SoftValueMap(int readClearCheckFrequency,
                    int writeClearCheckFrequency)
Equivalent to SoftValueMap(11, 0.75F, getClearCheckFrequency, putClearCheckFrequency).


SoftValueMap

public SoftValueMap(int initialCapacity,
                    float loadFactor,
                    int readClearCheckFrequency,
                    int writeClearCheckFrequency)
Constructs a SoftValueMap with specified initial capacity, load factor, and cleared value removal frequencies.

Parameters:
initialCapacity - initial number of hash buckets in the table [may not be negative, 0 is equivalent to 1].
loadFactor - the load factor to use to determine rehashing points [must be in (0.0, 1.0] range].
readClearCheckFrequency - specifies that every readClearCheckFrequency get(java.lang.Object) should check for and remove all mappings whose soft values have been cleared by the garbage collector [may not be less than 1].
writeClearCheckFrequency - specifies that every writeClearCheckFrequency put(java.lang.Object, java.lang.Object) should check for and remove all mappings whose soft values have been cleared by the garbage collector [may not be less than 1].
Method Detail

equals

public boolean equals(java.lang.Object rhs)
Specified by:
equals in interface java.util.Map
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Specified by:
hashCode in interface java.util.Map
Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Overrides Object.toString() for debug purposes.

Overrides:
toString in class java.lang.Object

size

public int size()
Returns the number of key-value mappings in this map. Some of the values may have been cleared already but not removed from the table.

NOTE: in contrast with the java.util.WeakHashMap implementation, this is a constant time operation.

Specified by:
size in interface java.util.Map

isEmpty

public boolean isEmpty()
Returns 'false' is this map contains key-value mappings (even if some of the values may have been cleared already but not removed from the table).

NOTE: in contrast with the java.util.WeakHashMap implementation, this is a constant time operation.

Specified by:
isEmpty in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)
Returns the value that is mapped to a given 'key'. Returns null if (a) this key has never been mapped or (b) a previously mapped value has been cleared by the garbage collector and removed from the table.

Specified by:
get in interface java.util.Map
Parameters:
key - mapping key [may not be null].
Returns:
Object value mapping for 'key' [can be null].

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
Updates the table to map 'key' to 'value'. Any existing mapping is overwritten.

Specified by:
put in interface java.util.Map
Parameters:
key - mapping key [may not be null].
value - mapping value [may not be null].
Returns:
Object previous value mapping for 'key' [null if no previous mapping existed or its value has been cleared by the garbage collector and removed from the table].

remove

public java.lang.Object remove(java.lang.Object key)
Specified by:
remove in interface java.util.Map

clear

public void clear()
Specified by:
clear in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)
Specified by:
containsKey in interface java.util.Map

containsValue

public boolean containsValue(java.lang.Object value)
Specified by:
containsValue in interface java.util.Map

putAll

public void putAll(java.util.Map map)
Specified by:
putAll in interface java.util.Map

keySet

public java.util.Set keySet()
Specified by:
keySet in interface java.util.Map

entrySet

public java.util.Set entrySet()
Specified by:
entrySet in interface java.util.Map

values

public java.util.Collection values()
Specified by:
values in interface java.util.Map

debugDump

void debugDump(java.lang.StringBuffer out)

rehash

private void rehash()
Re-hashes the table into a new array of buckets. During the process cleared value entries are discarded, making for another efficient cleared value removal method.


removeClearedValues

private void removeClearedValues()
Removes all entries whose soft values have been cleared _and_ enqueued. See comments below for why this is safe wrt to rehash().