net.sf.ehcache.constructs.blocking
Class BlockingCache

java.lang.Object
  net.sf.ehcache.constructs.EhcacheDecoratorAdapter
      net.sf.ehcache.constructs.blocking.BlockingCache

All Implemented Interfaces:

Cloneable, Ehcache, InternalEhcache

Direct Known Subclasses:

SelfPopulatingCache

public class BlockingCache
extends EhcacheDecoratorAdapter

A blocking decorator for an Ehcache, backed by a Ehcache.

It allows concurrent read access to elements already in the cache. If the element is null, other reads will block until an element with the same key is put into the cache.

This is useful for constructing read-through or self-populating caches.

This implementation uses the ReadWriteLockSync class. If you wish to use this class, you will need the concurrent package in your class path.

It features:

• Excellent liveness.
• Fine-grained locking on each element, rather than the cache as a whole.
• Scalability to a large number of threads.

"Hashtable / synchronizedMap uses the "one big fat lock" approach to guard the mutable state of the map. That works, but is a big concurrency bottleneck, as you've observed. You went to the opposite extreme, one lock per key. That works (as long as you've got sufficient synchronization in the cache itself to protect its own data structures.)

Lock striping is a middle ground, partitioning keys into a fixed number of subsets, like the trick used at large theaters for will-call ticket pickup -- there are separate lines for "A-F, G-M, N-R, and S-Z". This way, there are a fixed number of locks, each guarding (hopefully) 1/Nth of the keys." - Brian Goetz

Further improvements to hashing suggested by Joe Bowbeer.

Version:

$Id: BlockingCache.java 6907 2013-01-18 16:16:39Z cdennis $

Author:

Greg Luck

Field Summary

protected int

timeoutMillis The amount of time to block a thread before a LockTimeoutException is thrown

Fields inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter

underlyingCache

Constructor Summary

BlockingCache(Ehcache cache)
Creates a BlockingCache which decorates the supplied cache.

BlockingCache(Ehcache cache, int numberOfStripes)
Creates a BlockingCache which decorates the supplied cache.

Method Summary

Element	get(Object key) Looks up an entry.
Element	get(Serializable key) Gets an element from the cache.
Map	getAllWithLoader(Collection keys, Object loaderArgument) This method is not appropriate to use with BlockingCache.
protected Ehcache	getCache() Retrieve the EHCache backing cache
protected Sync	getLockForKey(Object key) Gets the Sync to use for a given key.
int	getTimeoutMillis() Gets the time to wait to acquire a lock.
Element	getWithLoader(Object key, CacheLoader loader, Object loaderArgument) This method is not appropriate to use with BlockingCache.
String	liveness() Synchronized version of getName to test liveness of the object lock.
void	load(Object key) This method is not appropriate to use with BlockingCache.
void	loadAll(Collection keys, Object argument) This method is not appropriate to use with BlockingCache.
void	put(Element element) Adds an entry and unlocks it
void	put(Element element, boolean doNotNotifyCacheReplicators) Put an element in the cache.
Element	putIfAbsent(Element element) Put an element in the cache if no element is currently mapped to the elements key.
Element	putIfAbsent(Element element, boolean doNotNotifyCacheReplicators) Put an element in the cache if no element is currently mapped to the elements key.
void	putQuiet(Element element) Put an element in the cache, without updating statistics, or updating listeners.
void	putWithWriter(Element element) Put an element in the cache writing through a CacheWriter.
void	registerCacheLoader(CacheLoader cacheLoader) Register a CacheLoader with the cache.
void	setTimeoutMillis(int timeoutMillis) Sets the time to wait to acquire a lock.
void	unregisterCacheLoader(CacheLoader cacheLoader) Unregister a CacheLoader with the cache.

Methods inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter

acquireReadLockOnKey, acquireWriteLockOnKey, addPropertyChangeListener, bootstrap, calculateInMemorySize, calculateOffHeapSize, calculateOnDiskSize, clone, createQuery, disableDynamicFeatures, dispose, evictExpiredElements, flush, getAll, getBootstrapCacheLoader, getCacheConfiguration, getCacheEventNotificationService, getCacheExceptionHandler, getCacheManager, getDiskStoreSize, getGuid, getInternalContext, getKeys, getKeysNoDuplicateCheck, getKeysWithExpiryCheck, getMemoryStoreSize, getName, getOffHeapStoreSize, getQuiet, getQuiet, getRegisteredCacheExtensions, getRegisteredCacheLoaders, getRegisteredCacheWriter, getSearchAttribute, getSize, getStatistics, getStatus, getWriterManager, hasAbortedSizeOf, initialise, isClusterBulkLoadEnabled, isClusterCoherent, isDisabled, isElementInMemory, isElementInMemory, isElementOnDisk, isElementOnDisk, isExpired, isKeyInCache, isNodeBulkLoadEnabled, isNodeCoherent, isReadLockedByCurrentThread, isSearchable, isValueInCache, isWriteLockedByCurrentThread, putAll, recalculateSize, registerCacheExtension, registerCacheWriter, registerDynamicAttributesExtractor, releaseReadLockOnKey, releaseWriteLockOnKey, remove, remove, remove, remove, removeAll, removeAll, removeAll, removeAll, removeAndReturnElement, removeElement, removePropertyChangeListener, removeQuiet, removeQuiet, removeWithWriter, replace, replace, setBootstrapCacheLoader, setCacheExceptionHandler, setCacheManager, setDisabled, setName, setNodeBulkLoadEnabled, setNodeCoherent, setTransactionManagerLookup, toString, tryReadLockOnKey, tryWriteLockOnKey, unregisterCacheExtension, unregisterCacheWriter, waitUntilClusterBulkLoadComplete, waitUntilClusterCoherent

Methods inherited from class java.lang.Object

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

Field Detail

timeoutMillis

protected volatile int timeoutMillis

The amount of time to block a thread before a LockTimeoutException is thrown

Constructor Detail

BlockingCache

public BlockingCache(Ehcache cache,
                     int numberOfStripes)
              throws CacheException

Creates a BlockingCache which decorates the supplied cache.

Parameters:

cache - a backing ehcache.

numberOfStripes - how many stripes to has the keys against. Must be a non-zero even number. This is a trade-off between memory use and concurrency

Throws:

CacheException - shouldn't happen

Since:

1.2

BlockingCache

public BlockingCache(Ehcache cache)
              throws CacheException

Creates a BlockingCache which decorates the supplied cache.

Parameters:

cache - a backing ehcache.

Throws:

CacheException - shouldn't happen

Since:

1.6.1

Method Detail

getCache

protected Ehcache getCache()

Retrieve the EHCache backing cache

Returns:

the backing cache

get

public Element get(Object key)
            throws RuntimeException,
                   LockTimeoutException

Looks up an entry. Blocks if the entry is null until a call to put(net.sf.ehcache.Element) is done to put an Element in.

If a put is not done, the lock is never released.

If this method throws an exception, it is the responsibility of the caller to catch that exception and call put(new Element(key, null)); to release the lock acquired. See SelfPopulatingCache for an example.

Note. If a LockTimeoutException is thrown while doing a get it means the lock was never acquired, therefore it is a threading error to call put(net.sf.ehcache.Element)

Specified by:

get in interface Ehcache

Overrides:

get in class EhcacheDecoratorAdapter

Parameters:

key - an Object value

Returns:

the element, or null, if it does not exist.

Throws:

LockTimeoutException - if timeout millis is non zero and this method has been unable to acquire a lock in that time

RuntimeException - if thrown the lock will not released. Catch and callput(new Element(key, null)); to release the lock acquired.

See Also:

Ehcache.isExpired(net.sf.ehcache.Element)

getLockForKey

protected Sync getLockForKey(Object key)

Gets the Sync to use for a given key.

Parameters:

key - the key

Returns:

one of a limited number of Sync's.

put

public void put(Element element)

Adds an entry and unlocks it

Specified by:

put in interface Ehcache

Overrides:

put in class EhcacheDecoratorAdapter

Parameters:

element - An object. If Serializable it can fully participate in replication and the DiskStore.

put

public void put(Element element,
                boolean doNotNotifyCacheReplicators)
         throws IllegalArgumentException,
                IllegalStateException,
                CacheException

Description copied from class: EhcacheDecoratorAdapter

Put an element in the cache.

Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

Also notifies the CacheEventListener that:

• the element was put, but only if the Element was actually put.
• if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested

Specified by:

put in interface Ehcache

Overrides:

put in class EhcacheDecoratorAdapter

Parameters:

element - An object. If Serializable it can fully participate in replication and the DiskStore.

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Throws:

IllegalArgumentException - if the element is null

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

putQuiet

public void putQuiet(Element element)
              throws IllegalArgumentException,
                     IllegalStateException,
                     CacheException

Description copied from class: EhcacheDecoratorAdapter

Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used in conjunction with Ehcache.getQuiet(java.io.Serializable)

Specified by:

putQuiet in interface Ehcache

Overrides:

putQuiet in class EhcacheDecoratorAdapter

Parameters:

element - An object. If Serializable it can fully participate in replication and the DiskStore.

Throws:

IllegalArgumentException - if the element is null

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

putWithWriter

public void putWithWriter(Element element)
                   throws IllegalArgumentException,
                          IllegalStateException,
                          CacheException

Description copied from class: EhcacheDecoratorAdapter

Put an element in the cache writing through a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

Also notifies the CacheEventListener, if the writer operation succeeds, that:

• the element was put, but only if the Element was actually put.
• if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested

Specified by:

putWithWriter in interface Ehcache

Overrides:

putWithWriter in class EhcacheDecoratorAdapter

Parameters:

element - An object. If Serializable it can fully participate in replication and the DiskStore.

Throws:

IllegalArgumentException - if the element is null

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException - if no CacheWriter was registered

putIfAbsent

public Element putIfAbsent(Element element)
                    throws NullPointerException

Description copied from class: EhcacheDecoratorAdapter

Put an element in the cache if no element is currently mapped to the elements key.

Specified by:

putIfAbsent in interface Ehcache

Overrides:

putIfAbsent in class EhcacheDecoratorAdapter

Parameters:

element - element to be added

Returns:

the element previously cached for this key, or null if none.

Throws:

NullPointerException - if the element is null, or has a null key

putIfAbsent

public Element putIfAbsent(Element element,
                           boolean doNotNotifyCacheReplicators)
                    throws NullPointerException

Description copied from interface: Ehcache

Put an element in the cache if no element is currently mapped to the elements key.

Specified by:

putIfAbsent in interface Ehcache

Overrides:

putIfAbsent in class EhcacheDecoratorAdapter

Parameters:

element - element to be added

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Returns:

the element previously cached for this key, or null if none.

Throws:

NullPointerException - if the element is null, or has a null key

get

public Element get(Serializable key)
            throws IllegalStateException,
                   CacheException

Gets an element from the cache. Updates Element Statistics

Note that the Element's lastAccessTime is always the time of this get. Use EhcacheDecoratorAdapter.getQuiet(Object) to peak into the Element to see its last access time with get

Specified by:

get in interface Ehcache

Overrides:

get in class EhcacheDecoratorAdapter

Parameters:

key - a serializable value

Returns:

the element, or null, if it does not exist.

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

See Also:

EhcacheDecoratorAdapter.isExpired(net.sf.ehcache.Element)

liveness

public String liveness()

Synchronized version of getName to test liveness of the object lock.

The time taken for this method to return is a useful measure of runtime contention on the cache.

Returns:

the name of the cache.

setTimeoutMillis

public void setTimeoutMillis(int timeoutMillis)

Sets the time to wait to acquire a lock. This may be modified at any time.

The consequences of setting a timeout are:

1. if a lock cannot be acquired in the given time a LockTimeoutException is thrown.
2. if there is a queue of threads waiting for the first thread to complete, but it does not complete within the time out period, the successive threads may find that they have exceeded their lock timeouts and fail. This is usually a good thing because it stops a build up of threads from overwhelming a busy resource, but it does need to be considered in the design of user interfaces. The timeout should be set no greater than the time a user would be expected to wait before considering the action will never return
3. it will be common to see a number of threads timeout trying to get the same lock. This is a normal and desired consequence.

The consequences of not setting a timeout (or setting it to 0) are:

1. There are no partial failures in the system. But there is a greater possibility that a temporary overload in one part of the system can cause a back up that may take a long time to recover from.
2. A failing method that perhaps fails because a resource is overloaded will be hit by each thread in turn, no matter whether there is a still a user who cares about getting a response.

Parameters:

timeoutMillis - the time in ms. Must be a positive number. 0 means wait forever.

getTimeoutMillis

public int getTimeoutMillis()

Gets the time to wait to acquire a lock.

Returns:

the time in ms.

registerCacheLoader

public void registerCacheLoader(CacheLoader cacheLoader)

Register a CacheLoader with the cache. It will then be tied into the cache lifecycle.

If the CacheLoader is not initialised, initialise it.

Specified by:

registerCacheLoader in interface Ehcache

Overrides:

registerCacheLoader in class EhcacheDecoratorAdapter

Parameters:

cacheLoader - A Cache Loader to register

unregisterCacheLoader

public void unregisterCacheLoader(CacheLoader cacheLoader)

Unregister a CacheLoader with the cache. It will then be detached from the cache lifecycle.

Specified by:

unregisterCacheLoader in interface Ehcache

Overrides:

unregisterCacheLoader in class EhcacheDecoratorAdapter

Parameters:

cacheLoader - A Cache Loader to unregister

getWithLoader

public Element getWithLoader(Object key,
                             CacheLoader loader,
                             Object loaderArgument)
                      throws CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

getWithLoader in interface Ehcache

Overrides:

getWithLoader in class EhcacheDecoratorAdapter

Parameters:

key - key whose associated value is to be returned.

loader - the override loader to use. If null, the cache's default loader will be used

loaderArgument - an argument to pass to the CacheLoader.

Returns:

an element if it existed or could be loaded, otherwise null

Throws:

CacheException - if this method is called

getAllWithLoader

public Map getAllWithLoader(Collection keys,
                            Object loaderArgument)
                     throws CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

getAllWithLoader in interface Ehcache

Overrides:

getAllWithLoader in class EhcacheDecoratorAdapter

Parameters:

keys - a collection of keys to be returned/loaded

loaderArgument - an argument to pass to the CacheLoader.

Returns:

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

Throws:

CacheException - if this method is called

load

public void load(Object key)
          throws CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

load in interface Ehcache

Overrides:

load in class EhcacheDecoratorAdapter

Parameters:

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

Throws:

CacheException - if this method is called

loadAll

public void loadAll(Collection keys,
                    Object argument)
             throws CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

loadAll in interface Ehcache

Overrides:

loadAll in class EhcacheDecoratorAdapter

Throws:

CacheException - if this method is called