com.rshtech.util
Class ObjectCache<K,V>

java.lang.Object
  com.rshtech.util.ObjectCache<K,V>

public class ObjectCache<K,V>
extends java.lang.Object

A simple object cache that covers most of the bases. This cache implementation will cache an object, storing it via a key (very much like a Map). Entries are then tracked by how often they are accessed. If an expiration time is set for the cache and any of the check strategies are set, entries will then be removed from the cache as certain size or time limits are reached.

None of the methods for manipulating the cache will accept null values (i.e. you cannot have null keys or null values). If you try to use a null, a NullPointerException will be generated.

Note that the default settings for the cache (if created via the default constructor ObjectCache() are the following:

size limit:	50,000
expiration limit:	[NONE]
unused expiration limit:	5 minutes
time-based cache check:	[NONE]
usage-based cache check:	[NONE]

These settings will effectively hold on to at most 50k objects and automatically expire anything older than 5 minutes when that limit is hit. Please see below for more information on these settings and how they affect the cache operation.

There are two limits you can enforce on the cache: maximum number of entries and maximum time (in milliseconds) to keep an entry before considering it expired. You can set these limits using the following methods:

• setSizeLimit(int) - controls the maximum number of entries the cache will hold.
• setExpirationLimit(long) - controls how long (in milliseconds) an entry will be held in the cache before it is considered expired (at which point it will be removed on the next cache check).
• setUnusedExpirationLimit(long) - controls how long (in milliseconds) an entry will be held in the cache unused before it is considered expired (at which point it will be removed on the next cache check).

A value of DISABLED (-1) (or anything less than 0) will disable both of these limits.

The difference between the expiration limit and the unused expiration limit is what each limit checks to verify if an element is expired. The expiration limit controls how long an element will be kept in the cache in total. This limit is compared against the objects creation time. So if the expiration limit is set to 10,000ms, no element in the cache will be held longer than 10 seconds, regardless of whether it is in use or not. The expiration limit allows you to set an upper bound on how long a cached object is considered good. Once the limit is reached, the cached object is considered stale and removed from the cache. Setting this value to DISABLED (-1) means that all cached objects are considered good forever.

The unused expiration limit is used to expire objects that are not used often enough in the cache. This limit allows you to expire unused or seldom used objects regardless of whether they have expired due to the expiration limit. This means that if the cache has set the expiration limit to DISABLED (-1), but has set the unused expiration limit to 10,000ms any objects that are not used at least every 10 seconds will be considered expired and removed from the cache.

The size, expiration and unused expiration limits are enforced in three ways: monitoring of overall cache size when cache entries are added, checking how long it has been since a cache check was performed, or checking how many cache accesses have been made since the last cache check was performed. The monitoring of overall size is handled automatically. It only is checked is the size limit is set. The other two settings are set using the following:

• setCacheCheckTimeInterval(long) - sets how many milliseconds can pass (at a minimum) before a cache check is performed.
• setCacheCheckUsageInterval(int) - sets how many cache accesses can be made before a cache check is performed.

A value of DISABLED (-1) (or anything less than 0) will disable both of these settings. Both settings can be applied at the same time. In such a case, which ever interval evaluates first will cause a check, and then both counters (both time based and usage based) will be reset.

Some fine-tuning of the settings may be required to get the optimal performance for you application or codebase. Be careful not to trigger cache checks too often or to set your expiration too low. Such settings could result in unnecessary thrashing of the cache--which may degrade the performance of your application or code.

Example Configurations:

Here are some example configurations for some common cache requirements:

• Caching Immutable Objects, up to 10,000. Such a cache might be used for caching reference data where the data never changes and we do not want to hold more than 10,000 at a time. Only when the max limit of 10,000 objects is reached will the least used elements in the cache be thrown out. The following is a list of the settings for this cache:

  size limit:	10,000
  expiration limit:	DISABLED (-1)
  unused expiration limit:	DISABLED (-1)
  time-based cache check:	DISABLED (-1)
  usage-based cache check:	DISABLED (-1)

• Caching Immutable Objects, up to 10,000, discarding seldom used frequently.. This cache is similar to the previous one, but the seldom used elements are removed occasionally before the max limit is reached. The following is a list of the settings for this cache:

  size limit:	10,000
  expiration limit:	DISABLED (-1)
  unused expiration limit:	600,000 (10 minutes)
  time-based cache check:	60,000 (1 minute)
  usage-based cache check:	DISABLED (-1)

  This would check the cache each time the cache is called and at least 1 minute has passed. If there are elements in the cache that have not been used for 10 minutes, they are removed.

  Another configuration based on how many times the cache has been used would be the following:

  size limit:	10,000
  expiration limit:	DISABLED (-1)
  unused expiration limit:	600,000 (10 minutes)
  time-based cache check:	DISABLED (-1)
  usage-based cache check:	50

  Every 50th call to get() would trigger a cache check, removing elements that had not been used for over 10 minutes.
• Caching Time Sensitive Objects. Such a cache might be used for caching security data that may have a maximum lifespan. For instance, the cache could hold user credentials and permissions. Such data may need to be refreshed every 5 minutes to be sure it is the most recent data. The following is a list of the settings for this cache:

  size limit:	10,000
  expiration limit:	300,000 (5 minutes)
  unused expiration limit:	DISABLED (-1)
  time-based cache check:	10,000 (10 seconds)
  usage-based cache check:	DISABLED (-1)

  Each time the cache is used, if the last check was over 10 seconds ago, a cache check would be triggered. If any element was created over 5 minutes ago, it would be marked expired and removed from the cache.

  You could also use a usage based check or a combination of time and usage based checks with this configuration.

Version:

$Revision: 3129 $

Author:

$Author: kostya $

Field Summary

static int

DISABLED

Constructor Summary

ObjectCache()
Creates a basic rule cache with the default values.

ObjectCache(int sizeLimitVal)
Creates a basic rule cache using the specified size limit and default values for the rest.

ObjectCache(int sizeLimitVal, long expirationLimitMs, long unusedExpirationLimitMs)
Creates a basic rule cache using the specified size limit and expiration limit, using default values for the rest.

ObjectCache(int sizeLimitVal, long expirationLimitMs, long unusedExpirationLimitMs, long timedCheckMs, int usageCheckVal)
Creates a basic rule cache using the specified values.

Method Summary

void	cache(K key, V value) Cache a specied value under the given key.
void	clear() Clears the cache entirely, removing all values.
boolean	containsKey(K key) Return whether or not the specified key is contained in the cache.
void	expunge() Expunges the cache (that is, it checks the cache for expired items and removes them).
V	get(K key) Get the cached object for the specified key (returns null if the key is not present).
long	getCacheCheckTimeInterval() Get the time interval (in milliseconds) between cache checks.
int	getCacheCheckUsageInterval() Get the number of cache accesses between cache checks.
long	getExpirationLimit() Get the expiration limit for entries in the cache.
int	getSizeLimit() Get the size limit for the cache.
long	getUnusedExpirationLimit() Get the expiration limit for entries to sit unused in the cache.
boolean	isEmpty() Return whether the cache is empty.
boolean	isUsingSoftReferences()
V	remove(K key) Removes a given key and its mapped value from the cache.
java.util.List<V>	removeAll(java.util.Collection<K> keys) Removes all cache values for the collection of keys.
void	setCacheCheckTimeInterval(long cacheCheckTimeInterval) Set the time interval (in milliseconds) between cache checks.
void	setCacheCheckUsageInterval(int cacheCheckUsageInterval) Set the number of cache accesses between cache checks.
void	setExpirationLimit(long limit) Set the expiration limit for the entries in the cache.
void	setSizeLimit(int sizeLimit) Set the size limit for the cache.
void	setUnusedExpirationLimit(long limit) Set the expiration limit for the entries to sit unused in the cache.
void	setUsingSoftReferences(boolean val)
int	size() Get the size of the cache (how many entries it contains).

Methods inherited from class java.lang.Object

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

Field Detail

DISABLED

public static final int DISABLED

See Also:

Constant Field Values

Constructor Detail

ObjectCache

public ObjectCache()

Creates a basic rule cache with the default values.

ObjectCache

public ObjectCache(int sizeLimitVal)

Creates a basic rule cache using the specified size limit and default values for the rest.

Parameters:

sizeLimitVal - the maximum number of entries to have in the cache

ObjectCache

public ObjectCache(int sizeLimitVal,
                   long expirationLimitMs,
                   long unusedExpirationLimitMs)

Creates a basic rule cache using the specified size limit and expiration limit, using default values for the rest.

Parameters:

sizeLimitVal - the maximum number of entries to have in the cache

expirationLimitMs - the time (in milliseconds) to keep an entry before it is considered expired.

unusedExpirationLimitMs - the time (in milliseconds) to keep an entry unused before it is considered expired.

ObjectCache

public ObjectCache(int sizeLimitVal,
                   long expirationLimitMs,
                   long unusedExpirationLimitMs,
                   long timedCheckMs,
                   int usageCheckVal)

Creates a basic rule cache using the specified values.

Parameters:

sizeLimitVal - the maximum number of entries to have in the cache

expirationLimitMs - the time (in milliseconds) to keep an entry before it is considered expired.

unusedExpirationLimitMs - the time (in milliseconds) to keep an entry before it is considered expired.

timedCheckMs - the time (in milliseconds) to wait between cache checks.

usageCheckVal - the number of cache accesses to wait between cache checks.

Method Detail

isEmpty

public boolean isEmpty()

Return whether the cache is empty.

Returns:

true if there are no entries, false otherwise

size

public int size()

Get the size of the cache (how many entries it contains).

Returns:

the number of entries currently in the cache

containsKey

public boolean containsKey(K key)

Return whether or not the specified key is contained in the cache. Cache entries are keyed, so it is possible for an object to be in the cache twice but under two different keys. Such entries are considered separate, whether the object is the same or not.

Parameters:

key - the key to lookup in the cache

Returns:

true if the key is present, false otherwise

get

public V get(K key)

Get the cached object for the specified key (returns null if the key is not present). When a value is accessed via this method, the value's last access time is updated (thus changing its chances of being marked expired).

Parameters:

key - the key to use to lookup the object

Returns:

the value mapped to the specified key

cache

public void cache(K key,
                  V value)

Cache a specied value under the given key. If the key is already present, the previous value is over written with the new value (and the new value gets new cache times when stored).

Parameters:

key -

value -

remove

public V remove(K key)

Removes a given key and its mapped value from the cache. If the key is not present, it is ignored.

Parameters:

key - the key to remove.

Returns:

the cached value removed from the cache

removeAll

public java.util.List<V> removeAll(java.util.Collection<K> keys)

Removes all cache values for the collection of keys. If a key is not in the cache, it is ignored.

Parameters:

keys - the keys to remove.

Returns:

a Set of the cached values removed from the cache in the order they were removed (depends on the keys collection order).

clear

public void clear()

Clears the cache entirely, removing all values.

expunge

public void expunge()

Expunges the cache (that is, it checks the cache for expired items and removes them). Using this method should not be necessary with proper limit and check values. However, when you want to force a cache check or want to manage it yourself, this method appropriate.

getSizeLimit

public int getSizeLimit()

Get the size limit for the cache.

Returns:

Returns the size limit.

setSizeLimit

public void setSizeLimit(int sizeLimit)

Set the size limit for the cache.

Parameters:

sizeLimit - The sizeLimit to set.

getExpirationLimit

public long getExpirationLimit()

Get the expiration limit for entries in the cache.

Returns:

the expiration limit.

setExpirationLimit

public void setExpirationLimit(long limit)

Set the expiration limit for the entries in the cache.

Parameters:

limit - The expirationLimit to set.

getUnusedExpirationLimit

public long getUnusedExpirationLimit()

Get the expiration limit for entries to sit unused in the cache.

Returns:

the expiration limit.

setUnusedExpirationLimit

public void setUnusedExpirationLimit(long limit)

Set the expiration limit for the entries to sit unused in the cache.

Parameters:

limit - The unusedExpirationLimit to set.

getCacheCheckTimeInterval

public long getCacheCheckTimeInterval()

Get the time interval (in milliseconds) between cache checks.

Returns:

the time interval (in milliseconds) between cache checks.

setCacheCheckTimeInterval

public void setCacheCheckTimeInterval(long cacheCheckTimeInterval)

Set the time interval (in milliseconds) between cache checks.

Parameters:

cacheCheckTimeInterval - the time interval in milliseconds.

getCacheCheckUsageInterval

public int getCacheCheckUsageInterval()

Get the number of cache accesses between cache checks.

Returns:

the number of cache accesses between cache checks

setCacheCheckUsageInterval

public void setCacheCheckUsageInterval(int cacheCheckUsageInterval)

Set the number of cache accesses between cache checks.

Parameters:

cacheCheckUsageInterval - number of cache accesses between checks.

isUsingSoftReferences

public boolean isUsingSoftReferences()

setUsingSoftReferences

public void setUsingSoftReferences(boolean val)