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:

• test() performs additional checks to see if we need to refresh the requested object
• load() loads in the data (from wherever) based on the key

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