echopoint.util
Class ExpiryCache

java.lang.Object
  echopoint.util.ExpiryCache

public class ExpiryCache

extends java.lang.Object

ExpiryCache implements a cache that can contain objects that "expire". A shared background task will periodically "reap" objects that have "expired".

By default, soft references are used to the cached data so that they can be reclaimed in low memory conditions regardless of whether they have expired or not.

The time-to-live and access-timeout is used to decide when an object has expired and needs to be removed from the cache.

Time-to-live is simple. Once the specified period elapses, the object is removed from the cache, regardless of how many times its been accessed.

Access-timeout is a little more complicated. Each time the object is taken from the cache, its lastAccessTime is tracked. If the access-timeout has expired (since its last access) then the object is taken from the cache.

If both the time-to-live and access-timeout is -1, then the object will never expire from the cache.

Field Summary

static long	DEFAULT_ACCESS_TIMEOUT the default cache access time out 5 minutes
static long	DEFAULT_REAPER_INTERVAL The reaper interval is 2 minutes.
static long	DEFAULT_TIME_TO_LIVE the default cache time-to-live is 10 minutes

Constructor Summary

ExpiryCache()
Constructs a default ExpiryCache

ExpiryCache(long timeToLive, long accessTimeout)
Constructs a ExpiryCache

ExpiryCache(long timeToLive, long accessTimeout, boolean softReferences)
Constructs a ExpiryCache with all the parameters

Method Summary

void	clear() Clears the cache of all contained objects
boolean	containsKey(java.lang.Object key) Returns true if this ExpiryCache contains an entry for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this ExpiryCache contains a key to the specified value.
java.lang.Object	get(java.lang.Object key) Retrieves an object from the cache
int	howManyObjects() Returtns how many objects are currently in the cache.
int	howManyTimesAccessed(java.lang.Object key) Returns the number of times the object was accessed under a given key
boolean	isSoftReferences() Returns true if soft refernces are used to cached data
java.lang.Object	put(java.lang.Object key, java.lang.Object objToCache) Places an object into the cache.
java.lang.Object	put(java.lang.Object key, java.lang.Object objToCache, long timeToLive, long accessTimeout) Places an object into the cache with the specified 'time-to-live' and a 'access time out' value.
void	setAccessTimeout(long milliSecs) Sets the default access timeout for a cache entry
void	setTimeToLive(long milliSecs) Sets the default 'time-to-live' for a cache entry
long	whenCached(java.lang.Object key) Returns the time when the object was cached under a given key
long	whenLastAccessed(java.lang.Object key) Returns the time when the object was last accessed under a given key

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIME_TO_LIVE

public static final long DEFAULT_TIME_TO_LIVE

the default cache time-to-live is 10 minutes

See Also:

Constant Field Values

DEFAULT_ACCESS_TIMEOUT

public static final long DEFAULT_ACCESS_TIMEOUT

the default cache access time out 5 minutes

See Also:

Constant Field Values

DEFAULT_REAPER_INTERVAL

public static final long DEFAULT_REAPER_INTERVAL

The reaper interval is 2 minutes. Therefore the cached object life span granulairty is +/- 1 minute.

See Also:

Constant Field Values

Constructor Detail

ExpiryCache

public ExpiryCache()

Constructs a default ExpiryCache

ExpiryCache

public ExpiryCache(long timeToLive,
                   long accessTimeout)

Constructs a ExpiryCache

Parameters:

timeToLive - - the default time-to-live for a cache entry

accessTimeout - - the default access timeout for a cache entry

ExpiryCache

public ExpiryCache(long timeToLive,
                   long accessTimeout,
                   boolean softReferences)

Constructs a ExpiryCache with all the parameters

Parameters:

timeToLive - - the default time-to-live for a cache entry

accessTimeout - - the default access timeout for a cache entry

softReferences - - whether soft refernces are used to cached data

Method Detail

setTimeToLive

public void setTimeToLive(long milliSecs)

Sets the default 'time-to-live' for a cache entry

Parameters:

milliSecs - - 'time-to-live' for a cache entry

setAccessTimeout

public void setAccessTimeout(long milliSecs)

Sets the default access timeout for a cache entry

Parameters:

milliSecs - - access timeout for a cache entry

howManyObjects

public int howManyObjects()

Returtns how many objects are currently in the cache.

Returns:

how many objects are currently in the cache.

clear

public void clear()

Clears the cache of all contained objects

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object objToCache)

Places an object into the cache. The object will have a caches default 'time-to-live' and a caches default 'access time out' value.

Parameters:

key - - the key of the cached object

objToCache - - the object to cache

Returns:

- the old object at this cache key

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object objToCache,
                            long timeToLive,
                            long accessTimeout)

Places an object into the cache with the specified 'time-to-live' and a 'access time out' value.

Parameters:

key - - the key of the cached object

objToCache - - the object to cache

timeToLive - - the time-to-live on the object or -1 to live for ever

accessTimeout - - the accessTimeout on the object or -1 to never time out

Returns:

- the old object at this cache key

get

public java.lang.Object get(java.lang.Object key)

Retrieves an object from the cache

Parameters:

key - - the key to the cached object

Returns:

the object for the key or null

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this ExpiryCache contains an entry for the specified key. More formally, returns true if and only if this map contains at a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Parameters:

key - key whose presence in this map is to be tested.

Returns:

true if this ExpiryCache contains an entry for the specified key.

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this ExpiryCache contains a key to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)).

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this ExpiryCache contains a key to the specified value

whenCached

public long whenCached(java.lang.Object key)

Returns the time when the object was cached under a given key

Parameters:

key - - the key to the cached object

Returns:

the time when the object was cached under a given key

whenLastAccessed

public long whenLastAccessed(java.lang.Object key)

Returns the time when the object was last accessed under a given key

Parameters:

key - - the key to the cached object

Returns:

the time when the object was last accessed under a given key

howManyTimesAccessed

public int howManyTimesAccessed(java.lang.Object key)

Returns the number of times the object was accessed under a given key

Parameters:

key - - the key to the cached object

Returns:

the number of times the object was accessed under a given key

isSoftReferences

public boolean isSoftReferences()

Returns true if soft refernces are used to cached data

Returns:

true if soft refernces are used to cached data