Purple Code

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:

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

Documentation generated March 5 2003