echopoint.util.collections
Class ExpiryCache

java.lang.Object
  echopoint.util.collections.ExpiryCache

All Implemented Interfaces:

Map

Direct Known Subclasses:

TimerExpiryCache

public class ExpiryCache
extends Object
implements Map

ExpiryCache implements a Map cache contains objects that "expire".

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.

The objVersion value, which can be specified at put time, can be later retrieved along with the object. This allows for application level versioning of objects against when they put in the cache. For example if you cached the contents of a File read, you might want to store the File.lastModified() in the objVersion number. Later when you want the cached contents, you could check the put time objVersion number against the current File.lastModified(). So even though the cached content has not expired, the underlying content has and hence should be re-read.

Under the cover this class uses a ConcurrentReaderHashMap and hence is thread safe for writes to the cache.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

static long	DEFAULT_ACCESS_TIMEOUT the default cache access time out 5 minutes
static long	DEFAULT_TIME_TO_LIVE the default cache time-to-live is 60 minutes

Constructor Summary

ExpiryCache()
Constructs a default ExpiryCache that uses SoftReferences

ExpiryCache(long timeToLive, long accessTimeout)
Constructs a ExpiryCache that uses SoftReferences

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

Method Summary

void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value) This operation is not supported on ExpiryCache.
Set	entrySet() This operation is not supported on ExpiryCache.
Object	get(Object key) Retrieves an object from the cache.
Object	get(Object key, long objVersion) Retrieves an object from the cache.
boolean	hasExpired(Object key, long when) Called to see if a cache entry has expired or not at a given point in time.
int	howManyTimesAccessed(Object key) Returns the number of times the object was accessed under a given key
boolean	isEmpty() Note this may return false when in fact all objects in the cache have expired.
boolean	isSoftReferences() Returns true if SoftReferences are used to cached data
Set	keySet() Returns a Set of all the keys in the cache.
protected void	onExpiredObject(Object key) Called when an object has been detected as expired or versioned out of existence.
Object	put(Object key, Object objToCache) Places an object into the cache.
Object	put(Object key, Object objToCache, long objVersion) Places an object into the cache.
Object	put(Object key, Object objToCache, long timeToLive, long accessTimeout) Places an object into the cache with the specified 'time-to-live' and a 'access time out' value.
Object	put(Object key, Object objToCache, long timeToLive, long accessTimeout, long objVersion) Places an object into the cache with the specified 'time-to-live' and a 'access time out' value as well as a version number.
void	putAll(Map t)
Object	remove(Object key)
void	setAccessTimeout(long milliSecs) Sets the default access timeout for a cache entry
void	setSoftReferences(boolean newValue) Sets whether SoftReferences are used to hold cache entries.
void	setTimeToLive(long milliSecs) Sets the default 'time-to-live' for a cache entry
int	size() Note this may return a size larger than the number of non expired objects.
Collection	values() This operation is not supported on ExpiryCache.
long	whenCached(Object key) Returns the time when the object was cached under a given key
long	whenLastAccessed(Object key) Returns the time when the object was last accessed under a given key
long	whenVersion(Object key) Returns the version number that was provided when the object was placed in the cache.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

DEFAULT_TIME_TO_LIVE

public static final long DEFAULT_TIME_TO_LIVE

the default cache time-to-live is 60 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

Constructor Detail

ExpiryCache

public ExpiryCache()

Constructs a default ExpiryCache that uses SoftReferences

ExpiryCache

public ExpiryCache(long timeToLive,
                   long accessTimeout)

Constructs a ExpiryCache that uses SoftReferences

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 SoftReferences 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

whenCached

public long whenCached(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(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

whenVersion

public long whenVersion(Object key)

Returns the version number that was provided when the object was placed in the cache.

Parameters:

key - - the key to the cached object

Returns:

the version number that was provided when the object was placed in the cache or -1 if it was not provided at cache put.

howManyTimesAccessed

public int howManyTimesAccessed(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 SoftReferences are used to cached data

Returns:

true if SoftReferences are used to cached data

setSoftReferences

public void setSoftReferences(boolean newValue)

Sets whether SoftReferences are used to hold cache entries.

Parameters:

newValue - - the new value of the flag

clear

public void clear()

Specified by:

clear in interface Map

See Also:

Map.clear()

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map

See Also:

Map.containsKey(java.lang.Object)

remove

public Object remove(Object key)

Specified by:

remove in interface Map

See Also:

Map.remove(java.lang.Object)

size

public int size()

Note this may return a size larger than the number of non expired objects. A traversal of cached objects is NOT done here to work out a correct size value.

Specified by:

size in interface Map

See Also:

Map.size()

isEmpty

public boolean isEmpty()

Note this may return false when in fact all objects in the cache have expired. A traversal of cached objects is NOT done here to work out if it is empty.

Specified by:

isEmpty in interface Map

See Also:

Map.isEmpty()

putAll

public void putAll(Map t)

Specified by:

putAll in interface Map

See Also:

Map.putAll(java.util.Map)

keySet

public Set keySet()

Returns a Set of all the keys in the cache. It may contain keys to objects that have expired so be careful when using this.

Specified by:

keySet in interface Map

Returns:

a Set of all the keys in the cache

entrySet

public Set entrySet()

This operation is not supported on ExpiryCache.

Specified by:

entrySet in interface Map

Throws:

UnsupportedOperationException

values

public Collection values()

This operation is not supported on ExpiryCache.

Specified by:

values in interface Map

Throws:

UnsupportedOperationException

containsValue

public boolean containsValue(Object value)

This operation is not supported on ExpiryCache.

Specified by:

containsValue in interface Map

Throws:

UnsupportedOperationException

put

public Object put(Object key,
                  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.

Specified by:

put in interface Map

Parameters:

key - - the key of the cached object

objToCache - - the object to cache

Returns:

- the old object at this cache key

put

public Object put(Object key,
                  Object objToCache,
                  long objVersion)

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

objVersion - - the version of the object at the time it is put

Returns:

- the old object at this cache key

put

public Object put(Object key,
                  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

put

public Object put(Object key,
                  Object objToCache,
                  long timeToLive,
                  long accessTimeout,
                  long objVersion)

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

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

objVersion - - a version number that can be used later

Returns:

- the old object at this cache key

get

public Object get(Object key)

Retrieves an object from the cache. If the object has expired, then it will return null

Specified by:

get in interface Map

Parameters:

key - - the key to the cached object

Returns:

the object for the key or null

get

public Object get(Object key,
                  long objVersion)

Retrieves an object from the cache. If the object has expired or its recorded put version is less then the objVersion, then it will return null.

Parameters:

key - - the key to the cached object

objVersion - - the object version number to compare against

Returns:

the object for the key or null

onExpiredObject

protected void onExpiredObject(Object key)

Called when an object has been detected as expired or versioned out of existence.

Parameters:

key - - the key to the object

hasExpired

public boolean hasExpired(Object key,
                          long when)

Called to see if a cache entry has expired or not at a given point in time.

Parameters:

key - - the key to the cached object

when - - the time to do the comparision against

Returns:

true if the object has expired in the cache or cant be found in the cache.