com.vladium.util

Class SoftValueMap

java.lang.Object

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

Nested Classes

Modifier and Type	Class and Description
(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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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().