net.sf.ehcache.jcache
Class JCache

java.lang.Object
  net.sf.ehcache.jcache.JCache

All Implemented Interfaces:

java.util.Map, net.sf.jsr107cache.Cache

public class JCache
extends java.lang.Object
implements net.sf.jsr107cache.Cache

A cache implementation that matches the JCACHE specification.

It is not possible for one class to implement both JCACHE and Ehcache in the same class due to conflicts with method signatures.

This implementation is a decorator for Ehcache, and should exhibit the same underlying characteristics as Ehcache.

Note that JCACHE contains no lifecyle methods. JCaches cannot be stopped. Any resources, such as loader threads cannot be released, although they will die off after 60 seconds.

Version:

$Id: JCache.java 512 2007-07-10 09:18:45Z gregluck $

Author:

Greg Luck

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

JCache(Ehcache cache, net.sf.jsr107cache.CacheLoader cacheLoader)
A constructor for JCache.

Method Summary

void	addListener(net.sf.jsr107cache.CacheListener cacheListener) Add a listener to the list of cache listeners.
void	clear() Removes all mappings from this map (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Set	entrySet() Returns a set view of the mappings contained in this map.
void	evict() The evict method will remove objects from the cache that are no longer valid.
java.lang.Object	get(java.lang.Object key) The get method will return, from the cache, the object associated with the argument "key".
java.util.Map	getAll(java.util.Collection keys) The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
Ehcache	getBackingCache() Gets the backing Ehcache
net.sf.jsr107cache.CacheEntry	getCacheEntry(java.lang.Object key) returns the CacheEntry object associated with the key.
net.sf.jsr107cache.CacheLoader	getCacheLoader() Gets the CacheLoader registered in this cache
net.sf.jsr107cache.CacheStatistics	getCacheStatistics() Gets an immutable Statistics object representing the Cache statistics at the time.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
java.util.Set	keySet() Returns a set view of the keys contained in this map.
void	load(java.lang.Object key) The load method provides a means to "pre load" the cache.
void	loadAll(java.util.Collection keys) The loadAll method provides a means to "pre load" objects into the cache.
java.lang.Object	peek(java.lang.Object key) The peek method will return the object associated with "key" if it currently exists (and is valid) in the cache.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map (optional operation).
void	putAll(java.util.Map sourceMap) Copies all of the mappings from the specified map to this map (optional operation).
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this map if it is present (optional operation).
void	removeListener(net.sf.jsr107cache.CacheListener cacheListener) Remove a listener from the list of cache listeners
void	setCacheLoader(net.sf.jsr107cache.CacheLoader cacheLoader) Setter for the CacheLoader.
void	setStatisticsAccuracy(int statisticsAccuracy) Sets the statistics accuracy.
int	size() Returns the number of key-value mappings in this map.
java.lang.String	toString() Returns a String representation of the underlying Cache.
java.util.Collection	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.jsr107cache.Cache

equals, hashCode

Constructor Detail

JCache

public JCache(Ehcache cache,
              net.sf.jsr107cache.CacheLoader cacheLoader)

A constructor for JCache.

JCache is an adaptor for an Ehcache, and therefore requires an Ehcace in its constructor.

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Ehcache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

cache - An ehcache

cacheLoader - used to load entries when they are not in the cache. If this is null, which is legal, loads do a noop

Since:

1.3

Method Detail

setCacheLoader

public void setCacheLoader(net.sf.jsr107cache.CacheLoader cacheLoader)

Setter for the CacheLoader. Changing the CacheLoader takes immediate effect.

Parameters:

cacheLoader - the loader to dynamically load new cache entries

addListener

public void addListener(net.sf.jsr107cache.CacheListener cacheListener)

Add a listener to the list of cache listeners. The behaviour of JCACHE and Ehcache listeners is a little different. See JCacheListenerAdaptor for details on how each event is adapted.

Specified by:

addListener in interface net.sf.jsr107cache.Cache

Parameters:

cacheListener - a JCACHE CacheListener

See Also:

JCacheListenerAdaptor

evict

public void evict()

The evict method will remove objects from the cache that are no longer valid. Objects where the specified expiration time has been reached.

This implementation synchronously checks each store for expired elements. Note that the DiskStore has an expiryThread that runs periodically to do the same thing, and that the MemoryStore lazily checks for expiry on overflow and peek, thus reducing the utility of calling this method.

Specified by:

evict in interface net.sf.jsr107cache.Cache

getAll

public java.util.Map getAll(java.util.Collection keys)
                     throws net.sf.jsr107cache.CacheException

The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

Note. If the getAll exceeds the maximum cache size, the returned map will necessarily be less than the number specified.

Specified by:

getAll in interface net.sf.jsr107cache.Cache

Parameters:

keys -

Returns:

a Map populated from the Cache. If there are no elements, an empty Map is returned.

Throws:

net.sf.jsr107cache.CacheException

getCacheLoader

public net.sf.jsr107cache.CacheLoader getCacheLoader()

Gets the CacheLoader registered in this cache

Returns:

the loader, or null if there is none

getCacheEntry

public net.sf.jsr107cache.CacheEntry getCacheEntry(java.lang.Object key)

returns the CacheEntry object associated with the key.

Specified by:

getCacheEntry in interface net.sf.jsr107cache.Cache

Parameters:

key - the key to look for in the cache

getCacheStatistics

public net.sf.jsr107cache.CacheStatistics getCacheStatistics()
                                                      throws java.lang.IllegalStateException

Gets an immutable Statistics object representing the Cache statistics at the time. How the statistics are calculated depends on the statistics accuracy setting. The only aspect of statistics sensitive to the accuracy setting is object size. How that is calculated is discussed below.

Best Effort Size

This result is returned when the statistics accuracy setting is CacheStatistics.STATISTICS_ACCURACY_BEST_EFFORT.

The size is the number of Elements in the MemoryStore plus the number of Elements in the DiskStore.

This number is the actual number of elements, including expired elements that have not been removed. Any duplicates between stores are accounted for.

Expired elements are removed from the the memory store when getting an expired element, or when attempting to spool an expired element to disk.

Expired elements are removed from the disk store when getting an expired element, or when the expiry thread runs, which is once every five minutes.

Guaranteed Accuracy Size

This result is returned when the statistics accuracy setting is CacheStatistics.STATISTICS_ACCURACY_GUARANTEED.

This method accounts for elements which might be expired or duplicated between stores. It take approximately 200ms per 1000 elements to execute.

Fast but non-accurate Size

This result is returned when the statistics accuracy setting is CacheStatistics.STATISTICS_ACCURACY_NONE.

The number given may contain expired elements. In addition if the DiskStore is used it may contain some double counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take 36ms.

Specified by:

getCacheStatistics in interface net.sf.jsr107cache.Cache

Returns:

the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.

Throws:

java.lang.IllegalStateException - if the cache is not Status.STATUS_ALIVE

load

public void load(java.lang.Object key)
          throws net.sf.jsr107cache.CacheException

The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified object into the cache using the associated cacheloader. If the object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

Specified by:

load in interface net.sf.jsr107cache.Cache

Parameters:

key - key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it.

Throws:

net.sf.jsr107cache.CacheException

loadAll

public void loadAll(java.util.Collection keys)
             throws net.sf.jsr107cache.CacheException

The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load the specified objects into the cache using the associated cache loader. If the an object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) should be logged. The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method.

keys - collection of the keys whose associated values to be loaded into this cache by using the associated cacheloader if this cache doesn't contain them.

The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

Specified by:

loadAll in interface net.sf.jsr107cache.Cache

Throws:

net.sf.jsr107cache.CacheException

peek

public java.lang.Object peek(java.lang.Object key)

The peek method will return the object associated with "key" if it currently exists (and is valid) in the cache. If not, a null is returned. With "peek" the CacheLoader will not be invoked and other caches in the system will not be searched.

In ehcache peek bahaves the same way as get(java.lang.Object)

Specified by:

peek in interface net.sf.jsr107cache.Cache

Parameters:

key -

Returns:

the value stored in the cache by key, or null if it does not exist

removeListener

public void removeListener(net.sf.jsr107cache.CacheListener cacheListener)

Remove a listener from the list of cache listeners

Specified by:

removeListener in interface net.sf.jsr107cache.Cache

Parameters:

cacheListener - a JCACHE CacheListener

See Also:

JCacheListenerAdaptor

size

public int size()

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface java.util.Map

Specified by:

size in interface net.sf.jsr107cache.Cache

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

Specified by:

isEmpty in interface net.sf.jsr107cache.Cache

Returns:

true if this map contains no key-value mappings.

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Specified by:

containsKey in interface java.util.Map

Specified by:

containsKey in interface net.sf.jsr107cache.Cache

Parameters:

key - key whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified key.

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the map size for most implementations of the Map interface.

Warning: This method is extremely slow. Ehcache is designed for efficient retrieval using keys, not values.

Specified by:

containsValue in interface java.util.Map

Specified by:

containsValue in interface net.sf.jsr107cache.Cache

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value.

get

public java.lang.Object get(java.lang.Object key)
                     throws java.lang.RuntimeException

The get method will return, from the cache, the object associated with the argument "key".

If the object is not in the cache, the associated cache loader will be called. If no loader is associated with the object, a null is returned.

If a problem is encountered during the retrieving or loading of the object, an exception (to be defined) will be thrown. (Until it is defined, the ehcache implementation throws a RuntimeException.)

If the "arg" argument is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load method.

The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

Cache statistics are only updated for the initial attempt to get the cached entry.

Specified by:

get in interface java.util.Map

Specified by:

get in interface net.sf.jsr107cache.Cache

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key after an attempt has been made to load it.

Throws:

java.lang.RuntimeException - JSR107 should really throw a CacheException here, but the spec does not allow it. Instead throw a RuntimeException if the underlying load method throws a CacheException.

See Also:

todo consider removing async stuff

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.))

Specified by:

put in interface java.util.Map

Specified by:

put in interface net.sf.jsr107cache.Cache

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

remove

public java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. (A null return can also indicate that the map previously associated null with the specified key if the implementation supports null values.) The map will not contain a mapping for the specified key once the call returns.

Specified by:

remove in interface java.util.Map

Specified by:

remove in interface net.sf.jsr107cache.Cache

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

putAll

public void putAll(java.util.Map sourceMap)

Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the N specified map. The behavior of this operation is unspecified if the specified map is modified while the operation is in progress.

Specified by:

putAll in interface java.util.Map

Specified by:

putAll in interface net.sf.jsr107cache.Cache

Parameters:

sourceMap - Mappings to be stored in this map.

clear

public void clear()

Removes all mappings from this map (optional operation).

Specified by:

clear in interface java.util.Map

Specified by:

clear in interface net.sf.jsr107cache.Cache

keySet

public java.util.Set keySet()

Returns a set view of the keys contained in this map. The set is not live because ehcache is not backed by a simple map.

Specified by:

keySet in interface java.util.Map

Specified by:

keySet in interface net.sf.jsr107cache.Cache

Returns:

a set view of the keys contained in this map.

values

public java.util.Collection values()

Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Contradicting the above Map contract, whether cache changes after this method returns are not reflected in the Collection. This is because ehcache is not backed by a single map.

Specified by:

values in interface java.util.Map

Specified by:

values in interface net.sf.jsr107cache.Cache

Returns:

a collection view of the values contained in this map.

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Contradicting the above Map contract, whether or not changes to an entry affect the entry in the cache is undefined.

Specified by:

entrySet in interface java.util.Map

Specified by:

entrySet in interface net.sf.jsr107cache.Cache

Returns:

a set view of the mappings contained in this map.

setStatisticsAccuracy

public void setStatisticsAccuracy(int statisticsAccuracy)

Sets the statistics accuracy.

Parameters:

statisticsAccuracy - one of CacheStatistics.STATISTICS_ACCURACY_BEST_EFFORT, CacheStatistics.STATISTICS_ACCURACY_GUARANTEED, CacheStatistics.STATISTICS_ACCURACY_NONE

getBackingCache

public Ehcache getBackingCache()

Gets the backing Ehcache

toString

public java.lang.String toString()

Returns a String representation of the underlying Cache.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the object.