net.sf.ehcache.constructs.eventual
Class StronglyConsistentCacheAccessor

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

• using a read lock for read operations
• using a write lock for write operations
• using a write lock and compound operations for the CAS 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:

• 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

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:

• 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.

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:

• 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

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