org.ofbiz.core.util

Class UtilCache<K,V>

java.lang.Object

org.ofbiz.core.util.UtilCache<K,V>

public class UtilCache<K,V>
extends Object

Generalized caching utility. Provides a number of caching features:

• Limited or unlimited element capacity
• If limited, removes elements with the LRU (Least Recently Used) algorithm
• Keeps track of when each element was loaded into the cache
• Using the expireTime can report whether a given element has expired
• Counts misses and hits

Since:

2.0

Version:

$Revision: 1.1 $

Author:

David E. Jones

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UtilCache.CacheLine<T>

Field Summary

Fields

Modifier and Type	Field and Description
Map<K,UtilCache.CacheLine<V>>	cacheLineTable A hashtable containing a CacheLine object with a value and a loadTime for each element.
protected static Map<String,Integer>	defaultIndices An index number appended to utilCacheTable names when there are conflicts.
protected long	expireTime Specifies the amount of time since initial loading before an element will be reported as expired.
protected long	hitCount A count of the number of cache hits
LinkedList<K>	keyLRUList A list of the elements order by Least Recent Use
protected long	maxSize The maximum number of elements in the cache.
protected long	missCount A count of the number of cache misses
protected String	name The name of the UtilCache instance, is also the key for the instance in utilCacheTable.
protected boolean	useSoftReference Specifies whether or not to use soft references for this cache, defaults to false
static Map<String,UtilCache<?,?>>	utilCacheTable A static Map to keep track of all of the UtilCache instances.

Constructor Summary

Constructors

Constructor and Description
UtilCache() Default constructor, all members stay at default values as defined in cache.properties, or the defaults in this file if cache.properties is not found, or there are no 'default' entries in it.
UtilCache(long maxSize, long expireTime) Constructor which specifies the maxSize and expireTime.
UtilCache(String cacheName) This constructor takes a name for the cache, puts itself in the utilCacheTable.
UtilCache(String cacheName, long maxSize, long expireTime) Constructor which specifies the cacheName as well as the maxSize and expireTime.
UtilCache(String cacheName, long maxSize, long expireTime, boolean useSoftReference) Constructor which specifies the cacheName as well as the maxSize, expireTime and useSoftReference.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Removes all elements from this cache
static void	clearAllCaches() Removes all elements from this cache
void	clearCounters() Clears the hit and miss counters
void	clearExpired() Clears all expired cache entries; also clear any cache entries where the SoftReference in the CacheLine object has been cleared by the gc
static void	clearExpiredFromAllCaches() Clears all expired cache entries from all caches
boolean	containsKey(Object key) Returns a boolean specifying whether or not an element with the specified key is in the cache.
V	get(K key) Gets an element from the cache according to the specified key.
long	getExpireTime() return the current expire time for the cache elements
long	getHitCount() Returns the number of successful hits on the cache
long	getMaxSize() Returns the current maximum number of elements in the cache
long	getMissCount() Returns the number of cache misses
String	getName() Getter for the name of the UtilCache instance.
protected String	getNextDefaultIndex(String cacheName)
boolean	getUseSoftReference() Return whether or not the cache lines should use a soft reference to the data
boolean	hasExpired(K key) Returns a boolean specifying whether or not the element corresponding to the key has expired.
protected boolean	hasExpired(UtilCache.CacheLine<V> line)
void	put(K key, V value) Puts or loads the passed element into the cache
Object	remove(Object key) Removes an element from the cache according to the specified key
void	setExpireTime(long expireTime) Sets the expire time for the cache elements.
void	setMaxSize(long maxSize) Sets the maximum number of elements in the cache.
protected void	setPropertiesParams(String cacheName)
void	setUseSoftReference(boolean useSoftReference) Set whether or not the cache lines should use a soft reference to the data
long	size() Returns the number of elements currently in the cache
static boolean	validKey(String cacheName, Object key) Checks for a non-expired key in a specific cache

Methods inherited from class java.lang.Object

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

Field Detail

utilCacheTable

public static Map<String,UtilCache<?,?>> utilCacheTable

A static Map to keep track of all of the UtilCache instances.

defaultIndices

protected static Map<String,Integer> defaultIndices

An index number appended to utilCacheTable names when there are conflicts.

name

protected String name

The name of the UtilCache instance, is also the key for the instance in utilCacheTable.

keyLRUList

public LinkedList<K> keyLRUList

A list of the elements order by Least Recent Use

cacheLineTable

public Map<K,UtilCache.CacheLine<V>> cacheLineTable

A hashtable containing a CacheLine object with a value and a loadTime for each element.

hitCount

protected long hitCount

A count of the number of cache hits

missCount

protected long missCount

A count of the number of cache misses

maxSize

protected long maxSize

The maximum number of elements in the cache. If set to 0, there will be no limit on the number of elements in the cache.

expireTime

protected long expireTime

Specifies the amount of time since initial loading before an element will be reported as expired. If set to 0, elements will never expire.

useSoftReference

protected boolean useSoftReference

Specifies whether or not to use soft references for this cache, defaults to false

Constructor Detail

UtilCache

public UtilCache(String cacheName,
         long maxSize,
         long expireTime,
         boolean useSoftReference)

Constructor which specifies the cacheName as well as the maxSize, expireTime and useSoftReference. The passed maxSize, expireTime and useSoftReference will be overridden by values from cache.properties if found.

Parameters:

maxSize - The maxSize member is set to this value

expireTime - The expireTime member is set to this value

cacheName - The name of the cache.

useSoftReference - Specifies whether or not to use soft references for this cache.

UtilCache

public UtilCache(String cacheName,
         long maxSize,
         long expireTime)

Constructor which specifies the cacheName as well as the maxSize and expireTime. The passed maxSize and expireTime will be overridden by values from cache.properties if found.

Parameters:

maxSize - The maxSize member is set to this value

expireTime - The expireTime member is set to this value

cacheName - The name of the cache.

UtilCache

public UtilCache(long maxSize,
         long expireTime)

Constructor which specifies the maxSize and expireTime.

Parameters:

maxSize - The maxSize member is set to this value

expireTime - The expireTime member is set to this value

UtilCache

public UtilCache(String cacheName)

This constructor takes a name for the cache, puts itself in the utilCacheTable. It also uses the cacheName to lookup the initialization parameters from cache.properties.

Parameters:

cacheName - The name of the cache.

UtilCache

public UtilCache()

Default constructor, all members stay at default values as defined in cache.properties, or the defaults in this file if cache.properties is not found, or there are no 'default' entries in it.

Method Detail

getNextDefaultIndex

protected String getNextDefaultIndex(String cacheName)

setPropertiesParams

protected void setPropertiesParams(String cacheName)

put

public void put(K key,
       V value)

Puts or loads the passed element into the cache

Parameters:

key - The key for the element, used to reference it in the hastables and LRU linked list

value - The value of the element

get

public V get(K key)

Gets an element from the cache according to the specified key. If the requested element hasExpired, it is removed before it is looked up which causes the function to return null.

Parameters:

key - The key for the element, used to reference it in the hastables and LRU linked list

Returns:

The value of the element specified by the key

remove

public Object remove(Object key)

Removes an element from the cache according to the specified key

Parameters:

key - The key for the element, used to reference it in the hastables and LRU linked list

Returns:

The value of the removed element specified by the key

clear

public void clear()

Removes all elements from this cache

clearAllCaches

public static void clearAllCaches()

Removes all elements from this cache

getName

public String getName()

Getter for the name of the UtilCache instance.

Returns:

The name of the instance

getHitCount

public long getHitCount()

Returns the number of successful hits on the cache

Returns:

The number of successful cache hits

getMissCount

public long getMissCount()

Returns the number of cache misses

Returns:

The number of cache misses

clearCounters

public void clearCounters()

Clears the hit and miss counters

setMaxSize

public void setMaxSize(long maxSize)

Sets the maximum number of elements in the cache. If 0, there is no maximum.

Parameters:

maxSize - The maximum number of elements in the cache

getMaxSize

public long getMaxSize()

Returns the current maximum number of elements in the cache

Returns:

The maximum number of elements in the cache

setExpireTime

public void setExpireTime(long expireTime)

Sets the expire time for the cache elements. If 0, elements never expire.

Parameters:

expireTime - The expire time for the cache elements

getExpireTime

public long getExpireTime()

return the current expire time for the cache elements

Returns:

The expire time for the cache elements

setUseSoftReference

public void setUseSoftReference(boolean useSoftReference)

Set whether or not the cache lines should use a soft reference to the data

getUseSoftReference

public boolean getUseSoftReference()

Return whether or not the cache lines should use a soft reference to the data

size

public long size()

Returns the number of elements currently in the cache

Returns:

The number of elements currently in the cache

containsKey

public boolean containsKey(Object key)

Returns a boolean specifying whether or not an element with the specified key is in the cache. If the requested element hasExpired, it is removed before it is looked up which causes the function to return false.

Parameters:

key - The key for the element, used to reference it in the hastables and LRU linked list

Returns:

True is the cache contains an element corresponding to the specified key, otherwise false

hasExpired

public boolean hasExpired(K key)

Returns a boolean specifying whether or not the element corresponding to the key has expired. Only returns true if element is in cache and has expired. Error conditions return false, if no expireTable entry, returns true. Always returns false if expireTime <= 0. Also, if SoftReference in the CacheLine object has been cleared by the gc return true.

Parameters:

key - The key for the element, used to reference it in the hastables and LRU linked list

Returns:

True is the element corresponding to the specified key has expired, otherwise false

hasExpired

protected boolean hasExpired(UtilCache.CacheLine<V> line)

clearExpired

public void clearExpired()

Clears all expired cache entries; also clear any cache entries where the SoftReference in the CacheLine object has been cleared by the gc

clearExpiredFromAllCaches

public static void clearExpiredFromAllCaches()

Clears all expired cache entries from all caches

validKey

public static boolean validKey(String cacheName,
               Object key)

Checks for a non-expired key in a specific cache