org.xorm.cache
Class LRUCache

java.lang.Object
  |
  +--org.xorm.cache.LRUCache

All Implemented Interfaces:

Configurable, DataCache

public class LRUCache

extends Object

implements DataCache

An LRU Cache with a hard and soft reference limit. Objects that exceed the hard limit are stored as soft references, and objects that exceed the soft limit are discarded from the cache. The hard limit and soft limit are additive, in that hard limit is the number of objects to store with hard references, and the soft limit is the number of objects to store with soft references, exclusive of the hard limit. Hence, a hard limit of 10, and soft limit of 20 would create a (possible) cache size of 30. Since items stored as soft references are subject to collection by the Garbage collector, the soft reference cache will often be smaller than the limit set on it. It is possible to also configure the cache to behave as only a soft or hard cache by simply configuring the hard and soft limit appropriately. See the additional documentation below about how to configure this. This class uses a referenceQueue to insure that values removed from the This class can also be configured to log its statistics to its logger (defined as Logger.getLogger("org.xorm.cache.LRUCache")) Normally, this class would be used by adding the following properties to the properties files given to xorm at startup:

• org.xorm.cache.DataCacheClass=org.xorm.cache.LRUCache

The following properties will override the default values in this class:

• org.xorm.cache.LRUCache.hardSize=<non-negative intValue>
• org.xorm.cache.LRUCache.softSize=<intValue>
• org.xorm.cache.LRUCache.logInterval=<intValue>

See setProperties for a description of the meaning of these properties.

Author:

Harry Evans

Field Summary

static int	DEFAULT_HARD_SIZE
static long	DEFAULT_LOG_INTERVAL
static int	DEFAULT_SOFT_SIZE

Constructor Summary

LRUCache()
Construct an LRUCache using DEFAULT_HARD_SIZE, DEFAULT_SOFT_SIZE, and DEFAULT_LOG_INTERVAL.

LRUCache(int hardSize, int softSize, long aLogInterval)
Construct a LRUCache.

Method Summary

void	add(Row row) Adds or replaces the Row in the cache.
void	addAll(Collection c) Optional method to add a collection of objects to the cache all at once.
Row	get(Table table, Object aPrimaryKey) Retrieves a cloned copy of the Row from the cache with the matching primary key.
void	log() Optional method for use by external classes to force logging of the cache usage statistics regardless of the value of logInterval.
void	remove(Row row) Removes a Row from the cache by its primary key.
Object	removeValue(Object value) Optional method to remove a value from the cache.
void	setFactory(InterfaceManagerFactory factory)
void	setProperties(Properties props) This method is called by XORM after reflectively instantiating the class.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_HARD_SIZE

public static final int DEFAULT_HARD_SIZE

See Also:

Constant Field Values

DEFAULT_SOFT_SIZE

public static final int DEFAULT_SOFT_SIZE

See Also:

Constant Field Values

DEFAULT_LOG_INTERVAL

public static final long DEFAULT_LOG_INTERVAL

See Also:

Constant Field Values

Constructor Detail

LRUCache

public LRUCache(int hardSize,
                int softSize,
                long aLogInterval)

Construct a LRUCache. This method is provided primarily for use when programatically assigning the cache that XORM will use. The default constructor is usually the one that gets used.

Parameters:

hardSize - The number of objects to keep hard references to. If this number is greater than 0, keep references to that number of objects with hard references. Objects that are discarded from the hard cache will be put into soft cache, if soft cache does not have a size of 0. If this value is 0, do not create a hard cache. An exception is thrown if this value is less than 0.

softSize - The number of objects to keep soft references to. If this number is greater than 0, keep references to that number of objects with soft references. Objects that are discarded from the soft cache, either through lack of space, or through garbage collection, are discarded completely from the cache. If this value is 0, do not create a soft cache. If this value is less than 0, the number of references stored will be limited to the amount of memory in the system, and how aggressive the garbage collector is.

aLogInterval - the amount of time in milliseconds to log usage statistics to the logger ("org.xorm.cache.LRUCache"). If this value is 0, always log. If this value is a negative number, never log. If this value is positive, log whenever that number of milliseconds has elapsed and the cache is accessed. Logging is done on a best effort basis, and does not use a background thread. Therefore, if the cache is not accessed for time greater than the log interval, no values will be logged.

Throws:

RuntimeException - if the hardSize is less than 0, or the hardSize and softSize are both 0

LRUCache

public LRUCache()

Construct an LRUCache using DEFAULT_HARD_SIZE, DEFAULT_SOFT_SIZE, and DEFAULT_LOG_INTERVAL. This constructor is provided to enable reflective instantiation of the cache. It is normally used in combination with a call to setProperties, which will result in the cache extracting (possibly) different values than the default with which to run.

Method Detail

setProperties

public void setProperties(Properties props)

This method is called by XORM after reflectively instantiating the class. This method looks for the following properties:

• org.xorm.cache.LRUCache.hardSize
• org.xorm.cache.LRUCache.softSize
• org.xorm.cache.LRUCache.logInterval

Any property that isn't found will have the class default value assigned to it.

Specified by:

setProperties in interface Configurable

Parameters:

props - The Properties object (possibly) containing values to use for hardSize, softSize, and logInterval.

setFactory

public void setFactory(InterfaceManagerFactory factory)

Specified by:

setFactory in interface Configurable

add

public void add(Row row)

Description copied from interface: DataCache

Adds or replaces the Row in the cache. If the Table does not have a primary key defined, the implementation is not required to cache it.

Specified by:

add in interface DataCache

addAll

public void addAll(Collection c)

Optional method to add a collection of objects to the cache all at once. Not currently used by xorm or defined by the xorm interface.

Parameters:

c - A Collection of rows to be added to the cache. The Rows will be added in Iterator order.

get

public Row get(Table table,
               Object aPrimaryKey)

Retrieves a cloned copy of the Row from the cache with the matching primary key.

Specified by:

get in interface DataCache

Returns:

a row matching the criteria, or null

log

public void log()

Optional method for use by external classes to force logging of the cache usage statistics regardless of the value of logInterval.

removeValue

public Object removeValue(Object value)

Optional method to remove a value from the cache. Since all objects removed are Rows, this method should not be called directly in the near future.

remove

public void remove(Row row)

Description copied from interface: DataCache

Removes a Row from the cache by its primary key. If no matching row exists, no change is made. Implementations of this method should use the .equals() operator for Row comparisons.

Specified by:

remove in interface DataCache