com.purpletech.util
Class TimeoutMap

java.lang.Object
  |
  +--java.util.AbstractMap
        |
        +--com.purpletech.util.TimeoutMap

All Implemented Interfaces:

java.util.Map, java.lang.Runnable

public class TimeoutMap

extends java.util.AbstractMap

implements java.lang.Runnable

A Map that eventually times out (removes) its elements.

The constructor automatically starts a background (daemon) thread to handle expiry.

You may pass in an existing Map as backing store; this could be, e.g., a WeakHashMap, or a Map that knows how to load its contents from elsewhere.

You may subclass the following methods:

• expire() determines if an item has expired and should be removed from the cache

You may override expire() to implement your own expiration heuristic (e.g. LMF, which is ``last modified factor'' (LMF), calculated as the ratio of two time periods: LMF = (time since last validated) / (age when last validated) -- if LMF>some threshold (i.e. 20%), then the cached data is considered stale)

Nested Class Summary

static class

TimeoutMap.Info Information about an entry in the cache.

Field Summary

protected long	tempo
protected long	timeout

Constructor Summary

TimeoutMap()
Allow this object to create its own backing store.

TimeoutMap(long timeout)

TimeoutMap(java.util.Map contents)
Pass this constructor an implementation instance (for SortedMap, e.g.) -- does *not* follow conventions for java.util.Map, which would make a copy of the passed Map's contents.

TimeoutMap(java.util.Map contents, long timeout)

Method Summary

java.util.Set	entrySet()
protected boolean	expire(java.lang.Object key, TimeoutMap.Info info, long now) Subclasses should override this to provide their own expiration heuristic.
java.lang.Object	get(java.lang.Object key) Get an item from the cache.
long	getAccessed(java.lang.Object key) Convenience method to get the time this key's data was last accessed
java.lang.Object	getClean(java.lang.Object key) Get an item from the cache.
long	getEntered(java.lang.Object key) Convenience method to get the time this key's data was entered into the cache.
TimeoutMap.Info	getInfo(java.lang.Object key) Get all information about this cache entry, including the times it was accessed and entered.
int	getSize()
java.lang.Object	put(java.lang.Object key, java.lang.Object data) Add an item to the cache explicitly.
java.lang.Object	remove(java.lang.Object key) Explicitly remove item from cache
void	run()
void	setTempo(long msec)
void	setTimeout(long msec)

Methods inherited from class java.util.AbstractMap

clear, clone, containsKey, containsValue, equals, hashCode, isEmpty, keySet, putAll, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

timeout

protected long timeout

tempo

protected long tempo

Constructor Detail

TimeoutMap

public TimeoutMap()

Allow this object to create its own backing store. Spawns expiry thread.

TimeoutMap

public TimeoutMap(java.util.Map contents)

Pass this constructor an implementation instance (for SortedMap, e.g.) -- does *not* follow conventions for java.util.Map, which would make a copy of the passed Map's contents. Instead, call addAll().

TimeoutMap

public TimeoutMap(long timeout)

TimeoutMap

public TimeoutMap(java.util.Map contents,
                  long timeout)

Method Detail

setTimeout

public void setTimeout(long msec)

Parameters:

msec - the maximum time an item can sit in the cache without being accessed before it gets removed

setTempo

public void setTempo(long msec)

Parameters:

msec - the time that the expiry thread sleeps before waking up and checking for expirable items (hence "tempo")

entrySet

public java.util.Set entrySet()

Specified by:

entrySet in interface java.util.Map

Specified by:

entrySet in class java.util.AbstractMap

put

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

Add an item to the cache explicitly.

Specified by:

put in interface java.util.Map

Overrides:

put in class java.util.AbstractMap

get

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

Get an item from the cache. Updates the "last time accessed" record for the requested item.

Specified by:

get in interface java.util.Map

Overrides:

get in class java.util.AbstractMap

Returns:

null if not found

getClean

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

Get an item from the cache. Does not update the "last time accessed" record for the requested item.

Returns:

null if not found

getInfo

public TimeoutMap.Info getInfo(java.lang.Object key)

Get all information about this cache entry, including the times it was accessed and entered. Normally you just use get() to get the data.

getEntered

public long getEntered(java.lang.Object key)

Convenience method to get the time this key's data was entered into the cache.

getAccessed

public long getAccessed(java.lang.Object key)

Convenience method to get the time this key's data was last accessed

getSize

public int getSize()

Returns:

number of items in the cache

remove

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

Explicitly remove item from cache

Specified by:

remove in interface java.util.Map

Overrides:

remove in class java.util.AbstractMap

run

public void run()

Specified by:

run in interface java.lang.Runnable

expire

protected boolean expire(java.lang.Object key,
                         TimeoutMap.Info info,
                         long now)

Subclasses should override this to provide their own expiration heuristic.

Parameters:

key - key of object we're looking at

info - info of object we're looking at

now - current system time

Returns:

true if object should expire