org.melati.poem.util
Class Cache

java.lang.Object
  org.melati.poem.util.Cache

public final class Cache
extends Object

A store whose capacity has a guaranteed lower limit but whose upper limit is bounded by the amount of memory available to the JVM. The lower limit can be adjusted after cache creation. Elements added to the cache once the cache size exceeds the lower limit (the cache is full) force the least recently used (LRU) item off the held list. Items which are removed from the held list are not deleted but converted to soft references: available to be retrieved if they are not garbage collected first. The cache cannot contain nulls, as there would be no mechanism to distinguish between a held null value and an unheld value. There is no mechanism for invalidating the cache, reducing its size to zero mearly allows all its members to be garbage collected. Ideally, having been created, objects remain in the cache; however this is impracticable when the possible size of the sum of cached objects exceeds available memory. The performance of the cache depends upon the pattern of accesses to it. An LRU cache such as this assumes a normal distribution of accesses. The state of the cache can be monitored by using the reporting objects, see for example org.melati.admin.Status.

Nested Class Summary

class	Cache.InconsistencyException Thrown if one or more problems are discovered with cache consistency.
class	Cache.Info A class which enables reporting upon the state of the Cache.

Constructor Summary

Cache(int maxSize)
Constructor with maximum size.

Method Summary

void	delete(Object key) Remove from cache.
void	dump() Output to syserr.
void	dumpAnalysis() Dump to Syserr.
Object	get(Object key) Return an object from the Cache, null if not found.
Cache.Info	getInfo()
Enumeration<Object>	getReport() Report on the status of the cache.
int	getSize() Get maximum size of Cache.
void	iterate(Procedure f) Apply function to all items in cache, only ignoring items where the value has been garbage collected.
void	put(Object key, Object value) Add an Object to the cache.
void	setSize(int maxSize) Set maximum size of Cache.
void	trim(int maxSize_P) Reduce number of units held in the cache, without changing its size.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Cache

public Cache(int maxSize)

Constructor with maximum size.

Parameters:

maxSize - maximum size cache may grow to

Method Detail

setSize

public void setSize(int maxSize)

Set maximum size of Cache.

Parameters:

maxSize - maximum size cache may grow to

getSize

public int getSize()

Get maximum size of Cache.

trim

public void trim(int maxSize_P)

Reduce number of units held in the cache, without changing its size. This is intended for cache maintenance, enabling only the most frequently used items to remain in the cache, whilst the others are dropped; where dropped means converted to a soft reference.

Parameters:

maxSize_P - maximum number of units to hold

delete

public void delete(Object key)

Remove from cache. If key is not in the cache as a HeldNode then does nothing.

Parameters:

key - cache key field

put

public void put(Object key,
                Object value)

Add an Object to the cache.

Parameters:

key - the Object to use as a lookup

value - the Object to put in the cache

get

public Object get(Object key)

Return an object from the Cache, null if not found.

Parameters:

key - the cache key

Returns:

the object or null if not in cache

iterate

public void iterate(Procedure f)

Apply function to all items in cache, only ignoring items where the value has been garbage collected.

Parameters:

f - Procedure to apply to all members of cache

getReport

public Enumeration<Object> getReport()

Report on the status of the cache.

Returns:

an Enumeration of report lines

getInfo

public Cache.Info getInfo()

Returns:

a new Info object

dumpAnalysis

public void dumpAnalysis()

Dump to Syserr.

dump

public void dump()

Output to syserr.