ehcache

net.sf.ehcache.constructs.eventual
Class StronglyConsistentCacheAccessor

java.lang.Object
  extended by net.sf.ehcache.constructs.EhcacheDecoratorAdapter
      extended by net.sf.ehcache.constructs.eventual.StronglyConsistentCacheAccessor
All Implemented Interfaces:
Cloneable, Ehcache, InternalEhcache

public class StronglyConsistentCacheAccessor
extends EhcacheDecoratorAdapter

StronglyConsistentCacheAccessor is a decorator that accepts distributed caches configured with eventual consistency.

The accessor will then lock for all operations:

Author:
Louis Jacomet

Field Summary
 
Fields inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter
underlyingCache
 
Constructor Summary
StronglyConsistentCacheAccessor(Ehcache underlyingCache)
          Constructor accepting the cache to be decorated.
 
Method Summary
 Element get(Object key)
          Gets an element from the cache.
 Element get(Serializable key)
          Gets an element from the cache.
 Map<Object,Element> getAll(Collection<?> keys)
          Gets all the elements from the cache for the keys provided.
 Map getAllWithLoader(Collection keys, Object loaderArgument)
          The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
 Element getQuiet(Object key)
          Gets an element from the cache, without updating Element statistics.
 Element getQuiet(Serializable key)
          Gets an element from the cache, without updating Element statistics.
 Element getWithLoader(Object key, CacheLoader loader, Object loaderArgument)
          This method will return, from the cache, the object associated with the argument "key".
 void put(Element element)
          Put an element in the cache.
 void put(Element element, boolean doNotNotifyCacheReplicators)
          Put an element in the cache.
 void putAll(Collection<Element> elements)
          Puts a collection of elements in to 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.
 boolean remove(Object key)
          Removes an Element from the Cache.
 boolean remove(Object key, boolean doNotNotifyCacheReplicators)
          Removes an Element from the Cache.
 boolean remove(Serializable key)
          Removes an Element from the Cache.
 boolean remove(Serializable key, boolean doNotNotifyCacheReplicators)
          Removes an Element from the Cache.
 void removeAll(Collection<?> keys)
          Removes given set of Element from the Cache.
 void removeAll(Collection<?> keys, boolean doNotNotifyCacheReplicators)
          Removes all cached items.
 Element removeAndReturnElement(Object key)
          Removes and returns the element associated with the key
 boolean removeElement(Element element)
          Remove the Element mapped to the key for the supplied element if the value of the supplied Element compares equal to the value of the cached Element.
 boolean removeQuiet(Object key)
          Removes an Element from the Cache, without notifying listeners.
 boolean removeQuiet(Serializable key)
          Removes an Element from the Cache, without notifying listeners.
 boolean removeWithWriter(Object key)
          Removes an Element from the Cache and any stores it might be in.
 Element replace(Element element)
          Replace the cached element only if an Element is currently cached for this key
 boolean replace(Element old, Element element)
          Replace the cached element only if the current Element is equal to the supplied old Element.
 
Methods inherited from class net.sf.ehcache.constructs.EhcacheDecoratorAdapter
acquireReadLockOnKey, acquireWriteLockOnKey, addPropertyChangeListener, bootstrap, calculateInMemorySize, calculateOffHeapSize, calculateOnDiskSize, clone, createQuery, disableDynamicFeatures, dispose, evictExpiredElements, flush, getBootstrapCacheLoader, getCacheConfiguration, getCacheEventNotificationService, getCacheExceptionHandler, getCacheManager, getDiskStoreSize, getGuid, getInternalContext, getKeys, getKeysNoDuplicateCheck, getKeysWithExpiryCheck, getMemoryStoreSize, getName, getOffHeapStoreSize, getRegisteredCacheExtensions, getRegisteredCacheLoaders, getRegisteredCacheWriter, getSearchAttribute, getSearchAttributes, getSize, getStatistics, getStatus, getWriterManager, hasAbortedSizeOf, initialise, isClusterBulkLoadEnabled, isClusterCoherent, isDisabled, isElementInMemory, isElementInMemory, isElementOnDisk, isElementOnDisk, isExpired, isKeyInCache, isNodeBulkLoadEnabled, isNodeCoherent, isReadLockedByCurrentThread, isSearchable, isValueInCache, isWriteLockedByCurrentThread, load, loadAll, recalculateSize, registerCacheExtension, registerCacheLoader, registerCacheWriter, registerDynamicAttributesExtractor, releaseReadLockOnKey, releaseWriteLockOnKey, removeAll, removeAll, removePropertyChangeListener, setBootstrapCacheLoader, setCacheExceptionHandler, setCacheManager, setDisabled, setName, setNodeBulkLoadEnabled, setNodeCoherent, setTransactionManagerLookup, toString, tryReadLockOnKey, tryWriteLockOnKey, unregisterCacheExtension, unregisterCacheLoader, unregisterCacheWriter, waitUntilClusterBulkLoadComplete, waitUntilClusterCoherent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

StronglyConsistentCacheAccessor

public StronglyConsistentCacheAccessor(Ehcache underlyingCache)
                                throws IllegalArgumentException
Constructor accepting the cache to be decorated.

Parameters:
underlyingCache - a clustered cache configured with eventual consistency
Throws:
IllegalArgumentException - if the underlying cache is not clustered and has not eventual consistency.
Method Detail

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

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

replace

public boolean replace(Element old,
                       Element element)
                throws NullPointerException,
                       IllegalArgumentException
Description copied from class: EhcacheDecoratorAdapter
Replace the cached element only if the current Element is equal to the supplied old Element.

Specified by:
replace in interface Ehcache
Overrides:
replace in class EhcacheDecoratorAdapter
Parameters:
old - Element to be test against
element - Element to be cached
Returns:
true if the Element was replaced
Throws:
NullPointerException - if the either Element is null or has a null key
IllegalArgumentException - if the two Element keys are non-null but not equal

replace

public Element replace(Element element)
                throws NullPointerException
Description copied from class: EhcacheDecoratorAdapter
Replace the cached element only if an Element is currently cached for this key

Specified by:
replace in interface Ehcache
Overrides:
replace in class EhcacheDecoratorAdapter
Parameters:
element - Element to be cached
Returns:
the Element previously cached for this key, or null if no Element was cached
Throws:
NullPointerException - if the Element is null or has a null key

removeElement

public boolean removeElement(Element element)
                      throws NullPointerException
Description copied from class: EhcacheDecoratorAdapter
Remove the Element mapped to the key for the supplied element if the value of the supplied Element compares equal to the value of the cached Element.

This is equivalent to

   if (elementValueComparator.equals(cache.get(element.getObjectKey()), element)) {
       return cache.remove(element.getObjectKey());
   } else return false;
 
except that the action is performed atomically.

Specified by:
removeElement in interface Ehcache
Overrides:
removeElement in class EhcacheDecoratorAdapter
Parameters:
element - Element to be removed
Returns:
true if the value was removed
Throws:
NullPointerException - if the element is null, or has a null key
See Also:
CacheConfiguration.addElementValueComparator(net.sf.ehcache.config.ElementValueComparatorConfiguration)

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

put

public void put(Element element)
         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.
Throws:
IllegalArgumentException - if the element is null
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

putAll

public void putAll(Collection<Element> elements)
            throws IllegalArgumentException,
                   IllegalStateException,
                   CacheException
Description copied from class: EhcacheDecoratorAdapter
Puts a collection of elements in to the cache.

This method will throw a NullPointerException if a null element or null key is encountered in the collection, and a partial completion may result (as only some of the elements may have been put).

For each element that is put the registered CacheEventListeners are notified of a newly put item (notifyElementPut(...)) regardless of whether the individual put is a new put or an update.

Specified by:
putAll in interface Ehcache
Overrides:
putAll in class EhcacheDecoratorAdapter
Parameters:
elements - the collection of elements to be put in the cache.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
IllegalArgumentException

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

remove

public boolean remove(Object key,
                      boolean doNotNotifyCacheReplicators)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache. This also removes it from any stores it may be in.

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Specified by:
remove in interface Ehcache
Overrides:
remove in class EhcacheDecoratorAdapter
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:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeAll

public void removeAll(Collection<?> keys)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes given set of Element from the Cache. This also removes them from any stores it may be in. Throws a NullPointerException if any key in the collection is null

Also notifies the CacheEventListener after the elements were removed. Notification is sent for every key irrespective of whether the key was present in the cache or not This operation is partially completed if any element or any key is null

Specified by:
removeAll in interface Ehcache
Overrides:
removeAll in class EhcacheDecoratorAdapter
Parameters:
keys - a collection of keys to operate on
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

public boolean remove(Object key)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache. This also removes it from any stores it may be in.

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Specified by:
remove in interface Ehcache
Overrides:
remove in class EhcacheDecoratorAdapter
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeAll

public void removeAll(Collection<?> keys,
                      boolean doNotNotifyCacheReplicators)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes all cached items.

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

Specified by:
removeAll in interface Ehcache
Overrides:
removeAll in class EhcacheDecoratorAdapter
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:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

public boolean remove(Serializable key,
                      boolean doNotNotifyCacheReplicators)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache. This also removes it from any stores it may be in.

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Specified by:
remove in interface Ehcache
Overrides:
remove in class EhcacheDecoratorAdapter
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:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

public boolean remove(Serializable key)
               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache. This also removes it from any stores it may be in.

Also notifies the CacheEventListener after the element was removed.

Specified by:
remove in interface Ehcache
Overrides:
remove in class EhcacheDecoratorAdapter
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeQuiet

public boolean removeQuiet(Object key)
                    throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Specified by:
removeQuiet in interface Ehcache
Overrides:
removeQuiet in class EhcacheDecoratorAdapter
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeQuiet

public boolean removeQuiet(Serializable key)
                    throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Specified by:
removeQuiet in interface Ehcache
Overrides:
removeQuiet in class EhcacheDecoratorAdapter
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeWithWriter

public boolean removeWithWriter(Object key)
                         throws IllegalStateException,
                                CacheException
Description copied from class: EhcacheDecoratorAdapter
Removes an Element from the Cache and any stores it might be in. This also removes through to a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Specified by:
removeWithWriter in interface Ehcache
Overrides:
removeWithWriter in class EhcacheDecoratorAdapter
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException - if no CacheWriter was registered

removeAndReturnElement

public Element removeAndReturnElement(Object key)
                               throws IllegalStateException
Description copied from class: EhcacheDecoratorAdapter
Removes and returns the element associated with the key

Specified by:
removeAndReturnElement in interface InternalEhcache
Overrides:
removeAndReturnElement in class EhcacheDecoratorAdapter
Parameters:
key - the key of the element to operate on
Returns:
element the removed element associated with the key, null if no mapping exists
Throws:
IllegalStateException

get

public Element get(Object key)
            throws IllegalStateException,
                   CacheException
Description copied from class: EhcacheDecoratorAdapter
Gets an element from the cache. Updates Element Statistics

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

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:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
See Also:
Ehcache.isExpired(net.sf.ehcache.Element)

getAll

public Map<Object,Element> getAll(Collection<?> keys)
                           throws IllegalStateException,
                                  CacheException
Description copied from class: EhcacheDecoratorAdapter
Gets all the elements from the cache for the keys provided. Updates Element Statistics Throws a NullPointerException if any key in the collection is null

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

Specified by:
getAll in interface Ehcache
Overrides:
getAll in class EhcacheDecoratorAdapter
Parameters:
keys - a collection of keys for which value is to be fetched
Returns:
Map of key and elements for the provided keys, value will be null for the keys which do not exist
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
See Also:
Ehcache.isExpired(net.sf.ehcache.Element)

get

public Element get(Serializable key)
            throws IllegalStateException,
                   CacheException
Description copied from class: EhcacheDecoratorAdapter
Gets an element from the cache. Updates Element Statistics

Note that the Element's lastAccessTime is always the time of this get. Use Ehcache.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:
Ehcache.isExpired(net.sf.ehcache.Element)

getQuiet

public Element getQuiet(Object key)
                 throws IllegalStateException,
                        CacheException
Description copied from class: EhcacheDecoratorAdapter
Gets an element from the cache, without updating Element statistics. Cache statistics are also not updated.

Specified by:
getQuiet in interface Ehcache
Overrides:
getQuiet 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:
Ehcache.isExpired(net.sf.ehcache.Element)

getQuiet

public Element getQuiet(Serializable key)
                 throws IllegalStateException,
                        CacheException
Description copied from class: EhcacheDecoratorAdapter
Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

Specified by:
getQuiet in interface Ehcache
Overrides:
getQuiet 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:
Ehcache.isExpired(net.sf.ehcache.Element)

getWithLoader

public Element getWithLoader(Object key,
                             CacheLoader loader,
                             Object loaderArgument)
                      throws CacheException
Description copied from class: EhcacheDecoratorAdapter
This 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. That is either the CacheLoader passed in, or if null, the one associated with the cache. If both are null, no load is performed and null is returned.

Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

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

getAllWithLoader

public Map getAllWithLoader(Collection keys,
                            Object loaderArgument)
                     throws CacheException
Description copied from class: EhcacheDecoratorAdapter
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.

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

Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

The constructs package provides similar functionality using the decorator SelfPopulatingCache

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

ehcache

Copyright 2001-2014, Terracotta, Inc.