Purple Code

com.purpletech.util
Class Cache

java.lang.Object
  |
  +--com.purpletech.util.Cache
All Implemented Interfaces:
java.lang.Runnable

public class Cache
extends java.lang.Object
implements java.lang.Runnable

An object cache that eventually times out its elements. The constructor automatically starts a background thread. You may subclass two important methods:

Note that load() and test() require the existence of a primary key object that contains all the information you'd ever need to uniquely identify an object. This key class will need to implement hashCode() and equals() correctly (like an EJB primary key class). The overriding load method will cast the key to the appropriate class type so you can read the data values.

You may also 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
 class Cache.Entry
          an entry in a cache.
 class Cache.StringKey
          A sample Primary Key class containing merely a string.
 
Field Summary
protected  long sleep
           
protected  long timeout
           
 
Constructor Summary
Cache()
           
Cache(long timeout)
           
 
Method Summary
protected  boolean expire(java.lang.Object key, Cache.Entry entry, 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
 long getEntered(java.lang.Object key)
          Convenience method to get the time this key's data was entered into the cache.
 Cache.Entry getEntry(java.lang.Object key)
          Get all information about this cache entry, including the object itself, and the times it was accessed and entered.
 java.util.Map getMap()
          returns an unmodifiable Map for the entries in the cache.
 int getSize()
           
 java.lang.Object load(java.lang.Object key)
          Callback that loads an object or otherwise generates it when it's needed.
 void put(java.lang.Object key, java.lang.Object data)
          Add an item to the cache explicitly.
 void remove(java.lang.Object key)
          Explicitly remove item from cache
 void run()
           
 void setSleep(long msec)
           
 void setTimeout(long msec)
           
 boolean test(java.lang.Object key, Cache.Entry current)
          Callback that provides an extra check as to whether an object needs to be reloaded.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

timeout

protected long timeout

sleep

protected long sleep
Constructor Detail

Cache

public Cache()

Cache

public Cache(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

setSleep

public void setSleep(long msec)
Parameters:
msec - the time that the expiry thread sleeps before waking up and checking for expirable items

put

public void put(java.lang.Object key,
                java.lang.Object data)
Add an item to the cache explicitly.


get

public java.lang.Object get(java.lang.Object key)
Get an item from the cache. If it (a) never existed, or (b) has been removed due to timeout, or (c) fails the test() test, then we call the load() method to get the value. We then store that value in the cache for next time.

Note that load() can return null, which means you must explicitly add objects to the cache.


getEntry

public Cache.Entry getEntry(java.lang.Object key)
Get all information about this cache entry, including the object itself, and the times it was accessed and entered. Normally you just use get().


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

getMap

public java.util.Map getMap()
returns an unmodifiable Map for the entries in the cache. Don't get confused between Map.Entry and Cache.Entry -- this map maps an id to a Cache.Entry.

Returns:
an unmodifiable Map for the entries in the cache

remove

public void remove(java.lang.Object key)
Explicitly remove item from cache


test

public boolean test(java.lang.Object key,
                    Cache.Entry current)
Callback that provides an extra check as to whether an object needs to be reloaded. For example, if the file's contents point to other files, then you need to write a tester that checks those other files too.

Parameters:
key - the key object for the desired data
current - the current data for this key in the cache
Returns:
true if the object is valid (fresh), false if it needs to be reloaded (stale)

load

public java.lang.Object load(java.lang.Object key)
Callback that loads an object or otherwise generates it when it's needed.


run

public void run()
Specified by:
run in interface java.lang.Runnable

expire

protected boolean expire(java.lang.Object key,
                         Cache.Entry entry,
                         long now)
Subclasses should override this to provide their own expiration heuristic.

Parameters:
key - key of object we're looking at
entry - entry of object we're looking at
now - current system time
Returns:
true if object should expire

Documentation generated March 5 2003