org.ofbiz.base.util.cache
Class UtilCache<K,V>

java.lang.Object
  org.ofbiz.base.util.cache.UtilCache<K,V>

All Implemented Interfaces:

java.io.Serializable

public class UtilCache<K,V>
extends java.lang.Object
implements java.io.Serializable

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

See Also:

Serialized Form

Field Summary

CacheLineTable<K,V>	cacheLineTable A hashtable containing a CacheLine object with a value and a loadTime for each element.
protected static java.util.Map<java.lang.String,java.lang.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
protected java.util.Set<CacheListener<K,V>>	listeners The set of listeners to receive notifcations when items are modidfied(either delibrately or because they were expired).
protected int	maxInMemory
protected int	maxSize The maximum number of elements in the cache.
protected long	missCountExpired A count of the number of cache misses because it expired
protected long	missCountNotFound A count of the number of cache misses because it is not found in the cache
protected long	missCountSoftRef A count of the number of cache misses because it was cleared from the Soft Reference (ie garbage collection, etc)
static java.lang.String	module
protected java.lang.String	name The name of the UtilCache instance, is also the key for the instance in utilCacheTable.
protected long	removeHitCount A count of the number of cache hits on removes
protected long	removeMissCount A count of the number of cache misses on removes
protected boolean	useFileSystemStore Specifies whether or not to use file base stored for this cache, defautls to false
protected boolean	useSoftReference Specifies whether or not to use soft references for this cache, defaults to false
static java.util.Map<java.lang.String,UtilCache<?,?>>	utilCacheTable A static Map to keep track of all of the UtilCache instances.

Constructor Summary

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(int maxSize, long expireTime)
Constructor which specifies the maxSize and expireTime.

UtilCache(java.lang.String cacheName)
This constructor takes a name for the cache, puts itself in the utilCacheTable.

UtilCache(java.lang.String cacheName, boolean useSoftReference)
This constructor takes a name for the cache, puts itself in the utilCacheTable.

UtilCache(java.lang.String cacheName, int maxSize, int maxInMemory, long expireTime, boolean useSoftReference, boolean useFileSystemStore)
Constructor which specifies the cacheName as well as the maxSize, expireTime and useSoftReference.

UtilCache(java.lang.String cacheName, int maxSize, long expireTime)
Constructor which specifies the cacheName as well as the maxSize and expireTime.

UtilCache(java.lang.String cacheName, int maxSize, long expireTime, boolean useSoftReference)

Method Summary

void	addListener(CacheListener<K,V> listener) Adds an event listener for key removals
void	clear() Removes all elements from this cache
static void	clearAllCaches() Removes all elements from this cache
static void	clearCache(java.lang.String cacheName)
static void	clearCachesThatStartWith(java.lang.String startsWith)
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(java.lang.Object key) Returns a boolean specifying whether or not an element with the specified key is in the cache.
static <K,V> UtilCache<K,V>	findCache(java.lang.String cacheName)
V	get(java.lang.Object key) Gets an element from the cache according to the specified key.
java.util.Set<? extends K>	getCacheLineKeys() NOTE: this returns an unmodifiable copy of the keySet, so removing from here won't have an effect, and calling a remove while iterating through the set will not cause a concurrent modification exception.
java.util.Collection<? extends CacheLine<V>>	getCacheLineValues()
long	getExpireTime() return the current expire time for the cache elements
long	getHitCount() Returns the number of successful hits on the cache
protected CacheLine<V>	getInternal(java.lang.Object key, boolean countGet)
protected CacheLine<V>	getInternalNoCheck(java.lang.Object key)
long	getMaxSize() Returns the current maximum number of elements in the cache
long	getMissCountExpired() Returns the number of cache misses from entries that are expired
long	getMissCountNotFound() Returns the number of cache misses from entries that are not found in the cache
long	getMissCountSoftRef() Returns the number of cache misses from entries that are have had the soft reference cleared out (by garbage collector and such)
long	getMissCountTotal() Returns the number of cache misses caused by any reason
java.lang.String	getName() Getter for the name of the UtilCache instance.
protected java.lang.String	getNextDefaultIndex(java.lang.String cacheName)
static java.lang.String	getPropertyParam(java.util.ResourceBundle res, java.lang.String[] propNames, java.lang.String parameter)
long	getRemoveHitCount()
long	getRemoveMissCount()
long	getSizeInBytes()
boolean	getUseFileSystemStore()
boolean	getUseSoftReference() Return whether or not the cache lines should use a soft reference to the data
boolean	hasExpired(java.lang.Object key) Returns a boolean specifying whether or not the element corresponding to the key has expired.
protected void	noteAddition(K key, V newValue) Send a key addition event to all registered listeners
protected void	noteRemoval(K key, V oldValue) Send a key removal event to all registered listeners
protected void	noteUpdate(K key, V newValue, V oldValue) Send a key update event to all registered listeners
V	put(K key, V value) Puts or loads the passed element into the cache
V	put(K key, V value, long expireTime) Puts or loads the passed element into the cache
V	remove(java.lang.Object key) Removes an element from the cache according to the specified key
protected V	removeInternal(java.lang.Object key, boolean countRemove) This is used for internal remove calls because we only want to count external calls
void	removeListener(CacheListener<K,V> listener) Removes an event listener for key removals
void	setExpireTime(long expireTime) Sets the expire time for the cache elements.
void	setMaxSize(int maxSize) Sets the maximum number of elements in the cache.
protected void	setPropertiesParams(java.lang.String cacheName)
void	setPropertiesParams(java.lang.String[] propNames)
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(java.lang.String cacheName, java.lang.Object key) Checks for a non-expired key in a specific cache
java.util.List<V>	values()

Methods inherited from class java.lang.Object

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

Field Detail

module

public static final java.lang.String module

utilCacheTable

public static java.util.Map<java.lang.String,UtilCache<?,?>> utilCacheTable

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

defaultIndices

protected static java.util.Map<java.lang.String,java.lang.Integer> defaultIndices

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

name

protected java.lang.String name

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

cacheLineTable

public CacheLineTable<K,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

missCountNotFound

protected long missCountNotFound

A count of the number of cache misses because it is not found in the cache

missCountExpired

protected long missCountExpired

A count of the number of cache misses because it expired

missCountSoftRef

protected long missCountSoftRef

A count of the number of cache misses because it was cleared from the Soft Reference (ie garbage collection, etc)

removeHitCount

protected long removeHitCount

A count of the number of cache hits on removes

removeMissCount

protected long removeMissCount

A count of the number of cache misses on removes

maxSize

protected int 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.

maxInMemory

protected int maxInMemory

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

useFileSystemStore

protected boolean useFileSystemStore

Specifies whether or not to use file base stored for this cache, defautls to false

listeners

protected java.util.Set<CacheListener<K,V>> listeners

The set of listeners to receive notifcations when items are modidfied(either delibrately or because they were expired).

Constructor Detail

UtilCache

public UtilCache(java.lang.String cacheName,
                 int maxSize,
                 int maxInMemory,
                 long expireTime,
                 boolean useSoftReference,
                 boolean useFileSystemStore)

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(java.lang.String cacheName,
                 int maxSize,
                 long expireTime,
                 boolean useSoftReference)

UtilCache

public UtilCache(java.lang.String cacheName,
                 int 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(int 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(java.lang.String cacheName,
                 boolean useSoftReference)

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(java.lang.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 java.lang.String getNextDefaultIndex(java.lang.String cacheName)

getPropertyParam

public static java.lang.String getPropertyParam(java.util.ResourceBundle res,
                                                java.lang.String[] propNames,
                                                java.lang.String parameter)

setPropertiesParams

protected void setPropertiesParams(java.lang.String cacheName)

setPropertiesParams

public void setPropertiesParams(java.lang.String[] propNames)

put

public V 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

put

public V put(K key,
             V value,
             long expireTime)

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

expireTime - how long to keep this key in the cache

get

public V get(java.lang.Object 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

getInternalNoCheck

protected CacheLine<V> getInternalNoCheck(java.lang.Object key)

getInternal

protected CacheLine<V> getInternal(java.lang.Object key,
                                   boolean countGet)

values

public java.util.List<V> values()

getSizeInBytes

public long getSizeInBytes()

remove

public V remove(java.lang.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

removeInternal

protected V removeInternal(java.lang.Object key,
                           boolean countRemove)

This is used for internal remove calls because we only want to count external calls

clear

public void clear()

Removes all elements from this cache

clearAllCaches

public static void clearAllCaches()

Removes all elements from this cache

getName

public java.lang.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

getMissCountNotFound

public long getMissCountNotFound()

Returns the number of cache misses from entries that are not found in the cache

Returns:

The number of cache misses

getMissCountExpired

public long getMissCountExpired()

Returns the number of cache misses from entries that are expired

Returns:

The number of cache misses

getMissCountSoftRef

public long getMissCountSoftRef()

Returns the number of cache misses from entries that are have had the soft reference cleared out (by garbage collector and such)

Returns:

The number of cache misses

getMissCountTotal

public long getMissCountTotal()

Returns the number of cache misses caused by any reason

Returns:

The number of cache misses

getRemoveHitCount

public long getRemoveHitCount()

getRemoveMissCount

public long getRemoveMissCount()

clearCounters

public void clearCounters()

Clears the hit and miss counters

setMaxSize

public void setMaxSize(int 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

getUseFileSystemStore

public boolean getUseFileSystemStore()

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(java.lang.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

getCacheLineKeys

public java.util.Set<? extends K> getCacheLineKeys()

NOTE: this returns an unmodifiable copy of the keySet, so removing from here won't have an effect, and calling a remove while iterating through the set will not cause a concurrent modification exception. This behavior is necessary for now for the persisted cache feature.

getCacheLineValues

public java.util.Collection<? extends CacheLine<V>> getCacheLineValues()

hasExpired

public boolean hasExpired(java.lang.Object 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

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

noteAddition

protected void noteAddition(K key,
                            V newValue)

Send a key addition event to all registered listeners

noteRemoval

protected void noteRemoval(K key,
                           V oldValue)

Send a key removal event to all registered listeners

noteUpdate

protected void noteUpdate(K key,
                          V newValue,
                          V oldValue)

Send a key update event to all registered listeners

addListener

public void addListener(CacheListener<K,V> listener)

Adds an event listener for key removals

removeListener

public void removeListener(CacheListener<K,V> listener)

Removes an event listener for key removals

clearExpiredFromAllCaches

public static void clearExpiredFromAllCaches()

Clears all expired cache entries from all caches

validKey

public static boolean validKey(java.lang.String cacheName,
                               java.lang.Object key)

Checks for a non-expired key in a specific cache

clearCachesThatStartWith

public static void clearCachesThatStartWith(java.lang.String startsWith)

clearCache

public static void clearCache(java.lang.String cacheName)

findCache

public static <K,V> UtilCache<K,V> findCache(java.lang.String cacheName)