org.cdlib.xtf.cache
Class Cache<K,V>

Object
  extended by Cache<K,V>
Direct Known Subclasses:
GeneratingCache, SimpleCache

public abstract class Cache<K,V>
extends Object

Cache is an abstract class used for code shared by SimpleCache and GeneratingCache. Contains the workhorse functions for maintaining a cache, expiring entries based on age or count, checking dependencies, and checking for a key.


Nested Class Summary
protected  class Cache.ListEntry
          An entry in the age list maintained by the cache
protected  class Cache.NullIterator
          Used to return an iterator that does nothing
 
Field Summary
protected  EmbeddedList ageList
          A list, kept sorted by descending age, of all the entries.
protected  HashMap<K,Cache.ListEntry> keyMap
          Maintains a mapping of key to ListEntry, for fast key lookups
private  int maxEntries
          Maximum number of entries the cache may contain
private  int maxTime
          Maximum amount of time (in seconds) an entry can stay in the cache without being used.
 
Constructor Summary
Cache(int maxEntries, int maxTime)
          Constructor - sets up the parameters of the cache.
 
Method Summary
protected  void cleanup()
          Maintains the maxEntries and maxTime constraints imposed on the cache.
 void clear()
          Remove all entries from the cache.
 boolean dependenciesValid(K key)
          Check the dependencies of a cache entry, if present.
 Iterator getDependencies(K key)
          Get the list of dependencies for a cache entry, if present.
 boolean has(K key)
          Checks if the cache currently contains an entry for the given key.
 long lastSet(K key)
          Gets the time the entry for the given key was created, or zero if the key isn't present.
protected  void logAction(String action, K key, V value)
          Derived classes can override this method to print out log messages when significant things happen (entries are added, removed, expired, etc.)
 V remove(K key)
          Remove an entry from the cache.
 int size()
          Tells how many entries are currently cached
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

maxEntries

private int maxEntries
Maximum number of entries the cache may contain


maxTime

private int maxTime
Maximum amount of time (in seconds) an entry can stay in the cache without being used.


keyMap

protected HashMap<K,Cache.ListEntry> keyMap
Maintains a mapping of key to ListEntry, for fast key lookups


ageList

protected EmbeddedList ageList
A list, kept sorted by descending age, of all the entries. This is used to find the least-recently-used entry to remove when the cache constraints (time or # of entries) are exceeded.

Constructor Detail

Cache

public Cache(int maxEntries,
             int maxTime)
Constructor - sets up the parameters of the cache.

Parameters:
maxEntries - Number of entries allowed. If additional entries are created, older ones will be removed. Zero means no limit.
maxTime - Time (in seconds) that a cache entry will remain. If the entry hasn't been used in that time, it is removed from the cache. Zero means no time limit.
Method Detail

has

public boolean has(K key)
Checks if the cache currently contains an entry for the given key. If an entry exists but has stale dependencies, it is removed and false is returned. Otherwise, if one exists it is freshened (i.e. its expiration countdown is reset).

Parameters:
key - The key to look for.
Returns:
true iff the key has a valid entry in the cache.

lastSet

public long lastSet(K key)
Gets the time the entry for the given key was created, or zero if the key isn't present. The time is number of milliseconds since the epoch, just like System.currentTimeMillis().

Parameters:
key - The key to look for
Returns:
The time (in milliseconds from the epoch) that the entry was created, or zero if not present.

dependenciesValid

public boolean dependenciesValid(K key)
Check the dependencies of a cache entry, if present.

Parameters:
key - The key to check
Returns:
true iff the cache entry for the key is still valid.

getDependencies

public Iterator getDependencies(K key)
Get the list of dependencies for a cache entry, if present.

Parameters:
key - The key to check
Returns:
An iterator that will produce each dependency, or null if no dependencies.

remove

public V remove(K key)
Remove an entry from the cache.

Parameters:
key - The key to look up
Returns:
The value that was held for the key, or null if not found.

clear

public void clear()
Remove all entries from the cache.


size

public int size()
Tells how many entries are currently cached


cleanup

protected void cleanup()
Maintains the maxEntries and maxTime constraints imposed on the cache. Schedules additional cleanup when necessary.


logAction

protected void logAction(String action,
                         K key,
                         V value)
Derived classes can override this method to print out log messages when significant things happen (entries are added, removed, expired, etc.)

Parameters:
action - What happened ("Added", "Removed", etc.)
key - The key involved in the action
value - The value involved in the action