er.extensions.foundation

Class ERXExpiringCache<K,V>

java.lang.Object

er.extensions.foundation.ERXExpiringCache<K,V>

public class ERXExpiringCache<K,V>
extends Object

Cache that expires its entries based on time or version changes. Version can be any object that represents the current state of a cached value. When retrieving the value, you can retrieve it with a version key. If the version key used in the retrieval does not match the original version key of the object in the cache, then the cache will invalidate the value for that key and return null. An example version key might be the count of an array, if the count changes, you want to invalidate the cached object. Note that on a time-expiring cache, if you do not use the reaper with startBackgroundExpiration(), or manually call removeStaleEntries(), unexpired entries will remain in the cache for the lifetime of the cache.

Author:

ak, mschrag

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ERXExpiringCache.Entry<V>
protected static class	ERXExpiringCache.GrimReaper The reaper runnable for ERXExpiringCache.

Field Summary

Fields

Modifier and Type	Field and Description
static long	NO_TIMEOUT Designates that no timeout was specified.
static Object	NO_VERSION Designates that no explicit version was specified.

Constructor Summary

Constructors

Constructor and Description
ERXExpiringCache() Constructs an ERXExpiringCache with a 60 second expiration.
ERXExpiringCache(long expiryTimeInSeconds) Constructs an ERXExpiringCache with a cleanup time that matches expiryTimeInSeconds.
ERXExpiringCache(long expiryTimeInSeconds, long cleanupPauseInSeconds)

Method Summary

Modifier and Type	Method and Description
NSArray<K>	allKeys() Returns all keys.
protected ERXExpiringCache.Entry<V>	entryForKey(K key)
boolean	isStale(K key) Returns whether or not the object for the given key is a stale cache entry.
boolean	isStaleWithVersion(K key, Object currentVersionKey) Returns whether or not the object for the given key is a stale cache entry given the context of the current version of the key.
V	objectForKey(K key) Returns the value of the given key with an unspecified version.
V	objectForKeyWithVersion(K key, Object currentVersionKey) Returns the value of the given key passing in the current version of the cache value.
protected static ERXExpiringCache.GrimReaper	reaper() Returns the repear for all ERXExpringCaches.
void	removeAllObjects() Removes all the objects in this cache.
protected void	removeEntryForKey(ERXExpiringCache.Entry<V> entry, K key)
V	removeObjectForKey(K key) Removes the object for the given key.
void	removeStaleEntries() Removes all stale entries.
protected void	setEntryForKey(ERXExpiringCache.Entry<V> entry, K key)
void	setObjectForKey(V object, K key) Sets the object for the specified key in this cache with no version specified.
void	setObjectForKeyWithVersion(V object, K key, Object currentVersionKey) Sets the object for the specified key and current version key.
void	setObjectForKeyWithVersion(V object, K key, Object currentVersionKey, long expirationTime) Sets the object for the specified key and current version key.
void	startBackgroundExpiration() Adds this cache to the background thread that reaps time-expired entries from expiring caches.
void	stopBackgroundExpiration() Stops the background reaper for this cache.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

NO_TIMEOUT

public static final long NO_TIMEOUT

Designates that no timeout was specified.

See Also:

Constant Field Values

NO_VERSION

public static final Object NO_VERSION

Designates that no explicit version was specified.

Constructor Detail

ERXExpiringCache

public ERXExpiringCache()

Constructs an ERXExpiringCache with a 60 second expiration.

ERXExpiringCache

public ERXExpiringCache(long expiryTimeInSeconds)

Constructs an ERXExpiringCache with a cleanup time that matches expiryTimeInSeconds.

Parameters:

expiryTimeInSeconds - the lifetime in seconds of an object in the cache or NO_TIMEOUT

ERXExpiringCache

public ERXExpiringCache(long expiryTimeInSeconds,
                        long cleanupPauseInSeconds)

Parameters:

expiryTimeInSeconds - the lifetime in seconds of an object in the cache or NO_TIMEOUT

cleanupPauseInSeconds - the number of seconds to pause between cleanups

Method Detail

removeAllObjects

public void removeAllObjects()

Removes all the objects in this cache.

setObjectForKey

public void setObjectForKey(V object,
                            K key)

Sets the object for the specified key in this cache with no version specified.

Parameters:

object - the value to set

key - the lookup key

setObjectForKeyWithVersion

public void setObjectForKeyWithVersion(V object,
                                       K key,
                                       Object currentVersionKey,
                                       long expirationTime)

Sets the object for the specified key and current version key.

Parameters:

object - the object to set

key - the lookup key

currentVersionKey - the version of the object right now

setObjectForKeyWithVersion

public void setObjectForKeyWithVersion(V object,
                                       K key,
                                       Object currentVersionKey)

Sets the object for the specified key and current version key.

Parameters:

object - the object to set

key - the lookup key

currentVersionKey - the version of the object right now

objectForKey

public V objectForKey(K key)

Returns the value of the given key with an unspecified version.

Parameters:

key - the key to lookup with

Returns:

the value in the cache or null

objectForKeyWithVersion

public V objectForKeyWithVersion(K key,
                                 Object currentVersionKey)

Returns the value of the given key passing in the current version of the cache value. If the version key passed in does not match the version key in the cache, the cache will invalidate that key.

Parameters:

key - the key to lookup with

currentVersionKey - the current version of this key

Returns:

the value in the cache or null

isStale

public boolean isStale(K key)

Returns whether or not the object for the given key is a stale cache entry.

Parameters:

key - the key to lookup

Returns:

true if the value is stale

isStaleWithVersion

public boolean isStaleWithVersion(K key,
                                  Object currentVersionKey)

Returns whether or not the object for the given key is a stale cache entry given the context of the current version of the key.

Parameters:

key - the key to lookup

currentVersionKey - the current version of this key

Returns:

true if the value is stale

removeObjectForKey

public V removeObjectForKey(K key)

Removes the object for the given key.

Parameters:

key - the key to remove

Returns:

the removed object

removeStaleEntries

public void removeStaleEntries()

Removes all stale entries.

removeEntryForKey

protected void removeEntryForKey(ERXExpiringCache.Entry<V> entry,
                                 K key)

setEntryForKey

protected void setEntryForKey(ERXExpiringCache.Entry<V> entry,
                              K key)

entryForKey

protected ERXExpiringCache.Entry<V> entryForKey(K key)

toString

public String toString()

Overrides:

toString in class Object

startBackgroundExpiration

public void startBackgroundExpiration()

Adds this cache to the background thread that reaps time-expired entries from expiring caches. If this cache is not a time-expiration cache, this will throw an IllegalArgumentException.

stopBackgroundExpiration

public void stopBackgroundExpiration()

Stops the background reaper for this cache.

reaper

protected static ERXExpiringCache.GrimReaper reaper()

Returns the repear for all ERXExpringCaches.

Returns:

the repear for all ERXExpringCaches

allKeys

public NSArray<K> allKeys()

Returns all keys.