de.cismet.commons.ref

Class PurgingCache<K,V>

java.lang.Object

de.cismet.commons.ref.PurgingCache<K,V>

public final class PurgingCache<K,V>
extends Object

This class provides a simple key-value cache. The cache makes use of TimedSoftReferences to store the values to keys. Thus the values expire after a certain time if they have not already been collected before. The cache allows to define a custom time interval a value will be cached at most. It additionally provides means to purge stale entries from the cache. An entry is considered stale if an existing key does not map to a value at all (most likely because it has been collected before). Purge actions take place at a fixed interval which is can also be controlled.

Version:

1.0

Author:

martin.scholl@cismet.de

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_KEY_PURGE_INTERVAL The default key purge interval of the cache, 5 minutes.
static long	DEFAULT_VALUE_PURGE_INTERVAL The default value purge interval of the cache, 30 seconds.

Constructor Summary

Constructors

Constructor and Description
PurgingCache(Calculator<K,V> initialiser) Creates a new PurgingCache object.
PurgingCache(Calculator<K,V> initialiser, long valuePurgeInterval) Creates a new PurgingCache object.
PurgingCache(Calculator<K,V> initialiser, long keyPurgeInterval, long valuePurgeInterval) Creates a new PurgingCache object.
PurgingCache(Calculator<K,V> initialiser, long keyPurgeInterval, long valuePurgeInterval, boolean cacheNullValues) Creates a new PurgingCache object.

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all entries from the cache regardless of any purge interval setting.
<T extends K> V	get(T key) Gets the cached value for a given key.
long	getKeyPurgeInterval() Getter for the current keyPurgeInterval.
long	getValuePurgeInterval() Getter for the valuePurgeInterval that is currently used for newly initialised values.
boolean	isCacheNullValues() Getter for cacheNullValues that indicates whether null values calculated for a key will be cached or not.
void	setCacheNullValues(boolean cacheNullValues) Setter for cacheNullValues.
void	setKeyPurgeInterval(long keyPurgeInterval) Setter for the keyPurgeInterval.
void	setValuePurgeInterval(long valuePurgeInterval) Setter for the valuePurgeInterval.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_KEY_PURGE_INTERVAL

public static final long DEFAULT_KEY_PURGE_INTERVAL

The default key purge interval of the cache, 5 minutes.

See Also:

Constant Field Values

DEFAULT_VALUE_PURGE_INTERVAL

public static final long DEFAULT_VALUE_PURGE_INTERVAL

The default value purge interval of the cache, 30 seconds.

See Also:

Constant Field Values

Constructor Detail

PurgingCache

public PurgingCache(Calculator<K,V> initialiser)

Creates a new PurgingCache object. Using this constructor is similar to using PurgingCache(de.cismet.tools.Calculator, long, long) with DEFAULT_KEY_PURGE_INTERVAL as keyPurgeInterval and DEFAULT_VALUE_PURGE_INTERVAL as valuePurgeInterval.

Parameters:

initialiser - the Calculator instance that is able to create a value for a given key

PurgingCache

public PurgingCache(Calculator<K,V> initialiser,
                    long valuePurgeInterval)

Creates a new PurgingCache object. Using this constructor is similar to using PurgingCache(de.cismet.tools.Calculator, long, long) with DEFAULT_KEY_PURGE_INTERVAL as keyPurgeInterval.

Parameters:

initialiser - the Calculator instance that is able to create a value for a given key

valuePurgeInterval - the time in milliseconds that a cached value will be cached at most or 0 if purging of values (after a fixed amount of time) shall be disabled

PurgingCache

public PurgingCache(Calculator<K,V> initialiser,
                    long keyPurgeInterval,
                    long valuePurgeInterval)

Creates a new PurgingCache object. Using this constructor is similar to using PurgingCache(de.cismet.tools.Calculator, long, long, boolean) with false as cacheNullValues.

Parameters:

initialiser - the Calculator instance that is able to create a value for a given key

keyPurgeInterval - the time in milliseconds that lies between two purge actions or 0 if purging of keys shall be disabled

valuePurgeInterval - the time in milliseconds that a cached value will be cached at most or 0 if purging of values (after a fixed amount of time) shall be disabled

See Also:

Calculator, setKeyPurgeInterval(long), setValuePurgeInterval(long)

PurgingCache

public PurgingCache(Calculator<K,V> initialiser,
                    long keyPurgeInterval,
                    long valuePurgeInterval,
                    boolean cacheNullValues)

Creates a new PurgingCache object.

Parameters:

initialiser - the Calculator instance that is able to create a value for a given key

keyPurgeInterval - the time in milliseconds that lies between two purge actions or 0 if purging of keys shall be disabled

valuePurgeInterval - the time in milliseconds that a cached value will be cached at most or 0 if purging of values (after a fixed amount of time) shall be disabled

cacheNullValues - whether or not null values shall be cached

See Also:

Calculator, setKeyPurgeInterval(long), setValuePurgeInterval(long), setCacheNullValues(boolean)

Method Detail

get

public <T extends K> V get(T key)

Gets the cached value for a given key. If there exists a cached value it is returned, otherwise the Calculator instance provided in the constructor is responsible for creating a new value for the given key. The maximal time a value is cached is the current value returned by getValuePurgeInterval(). However, it is not guaranteed that the value stays that long in the cache as it makes use of SoftReferences to store the value.

NOTE: null keys are currently not supported.

Type Parameters:

T - any instance of K

Parameters:

key - the key to fetch a cached value for

Returns:

the value corresponding to the key (may be null)

Throws:

IllegalArgumentException - if the given key is null

CacheException - if the Calculator raises an exception during value creation

See Also:

setCacheNullValues(boolean)

getKeyPurgeInterval

public long getKeyPurgeInterval()

Getter for the current keyPurgeInterval.

Returns:

the time in milliseconds that lies between two purge actions or 0 if purging of keys is currently disabled.

See Also:

setKeyPurgeInterval(long)

setKeyPurgeInterval

public void setKeyPurgeInterval(long keyPurgeInterval)

Setter for the keyPurgeInterval. Every keyPurgeInterval milliseconds the cache will check for stale entries and remove them. The change takes effect immediately. A new purge action will take place in keyPurgeInterval milliseconds which means that any purge action that should have taken place is canceled. The value is expected to be in milliseconds. Any value below or equal to 0 will disable purging of keys.

Parameters:

keyPurgeInterval - the time in milliseconds that lies between two purge actions

getValuePurgeInterval

public long getValuePurgeInterval()

Getter for the valuePurgeInterval that is currently used for newly initialised values.

Returns:

the current valuePurgeInterval in milliseconds or 0 if purging of values is currently disabled.

See Also:

setValuePurgeInterval(long)

setValuePurgeInterval

public void setValuePurgeInterval(long valuePurgeInterval)

Setter for the valuePurgeInterval. The value that is set here will be used if any new reference to a value is created (during get(java.lang.Object). This implies that changing this value does not affect any existing (cached) references. The value is expected to be in milliseconds. Any value below or equal to 0 will disable purging of values.

Parameters:

valuePurgeInterval - the time in milliseconds after that a cached value will remain referenced if it is not accessed at all

isCacheNullValues

public boolean isCacheNullValues()

Getter for cacheNullValues that indicates whether null values calculated for a key will be cached or not.

Returns:

true if caching of null values is enabled, falseotherwise

setCacheNullValues

public void setCacheNullValues(boolean cacheNullValues)

Setter for cacheNullValues. The value that is set here will be used if any new reference to a value is created (during get(java.lang.Object). This implies that changing this value does not affect any existing (cached) references. If the parameter value is false and the value that is initially calculated during get() is null nothing will be cached which implies that any successive call to get() with the same key will cause the value to be calculated again. If the parameter value is true any null value will be treated like any other 'real' reference and thus will be cached and returned immediately for any successive call to get() with the same key.

Parameters:

cacheNullValues - true if caching of null values shall be enabled, false otherwise

clear

public void clear()

Removes all entries from the cache regardless of any purge interval setting.