ehcache

net.sf.ehcache.constructs.blocking
Class BlockingCache

java.lang.Object
  extended by net.sf.ehcache.constructs.EhcacheDecoratorAdapter
      extended by 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:

"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:

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:

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

ehcache

Copyright 2001-2014, Terracotta, Inc.