com.hp.util.cache

Class AgeOutHashMap<K,V>

java.lang.Object

com.hp.util.cache.AgeOutHashMap<K,V>

Type Parameters:

K - the key class

V - the value class

Direct Known Subclasses:

NotedAgeOutHashMap

public class AgeOutHashMap<K,V>
extends Object

Provides a map of key/value pairs that will automatically age-out when not write-accessed within a given number of milliseconds. The age-out parameter is dynamically configurable, meaning that it can be changed after creation of the map.

Note that this design uses a "passive" age-out model, meaning that aged-out entries are only detected and removed as a side-effect of interaction with the map. For example:

 AgeOutHashMap<Foo, Bar> map = new AgeOutHashMap<Foo, Bar>(100);
 map.put(Foo.F1, Bar.B2);
 // .. wait longer than 100ms for age-out ..
 // At this point, the entry is still in the map, but is only (silently)
 // removed when we attempt to access it:
 Bar b = map.get(Foo.F1);
 assertNull(b);
 

Entries in the map can be "actively" aged-out by invoking the prune() method.

Author:

Simon Hunt

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_AGE_OUT_MS The default age-out (ms).
static long	MIN_AGE_OUT_MS The minimum age-out (ms) allowed.

Constructor Summary

Constructors

Constructor and Description
AgeOutHashMap() Constructs a map with the initial age-out set to the default value of 5000L milliseconds.
AgeOutHashMap(long ageOutMs) Constructs a map with the specified initial age-out value (ms).
AgeOutHashMap(long ageOutMs, boolean ageOutDeadwoodOnly) Constructs a map with the specified initial age-out value (ms).

Method Summary

Methods

Modifier and Type	Method and Description
protected void	deadwood(Set<V> values) Invoked when a set of values are silently removed from the map.
protected void	deadwood(V value) Invoked when a value is silently removed from the map.
V	get(K key) Returns the value in the map for the given key.
long	getAgeOutMs() Returns the current age-out value (ms).
int	prune() Prunes aged-out entries from the map, returning the true map size.
V	put(K key, V value) Creates an entry in the map for the given key and value, returning the old value if there was one; null otherwise.
V	remove(K key) Removes the entry from the map for the given key, returning its value.
void	setAgeOut(long ageOutMs) Sets a new age-out value (ms) on the map.
int	size() Returns the number of entries in the map.
String	toString()
boolean	touch(K key) Refreshes the timestamp for the map entry with the given key, if it exists.
boolean	touchOrPut(K key, V value) Refreshes the timestamp for the map entry with the given key, if it exists, or creates a new entry.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_AGE_OUT_MS

public static final long DEFAULT_AGE_OUT_MS

The default age-out (ms).

See Also:

Constant Field Values

MIN_AGE_OUT_MS

public static final long MIN_AGE_OUT_MS

The minimum age-out (ms) allowed.

See Also:

Constant Field Values

Constructor Detail

AgeOutHashMap

public AgeOutHashMap()

Constructs a map with the initial age-out set to the default value of 5000L milliseconds.

AgeOutHashMap

public AgeOutHashMap(long ageOutMs)

Constructs a map with the specified initial age-out value (ms).

Parameters:

ageOutMs - the initial age-out value

Throws:

IllegalArgumentException - if ageOutMs is less than 10L

AgeOutHashMap

public AgeOutHashMap(long ageOutMs,
             boolean ageOutDeadwoodOnly)

Constructs a map with the specified initial age-out value (ms). During a call to public remove(Object), the ageOutDeadwoodOnly flag determines if deadwood(Object) is invoked.

Parameters:

ageOutMs - the initial age-out value

ageOutDeadwoodOnly - the age-out deadwood only flag

Throws:

IllegalArgumentException - if ageOutMs is less than 10L

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getAgeOutMs

public long getAgeOutMs()

Returns the current age-out value (ms).

Returns:

the current age-out value (ms)

setAgeOut

public void setAgeOut(long ageOutMs)

Sets a new age-out value (ms) on the map. Any entries in the map older than this new value are immediately pruned.

Parameters:

ageOutMs - the new age-out value (ms)

size

public int size()

Returns the number of entries in the map. Note that this may be an over-estimate of the true number if there are entries that have aged-out but have not yet been pruned from the map. To get an accurate count, invoke prune() first.

Returns:

the number of map entries

prune

public int prune()

Prunes aged-out entries from the map, returning the true map size.

Returns:

the map size after pruning

put

public V put(K key,
    V value)

Creates an entry in the map for the given key and value, returning the old value if there was one; null otherwise.

Parameters:

key - the key

value - the new value

Returns:

the old value

touch

public boolean touch(K key)

Refreshes the timestamp for the map entry with the given key, if it exists. This method returns true to indicate that the entry exists and had its timestamp updated; false if there was no entry for the given key.

Parameters:

key - the key

Returns:

true, if the entry exists and was updated; false otherwise

touchOrPut

public boolean touchOrPut(K key,
                 V value)

Refreshes the timestamp for the map entry with the given key, if it exists, or creates a new entry. This method returns true to indicate that the entry already existed and had its timestamp updated; false if a new entry was created.

Parameters:

key - the key

value - the value

Returns:

true, if the entry existed and was simply refreshed; false, if a new entry was created

get

public V get(K key)

Returns the value in the map for the given key. If no such entry exists in the map, null is returned.

Parameters:

key - the key

Returns:

the mapped value

remove

public V remove(K key)

Removes the entry from the map for the given key, returning its value. If no such entry exists in the map, null is returned. The deadwood(Object) callback will be invoked if a value was found and ageOutDeadwoodOnly is not set.

Parameters:

key - the key

Returns:

the (removed) value

deadwood

protected void deadwood(V value)

Invoked when a value is silently removed from the map. This default implementation does nothing.

This method is provided so that subclasses may override it and do something interesting with the value just removed.

Parameters:

value - the value removed from the map

deadwood

protected void deadwood(Set<V> values)

Invoked when a set of values are silently removed from the map. This default implementation does nothing.

This method is provided so that subclasses may override it and do something interesting with the values just removed.

Parameters:

values - the values removed from the map