net.sf.ehcache.constructs.locking
Class ExplicitLockingCache

java.lang.Object
  net.sf.ehcache.constructs.locking.ExplicitLockingCache

All Implemented Interfaces:

java.lang.Cloneable, net.sf.ehcache.Ehcache

public class ExplicitLockingCache
extends java.lang.Object
implements net.sf.ehcache.Ehcache

See description in package.html

Author:

Steve Harris, Greg Luck

Field Summary

protected net.sf.ehcache.Ehcache

cache The backing Cache

Constructor Summary

ExplicitLockingCache(net.sf.ehcache.Ehcache cache)
Constructor for this decorated cache

Method Summary

void	acquireReadLockOnKey(java.lang.Object key) Acquires the proper read lock for a given cache key
void	acquireWriteLockOnKey(java.lang.Object key) Acquires the proper write lock for a given cache key
void	bootstrap() Bootstrap command.
long	calculateInMemorySize() Gets the size of the memory store for this cache Warning: This method can be very expensive to run.
void	clearStatistics() Resets statistics counters back to 0.
java.lang.Object	clone() Clones a cache.
void	disableDynamicFeatures()
void	dispose() Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
void	evictExpiredElements() Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
void	flush() Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
net.sf.ehcache.Element	get(java.lang.Object key) Looks up an entry.
net.sf.ehcache.Element	get(java.io.Serializable key) Gets an element from the cache.
java.util.Map	getAllWithLoader(java.util.Collection keys, java.lang.Object loaderArgument) This method is not appropriate to use with BlockingCache.
float	getAverageGetTime() The average get time in ms.
net.sf.ehcache.bootstrap.BootstrapCacheLoader	getBootstrapCacheLoader() Accessor for the BootstrapCacheLoader associated with this cache.
protected net.sf.ehcache.Ehcache	getCache() Retrieve the EHCache backing cache
net.sf.ehcache.config.CacheConfiguration	getCacheConfiguration() Gets the cache configuration this cache was created with.
net.sf.ehcache.event.RegisteredEventListeners	getCacheEventNotificationService() Use this to access the service in order to register and unregister listeners
net.sf.ehcache.exceptionhandler.CacheExceptionHandler	getCacheExceptionHandler() Sets an ExceptionHandler on the Cache.
net.sf.ehcache.CacheManager	getCacheManager() Gets the CacheManager managing this cache.
int	getDiskStoreSize() Returns the number of elements in the disk store.
java.lang.String	getGuid() The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.
java.lang.Object	getInternalContext()
java.util.List	getKeys() Returns the keys for this cache.
java.util.List	getKeysNoDuplicateCheck() Returns a list of all elements in the cache, whether or not they are expired.
java.util.List	getKeysWithExpiryCheck() Returns a list of all elements in the cache.
net.sf.ehcache.statistics.LiveCacheStatistics	getLiveCacheStatistics()
protected net.sf.ehcache.concurrent.Sync	getLockForKey(java.lang.Object key) Gets the lock for a given key
long	getMemoryStoreSize() Returns the number of elements in the memory store.
java.lang.String	getName() Returns this cache's name
net.sf.ehcache.Element	getQuiet(java.lang.Object key) Gets an element from the cache, without updating Element statistics.
net.sf.ehcache.Element	getQuiet(java.io.Serializable key) Gets an element from the cache, without updating Element statistics.
java.util.List<net.sf.ehcache.extension.CacheExtension>	getRegisteredCacheExtensions()
java.util.List<net.sf.ehcache.loader.CacheLoader>	getRegisteredCacheLoaders()
net.sf.ehcache.writer.CacheWriter	getRegisteredCacheWriter()
net.sf.ehcache.statistics.sampled.SampledCacheStatistics	getSampledCacheStatistics()
int	getSize() Gets the size of the cache.
int	getSizeBasedOnAccuracy(int statisticsAccuracy)
net.sf.ehcache.Statistics	getStatistics() Gets an immutable Statistics object representing the Cache statistics at the time.
int	getStatisticsAccuracy() Accurately measuring statistics can be expensive.
net.sf.ehcache.Status	getStatus() Gets the status attribute of the Cache.
net.sf.ehcache.Element	getWithLoader(java.lang.Object key, net.sf.ehcache.loader.CacheLoader loader, java.lang.Object loaderArgument) This method is not appropriate to use with BlockingCache.
net.sf.ehcache.writer.CacheWriterManager	getWriterManager()
void	initialise() This method creates a memory or disk store and makes the cache ready to accept elements
boolean	isClusterCoherent()
boolean	isDisabled() Whether this cache is disabled.
boolean	isElementInMemory(java.lang.Object key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementInMemory(java.io.Serializable key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementOnDisk(java.lang.Object key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isElementOnDisk(java.io.Serializable key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isExpired(net.sf.ehcache.Element element) Checks whether this cache element has expired.
boolean	isKeyInCache(java.lang.Object key) An inexpensive check to see if the key exists in the cache.
boolean	isNodeCoherent()
boolean	isSampledStatisticsEnabled()
boolean	isStatisticsEnabled()
boolean	isValueInCache(java.lang.Object value) An extremely expensive check to see if the value exists in the cache.
java.lang.String	liveness() Synchronized version of getName to test liveness of the object lock.
void	load(java.lang.Object key) This method is not appropriate to use with BlockingCache.
void	loadAll(java.util.Collection keys, java.lang.Object argument) This method is not appropriate to use with BlockingCache.
void	put(net.sf.ehcache.Element element) Adds an entry and unlocks it
void	put(net.sf.ehcache.Element element, boolean doNotNotifyCacheReplicators) Put an element in the cache.
boolean	putIfAbsent(net.sf.ehcache.Element element) Put an element in the cache if an element for the key doesn't already exist
void	putQuiet(net.sf.ehcache.Element element) Put an element in the cache, without updating statistics, or updating listeners.
void	putWithWriter(net.sf.ehcache.Element element)
void	registerCacheExtension(net.sf.ehcache.extension.CacheExtension cacheExtension) Register a CacheExtension with the cache.
void	registerCacheLoader(net.sf.ehcache.loader.CacheLoader cacheLoader) Register a CacheLoader with the cache.
void	registerCacheUsageListener(net.sf.ehcache.statistics.CacheUsageListener cacheUsageListener)
void	registerCacheWriter(net.sf.ehcache.writer.CacheWriter cacheWriter)
void	releaseReadLockOnKey(java.lang.Object key) Release a held read lock for the passed in key
void	releaseWriteLockOnKey(java.lang.Object key) Release a held write lock for the passed in key
boolean	remove(java.lang.Object key) Removes an Element from the Cache.
boolean	remove(java.lang.Object key, boolean doNotNotifyCacheReplicators) Removes an Element from the Cache.
boolean	remove(java.io.Serializable key) Removes an Element from the Cache.
boolean	remove(java.io.Serializable key, boolean doNotNotifyCacheReplicators) Removes an Element from the Cache.
void	removeAll() Removes all cached items.
void	removeAll(boolean doNotNotifyCacheReplicators) Removes all cached items.
void	removeCacheUsageListener(net.sf.ehcache.statistics.CacheUsageListener cacheUsageListener)
boolean	removeQuiet(java.lang.Object key) Removes an Element from the Cache, without notifying listeners.
boolean	removeQuiet(java.io.Serializable key) Removes an Element from the Cache, without notifying listeners.
boolean	removeWithWriter(java.lang.Object key)
void	setBootstrapCacheLoader(net.sf.ehcache.bootstrap.BootstrapCacheLoader bootstrapCacheLoader) Sets the bootstrap cache loader.
void	setCacheExceptionHandler(net.sf.ehcache.exceptionhandler.CacheExceptionHandler cacheExceptionHandler) Sets an ExceptionHandler on the Cache.
void	setCacheManager(net.sf.ehcache.CacheManager cacheManager) Sets the CacheManager
void	setDisabled(boolean disabled) Disables or enables this cache.
void	setDiskStorePath(java.lang.String diskStorePath) DiskStore paths can conflict between CacheManager instances.
void	setName(java.lang.String name) Sets the cache name which will name.
void	setNodeCoherent(boolean coherent)
void	setSampledStatisticsEnabled(boolean enabledStatistics)
void	setStatisticsAccuracy(int statisticsAccuracy) Sets the statistics accuracy.
void	setStatisticsEnabled(boolean enabledStatistics)
void	setTransactionManagerLookup(net.sf.ehcache.transaction.manager.TransactionManagerLookup transactionManagerLookup)
boolean	tryReadLockOnKey(java.lang.Object key, long timeout) Try to get a read lock on a given key.
boolean	tryWriteLockOnKey(java.lang.Object key, long timeout) Try to get a write lock on a given key.
void	unregisterCacheExtension(net.sf.ehcache.extension.CacheExtension cacheExtension) Unregister a CacheExtension with the cache.
void	unregisterCacheLoader(net.sf.ehcache.loader.CacheLoader cacheLoader) Unregister a CacheLoader with the cache.
void	unregisterCacheWriter()
void	waitUntilClusterCoherent()

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.ehcache.Ehcache

toString

Field Detail

cache

protected final net.sf.ehcache.Ehcache cache

The backing Cache

Constructor Detail

ExplicitLockingCache

public ExplicitLockingCache(net.sf.ehcache.Ehcache cache)
                     throws net.sf.ehcache.CacheException

Constructor for this decorated cache

Parameters:

cache - the backing cache

Throws:

net.sf.ehcache.CacheException

Method Detail

getCache

protected net.sf.ehcache.Ehcache getCache()

Retrieve the EHCache backing cache

Returns:

the backing cache

getName

public java.lang.String getName()

Returns this cache's name

Specified by:

getName in interface net.sf.ehcache.Ehcache

setName

public void setName(java.lang.String name)

Sets the cache name which will name.

Specified by:

setName in interface net.sf.ehcache.Ehcache

Parameters:

name - the name of the cache. Should not be null.

isExpired

public boolean isExpired(net.sf.ehcache.Element element)
                  throws java.lang.IllegalStateException,
                         java.lang.NullPointerException

Checks whether this cache element has expired.

The element is expired if:

1. the idle time is non-zero and has elapsed, unless the cache is eternal; or
2. the time to live is non-zero and has elapsed, unless the cache is eternal; or
3. the value of the element is null.

Specified by:

isExpired in interface net.sf.ehcache.Ehcache

Returns:

true if it has expired

Throws:

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

java.lang.NullPointerException - if the element is null

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clones a cache. This is only legal if the cache has not been initialized. At that point only primitives have been set and no MemoryStore or DiskStore has been created.

A new, empty, RegisteredEventListeners is created on clone.

Specified by:

clone in interface net.sf.ehcache.Ehcache

Overrides:

clone in class java.lang.Object

Returns:

an object of type Cache

Throws:

java.lang.CloneNotSupportedException

getCacheEventNotificationService

public net.sf.ehcache.event.RegisteredEventListeners getCacheEventNotificationService()

Use this to access the service in order to register and unregister listeners

Specified by:

getCacheEventNotificationService in interface net.sf.ehcache.Ehcache

Returns:

the RegisteredEventListeners instance for this cache.

isElementInMemory

public boolean isElementInMemory(java.io.Serializable key)

Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

Specified by:

isElementInMemory in interface net.sf.ehcache.Ehcache

Returns:

true if an element matching the key is found in memory

isElementInMemory

public boolean isElementInMemory(java.lang.Object key)

Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

Specified by:

isElementInMemory in interface net.sf.ehcache.Ehcache

Returns:

true if an element matching the key is found in memory

Since:

1.2

isElementOnDisk

public boolean isElementOnDisk(java.io.Serializable key)

Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

Specified by:

isElementOnDisk in interface net.sf.ehcache.Ehcache

Returns:

true if an element matching the key is found in the diskStore

isElementOnDisk

public boolean isElementOnDisk(java.lang.Object key)

Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

Specified by:

isElementOnDisk in interface net.sf.ehcache.Ehcache

Returns:

true if an element matching the key is found in the diskStore

Since:

1.2

getGuid

public java.lang.String getGuid()

The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.

Specified by:

getGuid in interface net.sf.ehcache.Ehcache

Returns:

the globally unique identifier for this cache instance. This is guaranteed to be unique.

Since:

1.2

getCacheManager

public net.sf.ehcache.CacheManager getCacheManager()

Gets the CacheManager managing this cache. For a newly created cache this will be null until it has been added to a CacheManager.

Specified by:

getCacheManager in interface net.sf.ehcache.Ehcache

Returns:

the manager or null if there is none

clearStatistics

public void clearStatistics()

Resets statistics counters back to 0.

Specified by:

clearStatistics in interface net.sf.ehcache.Ehcache

getStatisticsAccuracy

public int getStatisticsAccuracy()

Accurately measuring statistics can be expensive. Returns the current accuracy setting.

Specified by:

getStatisticsAccuracy in interface net.sf.ehcache.Ehcache

Returns:

one of Statistics.STATISTICS_ACCURACY_BEST_EFFORT , Statistics.STATISTICS_ACCURACY_GUARANTEED, Statistics.STATISTICS_ACCURACY_NONE

setStatisticsAccuracy

public void setStatisticsAccuracy(int statisticsAccuracy)

Sets the statistics accuracy.

Specified by:

setStatisticsAccuracy in interface net.sf.ehcache.Ehcache

Parameters:

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

evictExpiredElements

public void evictExpiredElements()

Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.

Specified by:

evictExpiredElements in interface net.sf.ehcache.Ehcache

isKeyInCache

public boolean isKeyInCache(java.lang.Object key)

An inexpensive check to see if the key exists in the cache.

Specified by:

isKeyInCache in interface net.sf.ehcache.Ehcache

Parameters:

key - the key to check for

Returns:

true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

isValueInCache

public boolean isValueInCache(java.lang.Object value)

An extremely expensive check to see if the value exists in the cache.

Specified by:

isValueInCache in interface net.sf.ehcache.Ehcache

Parameters:

value - to check for

Returns:

true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

getStatistics

public net.sf.ehcache.Statistics getStatistics()
                                        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 Statistics.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 Statistics.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 Statistics.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:

getStatistics in interface net.sf.ehcache.Ehcache

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

getLiveCacheStatistics

public net.sf.ehcache.statistics.LiveCacheStatistics getLiveCacheStatistics()
                                                                     throws java.lang.IllegalStateException

Specified by:

getLiveCacheStatistics in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalStateException

setCacheManager

public void setCacheManager(net.sf.ehcache.CacheManager cacheManager)

Sets the CacheManager

Specified by:

setCacheManager in interface net.sf.ehcache.Ehcache

Parameters:

cacheManager - the CacheManager this cache belongs to

getBootstrapCacheLoader

public net.sf.ehcache.bootstrap.BootstrapCacheLoader getBootstrapCacheLoader()

Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.

Specified by:

getBootstrapCacheLoader in interface net.sf.ehcache.Ehcache

setBootstrapCacheLoader

public void setBootstrapCacheLoader(net.sf.ehcache.bootstrap.BootstrapCacheLoader bootstrapCacheLoader)
                             throws net.sf.ehcache.CacheException

Sets the bootstrap cache loader.

Specified by:

setBootstrapCacheLoader in interface net.sf.ehcache.Ehcache

Parameters:

bootstrapCacheLoader - the loader to be used

Throws:

net.sf.ehcache.CacheException - if this method is called after the cache is initialized

setDiskStorePath

public void setDiskStorePath(java.lang.String diskStorePath)
                      throws net.sf.ehcache.CacheException

DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.

Specified by:

setDiskStorePath in interface net.sf.ehcache.Ehcache

Parameters:

diskStorePath - the new path to be used.

Throws:

net.sf.ehcache.CacheException - if this method is called after the cache is initialized

initialise

public void initialise()

This method creates a memory or disk store and makes the cache ready to accept elements

Specified by:

initialise in interface net.sf.ehcache.Ehcache

bootstrap

public void bootstrap()

Bootstrap command. This must be called after the Cache is intialised, during CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager initialise completes, otherwise they will happen in the background.

Specified by:

bootstrap in interface net.sf.ehcache.Ehcache

dispose

public void dispose()
             throws java.lang.IllegalStateException

Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.

Should be invoked only by CacheManager.

Specified by:

dispose in interface net.sf.ehcache.Ehcache

Throws:

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

getCacheConfiguration

public net.sf.ehcache.config.CacheConfiguration getCacheConfiguration()

Gets the cache configuration this cache was created with.

Things like listeners that are added dynamically are excluded.

Specified by:

getCacheConfiguration in interface net.sf.ehcache.Ehcache

get

public net.sf.ehcache.Element get(java.lang.Object key)
                           throws java.lang.RuntimeException,
                                  net.sf.ehcache.constructs.blocking.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 net.sf.ehcache.Ehcache

Throws:

net.sf.ehcache.constructs.blocking.LockTimeoutException - if timeout millis is non zero and this method has been unable to acquire a lock in that time

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

put

public void put(net.sf.ehcache.Element element)

Adds an entry and unlocks it

Specified by:

put in interface net.sf.ehcache.Ehcache

put

public void put(net.sf.ehcache.Element element,
                boolean doNotNotifyCacheReplicators)
         throws java.lang.IllegalArgumentException,
                java.lang.IllegalStateException,
                net.sf.ehcache.CacheException

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 net.sf.ehcache.Ehcache

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:

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

java.lang.IllegalArgumentException - if the element is null

net.sf.ehcache.CacheException

putQuiet

public void putQuiet(net.sf.ehcache.Element element)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalStateException,
                     net.sf.ehcache.CacheException

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

Specified by:

putQuiet in interface net.sf.ehcache.Ehcache

Parameters:

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

Throws:

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

java.lang.IllegalArgumentException - if the element is null

net.sf.ehcache.CacheException

get

public net.sf.ehcache.Element get(java.io.Serializable key)
                           throws java.lang.IllegalStateException,
                                  net.sf.ehcache.CacheException

Gets an element from the cache. Updates Element Statistics

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

Specified by:

get in interface net.sf.ehcache.Ehcache

Parameters:

key - a serializable value

Returns:

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

Throws:

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

net.sf.ehcache.CacheException

See Also:

isExpired(net.sf.ehcache.Element)

getQuiet

public net.sf.ehcache.Element getQuiet(java.io.Serializable key)
                                throws java.lang.IllegalStateException,
                                       net.sf.ehcache.CacheException

Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

Specified by:

getQuiet in interface net.sf.ehcache.Ehcache

Parameters:

key - a serializable value

Returns:

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

Throws:

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

net.sf.ehcache.CacheException

See Also:

isExpired(net.sf.ehcache.Element)

getQuiet

public net.sf.ehcache.Element getQuiet(java.lang.Object key)
                                throws java.lang.IllegalStateException,
                                       net.sf.ehcache.CacheException

Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

Specified by:

getQuiet in interface net.sf.ehcache.Ehcache

Parameters:

key - a serializable value

Returns:

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

Throws:

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

net.sf.ehcache.CacheException

Since:

1.2

See Also:

isExpired(net.sf.ehcache.Element)

getKeys

public java.util.List getKeys()
                       throws net.sf.ehcache.CacheException

Returns the keys for this cache.

Specified by:

getKeys in interface net.sf.ehcache.Ehcache

Returns:

a list of Object keys for this cache. This is not a live set, so it will not track changes to the key set.

Throws:

net.sf.ehcache.CacheException

getKeysWithExpiryCheck

public java.util.List getKeysWithExpiryCheck()
                                      throws java.lang.IllegalStateException,
                                             net.sf.ehcache.CacheException

Returns a list of all elements in the cache. Only keys of non-expired elements are returned.

The returned keys are unique and can be considered a set.

The List returned is not live. It is a copy.

The time taken is O(n), where n is the number of elements in the cache. On a 1.8Ghz P4, the time taken is approximately 200ms per 1000 entries. This method is not synchronized, because it relies on a non-live list returned from getKeys() , which is synchronised, and which takes 8ms per 1000 entries. This way cache liveness is preserved, even if this method is very slow to return.

Consider whether your usage requires checking for expired keys. Because this method takes so long, depending on cache settings, the list could be quite out of date by the time you get it.

Specified by:

getKeysWithExpiryCheck in interface net.sf.ehcache.Ehcache

Returns:

a list of Object keys

Throws:

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

net.sf.ehcache.CacheException

getKeysNoDuplicateCheck

public java.util.List getKeysNoDuplicateCheck()
                                       throws java.lang.IllegalStateException

Returns a list of all elements in the cache, whether or not they are expired.

The returned keys are not unique and may contain duplicates. If the cache is only using the memory store, the list will be unique. If the disk store is being used as well, it will likely contain duplicates, because of the internal store design.

The List returned is not live. It is a copy.

The time taken is O(log n). On a single cpu 1.8Ghz P4, approximately 6ms is required for 1000 entries and 36 for 50000.

This is the fastest getKeys method

Specified by:

getKeysNoDuplicateCheck in interface net.sf.ehcache.Ehcache

Returns:

a list of Object keys

Throws:

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

remove

public boolean remove(java.io.Serializable key)
               throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

Returns:

true if the element was removed, false if it was not found in the cache

Throws:

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

remove

public boolean remove(java.lang.Object key)
               throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

Returns:

true if the element was removed, false if it was not found in the cache

Throws:

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

Since:

1.2

remove

public boolean remove(java.io.Serializable key,
                      boolean doNotNotifyCacheReplicators)
               throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

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:

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

remove

public boolean remove(java.lang.Object key,
                      boolean doNotNotifyCacheReplicators)
               throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

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:

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

removeQuiet

public boolean removeQuiet(java.io.Serializable key)
                    throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

Returns:

true if the element was removed, false if it was not found in the cache

Throws:

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

removeQuiet

public boolean removeQuiet(java.lang.Object key)
                    throws java.lang.IllegalStateException

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 net.sf.ehcache.Ehcache

Parameters:

key - the key to remove

Returns:

true if the element was removed, false if it was not found in the cache

Throws:

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

Since:

1.2

removeAll

public void removeAll()
               throws java.lang.IllegalStateException,
                      net.sf.ehcache.CacheException

Removes all cached items.

Specified by:

removeAll in interface net.sf.ehcache.Ehcache

Throws:

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

net.sf.ehcache.CacheException

removeAll

public void removeAll(boolean doNotNotifyCacheReplicators)
               throws java.lang.IllegalStateException,
                      net.sf.ehcache.CacheException

Removes all cached items.

Specified by:

removeAll in interface net.sf.ehcache.Ehcache

Parameters:

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:

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

net.sf.ehcache.CacheException

flush

public void flush()
           throws java.lang.IllegalStateException,
                  net.sf.ehcache.CacheException

Flushes all cache items from memory to the disk store, and from the DiskStore to disk.

Specified by:

flush in interface net.sf.ehcache.Ehcache

Throws:

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

net.sf.ehcache.CacheException

getSize

public int getSize()
            throws java.lang.IllegalStateException,
                   net.sf.ehcache.CacheException

Gets the size of the cache. This is a subtle concept. See below.

The size is the number of Elements in the MemoryStore plus the number of Elements in the net.sf.ehcache.store.DiskStore.

This number is the actual number of elements, including expired elements that have not been removed.

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.

To get an exact size, which would exclude expired elements, use getKeysWithExpiryCheck().size(), although see that method for the approximate time that would take.

To get a very fast result, use getKeysNoDuplicateCheck().size(). If the disk store is being used, there will be some duplicates.

Specified by:

getSize in interface net.sf.ehcache.Ehcache

Returns:

The size value

Throws:

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

net.sf.ehcache.CacheException

getSizeBasedOnAccuracy

public int getSizeBasedOnAccuracy(int statisticsAccuracy)
                           throws java.lang.IllegalStateException,
                                  net.sf.ehcache.CacheException

Specified by:

getSizeBasedOnAccuracy in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalStateException

net.sf.ehcache.CacheException

calculateInMemorySize

public long calculateInMemorySize()
                           throws java.lang.IllegalStateException,
                                  net.sf.ehcache.CacheException

Gets the size of the memory store for this cache

Warning: This method can be very expensive to run. Allow approximately 1 second per 1MB of entries. Running this method could create liveness problems because the object lock is held for a long period

Specified by:

calculateInMemorySize in interface net.sf.ehcache.Ehcache

Returns:

the approximate size of the memory store in bytes

Throws:

java.lang.IllegalStateException

net.sf.ehcache.CacheException

getMemoryStoreSize

public long getMemoryStoreSize()
                        throws java.lang.IllegalStateException

Returns the number of elements in the memory store.

Specified by:

getMemoryStoreSize in interface net.sf.ehcache.Ehcache

Returns:

the number of elements in the memory store

Throws:

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

getDiskStoreSize

public int getDiskStoreSize()
                     throws java.lang.IllegalStateException

Returns the number of elements in the disk store.

Specified by:

getDiskStoreSize in interface net.sf.ehcache.Ehcache

Returns:

the number of elements in the disk store.

Throws:

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

getStatus

public net.sf.ehcache.Status getStatus()

Gets the status attribute of the Cache.

Specified by:

getStatus in interface net.sf.ehcache.Ehcache

Returns:

The status value from the Status enum class

liveness

public java.lang.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.

registerCacheExtension

public void registerCacheExtension(net.sf.ehcache.extension.CacheExtension cacheExtension)

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

Specified by:

registerCacheExtension in interface net.sf.ehcache.Ehcache

unregisterCacheExtension

public void unregisterCacheExtension(net.sf.ehcache.extension.CacheExtension cacheExtension)

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

Specified by:

unregisterCacheExtension in interface net.sf.ehcache.Ehcache

getRegisteredCacheExtensions

public java.util.List<net.sf.ehcache.extension.CacheExtension> getRegisteredCacheExtensions()

Specified by:

getRegisteredCacheExtensions in interface net.sf.ehcache.Ehcache

Returns:

the cache extensions as a live list

getAverageGetTime

public float getAverageGetTime()

The average get time in ms.

Specified by:

getAverageGetTime in interface net.sf.ehcache.Ehcache

setCacheExceptionHandler

public void setCacheExceptionHandler(net.sf.ehcache.exceptionhandler.CacheExceptionHandler cacheExceptionHandler)

Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.

Specified by:

setCacheExceptionHandler in interface net.sf.ehcache.Ehcache

getCacheExceptionHandler

public net.sf.ehcache.exceptionhandler.CacheExceptionHandler getCacheExceptionHandler()

Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.

Specified by:

getCacheExceptionHandler in interface net.sf.ehcache.Ehcache

registerCacheLoader

public void registerCacheLoader(net.sf.ehcache.loader.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 net.sf.ehcache.Ehcache

Parameters:

cacheLoader - A Cache Loader to register

unregisterCacheLoader

public void unregisterCacheLoader(net.sf.ehcache.loader.CacheLoader cacheLoader)

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

Specified by:

unregisterCacheLoader in interface net.sf.ehcache.Ehcache

Parameters:

cacheLoader - A Cache Loader to unregister

getRegisteredCacheLoaders

public java.util.List<net.sf.ehcache.loader.CacheLoader> getRegisteredCacheLoaders()

Specified by:

getRegisteredCacheLoaders in interface net.sf.ehcache.Ehcache

Returns:

the cache loaders as a live list

getWithLoader

public net.sf.ehcache.Element getWithLoader(java.lang.Object key,
                                            net.sf.ehcache.loader.CacheLoader loader,
                                            java.lang.Object loaderArgument)
                                     throws net.sf.ehcache.CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

getWithLoader in interface net.sf.ehcache.Ehcache

Throws:

net.sf.ehcache.CacheException - if this method is called

getAllWithLoader

public java.util.Map getAllWithLoader(java.util.Collection keys,
                                      java.lang.Object loaderArgument)
                               throws net.sf.ehcache.CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

getAllWithLoader in interface net.sf.ehcache.Ehcache

Throws:

net.sf.ehcache.CacheException - if this method is called

load

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

This method is not appropriate to use with BlockingCache.

Specified by:

load in interface net.sf.ehcache.Ehcache

Throws:

net.sf.ehcache.CacheException - if this method is called

loadAll

public void loadAll(java.util.Collection keys,
                    java.lang.Object argument)
             throws net.sf.ehcache.CacheException

This method is not appropriate to use with BlockingCache.

Specified by:

loadAll in interface net.sf.ehcache.Ehcache

Throws:

net.sf.ehcache.CacheException - if this method is called

isDisabled

public boolean isDisabled()

Whether this cache is disabled. "Disabled" means:

1. bootstrap is disabled
2. puts are discarded
3. putQuites are discarded

In all other respects the cache continues as it is.

You can disable and enable a cache programmatically through the setDisabled(boolean) method.

By default caches are enabled on creation, unless the net.sf.ehcache.disabled system property is set.

Specified by:

isDisabled in interface net.sf.ehcache.Ehcache

Returns:

true if the cache is disabled.

setDisabled

public void setDisabled(boolean disabled)

Disables or enables this cache. This call overrides the previous value of disabled, even if the net.sf.ehcache.disabled system property is set

Specified by:

setDisabled in interface net.sf.ehcache.Ehcache

Parameters:

disabled - true if you wish to disable, false to enable

See Also:

isDisabled()

registerCacheUsageListener

public void registerCacheUsageListener(net.sf.ehcache.statistics.CacheUsageListener cacheUsageListener)
                                throws java.lang.IllegalStateException

Specified by:

registerCacheUsageListener in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalStateException

removeCacheUsageListener

public void removeCacheUsageListener(net.sf.ehcache.statistics.CacheUsageListener cacheUsageListener)
                              throws java.lang.IllegalStateException

Specified by:

removeCacheUsageListener in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalStateException

isStatisticsEnabled

public boolean isStatisticsEnabled()

Specified by:

isStatisticsEnabled in interface net.sf.ehcache.Ehcache

setStatisticsEnabled

public void setStatisticsEnabled(boolean enabledStatistics)

Specified by:

setStatisticsEnabled in interface net.sf.ehcache.Ehcache

getSampledCacheStatistics

public net.sf.ehcache.statistics.sampled.SampledCacheStatistics getSampledCacheStatistics()

Specified by:

getSampledCacheStatistics in interface net.sf.ehcache.Ehcache

setSampledStatisticsEnabled

public void setSampledStatisticsEnabled(boolean enabledStatistics)

Specified by:

setSampledStatisticsEnabled in interface net.sf.ehcache.Ehcache

isSampledStatisticsEnabled

public boolean isSampledStatisticsEnabled()

Specified by:

isSampledStatisticsEnabled in interface net.sf.ehcache.Ehcache

See Also:

Ehcache.isSampledStatisticsEnabled()

getInternalContext

public java.lang.Object getInternalContext()

Specified by:

getInternalContext in interface net.sf.ehcache.Ehcache

getLockForKey

protected net.sf.ehcache.concurrent.Sync getLockForKey(java.lang.Object key)

Gets the lock for a given key

Parameters:

key -

Returns:

the lock object for the passed in key

acquireReadLockOnKey

public void acquireReadLockOnKey(java.lang.Object key)

Acquires the proper read lock for a given cache key

Parameters:

key - - The key that retrieves a value that you want to protect via locking

acquireWriteLockOnKey

public void acquireWriteLockOnKey(java.lang.Object key)

Acquires the proper write lock for a given cache key

Parameters:

key - - The key that retrieves a value that you want to protect via locking

releaseReadLockOnKey

public void releaseReadLockOnKey(java.lang.Object key)

Release a held read lock for the passed in key

Parameters:

key - - The key that retrieves a value that you want to protect via locking

releaseWriteLockOnKey

public void releaseWriteLockOnKey(java.lang.Object key)

Release a held write lock for the passed in key

Parameters:

key - - The key that retrieves a value that you want to protect via locking

tryReadLockOnKey

public boolean tryReadLockOnKey(java.lang.Object key,
                                long timeout)
                         throws java.lang.InterruptedException

Try to get a read lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock

Parameters:

key - - The key that retrieves a value that you want to protect via locking

timeout - - millis until giveup on getting the lock

Returns:

whether the lock was awarded

Throws:

java.lang.InterruptedException

tryWriteLockOnKey

public boolean tryWriteLockOnKey(java.lang.Object key,
                                 long timeout)
                          throws java.lang.InterruptedException

Try to get a write lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock

Parameters:

key - - The key that retrieves a value that you want to protect via locking

timeout - - millis until giveup on getting the lock

Returns:

whether the lock was awarded

Throws:

java.lang.InterruptedException

putIfAbsent

public boolean putIfAbsent(net.sf.ehcache.Element element)

Put an element in the cache if an element for the key doesn't already exist

Parameters:

element - to add to the cache

Returns:

boolean did a put occur

disableDynamicFeatures

public void disableDynamicFeatures()

Specified by:

disableDynamicFeatures in interface net.sf.ehcache.Ehcache

putWithWriter

public void putWithWriter(net.sf.ehcache.Element element)
                   throws java.lang.IllegalArgumentException,
                          java.lang.IllegalStateException,
                          net.sf.ehcache.CacheException

Specified by:

putWithWriter in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalStateException

net.sf.ehcache.CacheException

removeWithWriter

public boolean removeWithWriter(java.lang.Object key)
                         throws java.lang.IllegalStateException

Specified by:

removeWithWriter in interface net.sf.ehcache.Ehcache

Throws:

java.lang.IllegalStateException

registerCacheWriter

public void registerCacheWriter(net.sf.ehcache.writer.CacheWriter cacheWriter)

Specified by:

registerCacheWriter in interface net.sf.ehcache.Ehcache

unregisterCacheWriter

public void unregisterCacheWriter()

Specified by:

unregisterCacheWriter in interface net.sf.ehcache.Ehcache

getRegisteredCacheWriter

public net.sf.ehcache.writer.CacheWriter getRegisteredCacheWriter()

Specified by:

getRegisteredCacheWriter in interface net.sf.ehcache.Ehcache

getWriterManager

public net.sf.ehcache.writer.CacheWriterManager getWriterManager()

Specified by:

getWriterManager in interface net.sf.ehcache.Ehcache

isNodeCoherent

public boolean isNodeCoherent()

Specified by:

isNodeCoherent in interface net.sf.ehcache.Ehcache

isClusterCoherent

public boolean isClusterCoherent()

Specified by:

isClusterCoherent in interface net.sf.ehcache.Ehcache

setNodeCoherent

public void setNodeCoherent(boolean coherent)
                     throws java.lang.UnsupportedOperationException

Specified by:

setNodeCoherent in interface net.sf.ehcache.Ehcache

Throws:

java.lang.UnsupportedOperationException

waitUntilClusterCoherent

public void waitUntilClusterCoherent()

Specified by:

waitUntilClusterCoherent in interface net.sf.ehcache.Ehcache

setTransactionManagerLookup

public void setTransactionManagerLookup(net.sf.ehcache.transaction.manager.TransactionManagerLookup transactionManagerLookup)

Specified by:

setTransactionManagerLookup in interface net.sf.ehcache.Ehcache