net.sf.ehcache
Class Cache

java.lang.Object
  net.sf.ehcache.Cache

All Implemented Interfaces:

Cloneable, EventListener, Ehcache, StoreListener

public class Cache
extends Object
implements Ehcache, StoreListener

Cache is the central class in ehcache. Caches have Elements and are managed by the CacheManager. The Cache performs logical actions. It delegates physical implementations to its Stores.

A reference to a Cache can be obtained through the CacheManager. A Cache thus obtained is guaranteed to have status Status.STATUS_ALIVE. This status is checked for any method which throws IllegalStateException and the same thrown if it is not alive. This would normally happen if a call is made after CacheManager.shutdown() is invoked.

Cache is threadsafe.

Statistics on cache usage are collected and made available through the getStatistics() methods.

Various decorators are available for Cache, such as BlockingCache, SelfPopulatingCache and the dynamic proxy ExceptionHandlingDynamicCacheProxy. See each class for details.

Version:

$Id: Cache.java 4141 2011-06-20 07:14:07Z lorban $

Author:

Greg Luck, Geert Bevin

Field Summary

static String	DEFAULT_CACHE_NAME A reserved word for cache names.
static long	DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS The default interval between runs of the expiry thread.
static String	NET_SF_EHCACHE_DISABLED System Property based method of disabling ehcache.
static String	NET_SF_EHCACHE_USE_CLASSIC_LRU System Property based method of selecting the LruMemoryStore in use up to ehcache 1.5.

Constructor Summary

Cache(CacheConfiguration cacheConfiguration)
2.0 and higher Constructor

The ConfigurationFactory and clients can create these.

Cache(CacheConfiguration cacheConfiguration, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader)
2.0 and higher Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds)
1.0 Constructor.

Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds)
1.1 Constructor.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners)
1.2 Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader)
1.2.1 Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk)
1.2.4 Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk, int diskSpoolBufferSizeMB)
1.3 Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk, int diskSpoolBufferSizeMB, boolean clearOnFlush)
1.6.0 Constructor

The ConfigurationFactory and clients can create these.

Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk, int diskSpoolBufferSizeMB, boolean clearOnFlush, boolean isTerracottaClustered, String terracottaValueMode, boolean terracottaCoherentReads)
1.7.0 Constructor

The ConfigurationFactory and clients can create these.

Method Summary

void	acquireReadLockOnKey(Object key) Acquires the proper read lock for a given cache key
void	acquireWriteLockOnKey(Object key) Acquires the proper write lock for a given cache key
void	addPropertyChangeListener(PropertyChangeListener listener) Add a PropertyChangeListener.
void	bootstrap() Bootstrap command.
long	calculateInMemorySize() Gets the size of the memory store for this cache.
long	calculateOffHeapSize() Gets the size of the off-heap store for this cache.
void	clearStatistics() Resets statistics counters back to 0.
Cache	clone() Clones a cache.
void	clusterCoherent(boolean clusterCoherent) Inform of cluster coherence.
protected DiskStore	createDiskStore() Creates a disk store when either: overflowToDisk is enabled diskPersistent is enabled
Query	createQuery() Create a new query builder for this cache
void	disableDynamicFeatures() Disables dynamic configuration and disable/enable for this cache.
void	dispose() Starts an orderly shutdown of the Cache.
boolean	equals(Object object) An equals method which follows the contract of Object.equals(Object) An Cache is equal to another one if it implements Ehcache and has the same GUID.
void	evictExpiredElements() Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
void	firePropertyChange(String propertyName, Object oldValue, Object newValue)
void	flush() Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
Element	get(Object key) Gets an element from the cache.
Element	get(Serializable key) Gets an element from the cache.
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".
float	getAverageGetTime() The average get time in ms.
long	getAverageSearchTime() Get the average search execution time (in millis) for searches that have completed in the last sample period
BootstrapCacheLoader	getBootstrapCacheLoader() Accessor for the BootstrapCacheLoader associated with this cache.
CacheConfiguration	getCacheConfiguration() Gets the cache configuration this cache was created with.
RegisteredEventListeners	getCacheEventNotificationService() Use this to access the service in order to register and unregister listeners
CacheExceptionHandler	getCacheExceptionHandler() Gets the ExceptionHandler on this Cache, or null if there isn't one.
CacheManager	getCacheManager() Gets the CacheManager managing this cache.
int	getDiskStoreSize() Returns the number of elements in the disk store.
String	getGuid() The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.
Object	getInternalContext() This should not be used return some internal context (generally will be null)
List	getKeys() Returns a list of all element keys in the cache, whether or not they are expired.
List	getKeysNoDuplicateCheck() Returns a list of all elements in the cache, whether or not they are expired.
List	getKeysWithExpiryCheck() Returns a list of all element keys in the cache.
LiveCacheStatistics	getLiveCacheStatistics() This is different from Ehcache.getStatistics() in the way that values returned from LiveCacheStatistics will reflect the current state of the cache (and not a snapshot of the cache when the api's were called like Ehcache.getStatistics())
protected Sync	getLockForKey(Object key) Gets the lock for a given key
Policy	getMemoryStoreEvictionPolicy()
long	getMemoryStoreSize() Returns the number of elements in the memory store.
String	getName() Gets the cache name.
long	getOffHeapStoreSize() Returns the number of elements in the off-heap store.
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.
List<CacheExtension>	getRegisteredCacheExtensions()
List<CacheLoader>	getRegisteredCacheLoaders()
CacheWriter	getRegisteredCacheWriter() Retrieves the CacheWriter that was registered for this cache.
SampledCacheStatistics	getSampledCacheStatistics() Returns sampled statistics for this cache.
<T> Attribute<T>	getSearchAttribute(String attributeName) Retrieve the given named search attribute
long	getSearchesPerSecond() Get the number of search executions that have completed in the last second
int	getSize() Gets the size of the cache.
int	getSizeBasedOnAccuracy(int statisticsAccuracy) Accurately measuring statistics can be expensive.
Statistics	getStatistics() Gets an immutable Statistics object representing the Cache statistics at the time.
int	getStatisticsAccuracy() Accurately measuring statistics can be expensive.
Status	getStatus() Gets the status attribute of the Cache.
Object	getStoreMBean() Get the optional store management bean for this cache.
TransactionManagerLookup	getTransactionManagerLookup() Get the TransactionManagerLookup implementation used to lookup the TransactionManager.
Element	getWithLoader(Object key, CacheLoader loader, Object loaderArgument) This method will return, from the cache, the Element associated with the argument "key".
CacheWriterManager	getWriterManager() Obtain the writer manager that's used by this cache instance.
int	hashCode() Returns a hash code value for the object.
void	initialise() Newly created caches do not have a Store.
boolean	isClusterBulkLoadEnabled() Returns true if at least one node in the cluster is in bulk-load mode.
boolean	isClusterCoherent() Deprecated. use isClusterBulkLoadEnabled() instead
boolean	isDisabled() Whether this cache is disabled.
protected boolean	isDiskStore() Whether this cache uses a disk store
boolean	isElementInMemory(Object key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementInMemory(Serializable key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementOffHeap(Object key) Whether an Element is stored in the cache in off-heap memory, indicating an intermediate cost of retrieval.
boolean	isElementOnDisk(Object key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isElementOnDisk(Serializable key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isExpired(Element element) Checks whether this cache element has expired.
boolean	isKeyInCache(Object key) An inexpensive check to see if the key exists in the cache.
boolean	isNodeBulkLoadEnabled() Returns true if the current node is in bulk-load mode.
boolean	isNodeCoherent() Deprecated. use isNodeBulkLoadEnabled() instead
boolean	isReadLockedByCurrentThread(Object key) Returns true if a read lock for the key is held by the current thread
boolean	isSampledStatisticsEnabled() Returns if sampled statistics collection is enabled or disabled
boolean	isSearchable() Is this cache searchable?
boolean	isStatisticsEnabled() Returns true if statistics collection is enabled
boolean	isTerracottaClustered() Indicates whether this cache is clustered by Terracotta
boolean	isValueInCache(Object value) An extremely expensive check to see if the value exists in the cache.
boolean	isWriteLockedByCurrentThread(Object key) Returns true if a write lock for the key is held by the current thread
void	load(Object key) The load method provides a means to "pre load" the cache.
void	loadAll(Collection keys, Object argument) The loadAll method provides a means to "pre load" objects into the cache.
void	put(Element element) Put an element in the cache.
void	put(Element element, boolean doNotNotifyCacheReplicators) Put an element in the cache.
Element	putIfAbsent(Element element) Put an element in the cache if no element is currently mapped to the elements key.
void	putQuiet(Element element) Put an element in the cache, without updating statistics, or updating listeners.
void	putWithWriter(Element element) Put an element in the cache writing through a CacheWriter.
void	registerCacheExtension(CacheExtension cacheExtension) Register a CacheExtension with the cache.
void	registerCacheLoader(CacheLoader cacheLoader) Register a CacheLoader with the cache.
void	registerCacheUsageListener(CacheUsageListener cacheUsageListener) Registers a CacheUsageListener which will be notified of the cache usage.
void	registerCacheWriter(CacheWriter cacheWriter) Register the CacheWriter for this cache.
void	releaseReadLockOnKey(Object key) Release a held read lock for the passed in key
void	releaseWriteLockOnKey(Object key) Release a held write lock for the passed in key
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() Removes all cached items.
void	removeAll(boolean doNotNotifyCacheReplicators) Removes all cached items.
void	removeCacheUsageListener(CacheUsageListener cacheUsageListener) Remove an already registered CacheUsageListener, if any.
boolean	removeElement(Element element) Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a PropertyChangeListener.
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.
void	setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) Sets the bootstrap cache loader.
void	setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler) Sets an ExceptionHandler on the Cache.
void	setCacheManager(CacheManager cacheManager) For use by CacheManager.
void	setDisabled(boolean disabled) Disables or enables this cache.
void	setDiskStorePath(String diskStorePath) DiskStore paths can conflict between CacheManager instances.
void	setMemoryStoreEvictionPolicy(Policy policy) Sets the eviction policy strategy.
void	setName(String name) Sets the cache name which will name.
void	setNodeBulkLoadEnabled(boolean enabledBulkLoad) Enable/disable bulk-load mode in this node for this cache.
void	setNodeCoherent(boolean coherent) Deprecated. use setNodeBulkLoadEnabled(boolean) instead
void	setSampledStatisticsEnabled(boolean enableStatistics) Enable/disable sampled statistics collection.
void	setStatisticsAccuracy(int statisticsAccuracy) Sets the statistics accuracy.
void	setStatisticsEnabled(boolean enableStatistics) Enable/disable statistics collection.
void	setTransactionManagerLookup(TransactionManagerLookup lookup) Sets the TransactionManagerLookup that needs to be used for this cache to lookup the TransactionManager This needs to be set before initialise() is called
String	toString() Returns a String representation of Cache.
boolean	tryReadLockOnKey(Object key, long timeout) Try to get a read lock on a given key.
boolean	tryWriteLockOnKey(Object key, long timeout) Try to get a write lock on a given key.
void	unregisterCacheExtension(CacheExtension cacheExtension) Unregister a CacheExtension with the cache.
void	unregisterCacheLoader(CacheLoader cacheLoader) Unregister a CacheLoader with the cache.
void	unregisterCacheWriter() Unregister the CacheWriter from the cache.
void	waitUntilClusterBulkLoadComplete() This method waits until all the connected nodes have disabled bulk-load.
void	waitUntilClusterCoherent() Deprecated. use waitUntilClusterBulkLoadComplete() instead

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_CACHE_NAME

public static final String DEFAULT_CACHE_NAME

A reserved word for cache names. It denotes a default configuration which is applied to caches created without configuration.

See Also:

Constant Field Values

NET_SF_EHCACHE_DISABLED

public static final String NET_SF_EHCACHE_DISABLED

System Property based method of disabling ehcache. If disabled no elements will be added to a cache.

Set the property "net.sf.ehcache.disabled=true" to disable ehcache.

This can easily be done using java -Dnet.sf.ehcache.disabled=true in the command line.

See Also:

Constant Field Values

NET_SF_EHCACHE_USE_CLASSIC_LRU

public static final String NET_SF_EHCACHE_USE_CLASSIC_LRU

System Property based method of selecting the LruMemoryStore in use up to ehcache 1.5. This is provided for ease of migration.

Set the property "net.sf.ehcache.use.classic.lru=true" to use the older LruMemoryStore implementation when LRU is selected as the eviction policy.

This can easily be done using java -Dnet.sf.ehcache.use.classic.lru=true in the command line.

See Also:

Constant Field Values

DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS

public static final long DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS

The default interval between runs of the expiry thread.

See Also:

CacheConfiguration#DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS for a preferred way of setting, Constant Field Values

Constructor Detail

Cache

public Cache(CacheConfiguration cacheConfiguration)

2.0 and higher Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

cacheConfiguration - the configuration that should be used to create the cache with

Cache

public Cache(CacheConfiguration cacheConfiguration,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader)

2.0 and higher Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

cacheConfiguration - the configuration that should be used to create the cache with

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

Cache

public Cache(String name,
             int maxElementsInMemory,
             boolean overflowToDisk,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds)

1.0 Constructor.

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

This constructor creates disk stores, if specified, that do not persist between restarts.

The default expiry thread interval of 120 seconds is used. This is the interval between runs of the expiry thread, where it checks the disk store for expired elements. It is not the the timeToLiveSeconds.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

overflowToDisk - whether to use the disk store

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

Since:

1.0

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             boolean overflowToDisk,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds)

1.1 Constructor.

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

overflowToDisk - whether to use the disk store

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

Since:

1.1

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners)

1.2 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

Since:

1.2

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader)

1.2.1 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

Since:

1.2.1

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader,
             int maxElementsOnDisk)

1.2.4 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

maxElementsOnDisk - the maximum number of Elements to allow on the disk. 0 means unlimited.

Since:

1.2.4

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader,
             int maxElementsOnDisk,
             int diskSpoolBufferSizeMB)

1.3 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

maxElementsOnDisk - the maximum number of Elements to allow on the disk. 0 means unlimited.

diskSpoolBufferSizeMB - the amount of memory to allocate the write buffer for puts to the DiskStore.

Since:

1.3

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader,
             int maxElementsOnDisk,
             int diskSpoolBufferSizeMB,
             boolean clearOnFlush)

1.6.0 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

maxElementsOnDisk - the maximum number of Elements to allow on the disk. 0 means unlimited.

diskSpoolBufferSizeMB - the amount of memory to allocate the write buffer for puts to the DiskStore.

clearOnFlush - whether the in-memory storage should be cleared when flush() is called on the cache

Since:

1.6.0

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Cache

public Cache(String name,
             int maxElementsInMemory,
             MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
             boolean overflowToDisk,
             String diskStorePath,
             boolean eternal,
             long timeToLiveSeconds,
             long timeToIdleSeconds,
             boolean diskPersistent,
             long diskExpiryThreadIntervalSeconds,
             RegisteredEventListeners registeredEventListeners,
             BootstrapCacheLoader bootstrapCacheLoader,
             int maxElementsOnDisk,
             int diskSpoolBufferSizeMB,
             boolean clearOnFlush,
             boolean isTerracottaClustered,
             String terracottaValueMode,
             boolean terracottaCoherentReads)

1.7.0 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters:

name - the name of the cache. Note that "default" is a reserved name for the defaultCache.

maxElementsInMemory - the maximum number of elements in memory, before they are evicted (0 == no limit)

memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.

overflowToDisk - whether to use the disk store

diskStorePath - this parameter is ignored. CacheManager sets it using setter injection.

eternal - whether the elements in the cache are eternal, i.e. never expire

timeToLiveSeconds - the default amount of time to live for an element from its creation date

timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date

diskPersistent - whether to persist the cache to disk between JVM restarts

diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended

registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created.

bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required.

maxElementsOnDisk - the maximum number of Elements to allow on the disk. 0 means unlimited.

diskSpoolBufferSizeMB - the amount of memory to allocate the write buffer for puts to the DiskStore.

clearOnFlush - whether the in-memory storage should be cleared when flush() is called on the cache

isTerracottaClustered - whether to cluster this cache with Terracotta

terracottaValueMode - either "SERIALIZATION" or "IDENTITY" mode, only used if isTerracottaClustered=true

terracottaCoherentReads - whether this cache should use coherent reads (usually should be true) unless optimizing for read-only

Since:

1.7.0

See Also:

Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader), for full construction support of version 2.0 and higher features.

Method Detail

getTransactionManagerLookup

public TransactionManagerLookup getTransactionManagerLookup()

Get the TransactionManagerLookup implementation used to lookup the TransactionManager. This is generally only set for XA transactional caches

Returns:

The TransactionManagerLookup instance

setTransactionManagerLookup

public void setTransactionManagerLookup(TransactionManagerLookup lookup)

Sets the TransactionManagerLookup that needs to be used for this cache to lookup the TransactionManager This needs to be set before initialise() is called

Specified by:

setTransactionManagerLookup in interface Ehcache

Parameters:

lookup - The TransactionManagerLookup instance

initialise

public void initialise()

Newly created caches do not have a Store.

This method creates the store and makes the cache ready to accept elements

Specified by:

initialise in interface Ehcache

getWriterManager

public CacheWriterManager getWriterManager()

Obtain the writer manager that's used by this cache instance.

Specified by:

getWriterManager in interface Ehcache

Returns:

the writer manager that's set up for this cache

createDiskStore

protected DiskStore createDiskStore()

Creates a disk store when either:

1. overflowToDisk is enabled
2. diskPersistent is enabled

Returns:

the disk store

isDiskStore

protected boolean isDiskStore()

Whether this cache uses a disk store

Returns:

true if the cache either overflows to disk or is disk persistent

isTerracottaClustered

public boolean isTerracottaClustered()

Indicates whether this cache is clustered by Terracotta

Returns:

true when the cache is clustered by Terracotta; or false otherwise

bootstrap

public void bootstrap()

Bootstrap command. This must be called after the Cache is initialised, 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 Ehcache

put

public final void put(Element element)
               throws IllegalArgumentException,
                      IllegalStateException,
                      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

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

put in interface Ehcache

Parameters:

element - A cache Element. If Serializable it can fully participate in replication and the DiskStore. If it is null or the key is null, it is ignored as a NOOP.

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

IllegalArgumentException - if the element is null

put

public final void put(Element element,
                      boolean doNotNotifyCacheReplicators)
               throws IllegalArgumentException,
                      IllegalStateException,
                      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

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

put in interface Ehcache

Parameters:

element - A cache Element. If Serializable it can fully participate in replication and the DiskStore. If it is null or the key is null, it is ignored as a NOOP.

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

IllegalArgumentException - if the element is null

CacheException

putWithWriter

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

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

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

putQuiet

public final void putQuiet(Element element)
                    throws IllegalArgumentException,
                           IllegalStateException,
                           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). Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

putQuiet in interface Ehcache

Parameters:

element - A cache Element. If Serializable it can fully participate in replication and the DiskStore. If it is null or the key is null, it is ignored as a NOOP.

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

IllegalArgumentException - if the element is null

CacheException

get

public final Element get(Serializable key)
                  throws IllegalStateException,
                         CacheException

Gets an element from the cache. Updates Element Statistics

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

Synchronization is handled within the method.

Specified by:

get in interface Ehcache

Parameters:

key - a serializable value. Null keys are not stored so get(null) always returns null

Returns:

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

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

See Also:

isExpired(net.sf.ehcache.Element)

get

public final Element get(Object key)
                  throws IllegalStateException,
                         CacheException

Gets an element from the cache. Updates Element Statistics

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

Synchronization is handled within the method.

Specified by:

get in interface Ehcache

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

Since:

1.2

See Also:

isExpired(net.sf.ehcache.Element)

getWithLoader

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

This method will return, from the cache, the Element associated with the argument "key".

If the Element 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.

If the loader decides to assign a null value to the Element, an Element with a null value is created and stored in the cache.

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

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

load

public void load(Object key)
          throws CacheException

The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified object into the cache using the associated CacheLoader. If the object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load 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.

The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

Specified by:

load in interface Ehcache

Parameters:

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

Throws:

CacheException

getAllWithLoader

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

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

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

loadAll

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

The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load the specified objects into the cache using the associated cache loader(s). If the an object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) should be logged. 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 (to be defined) 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.

keys - collection of the keys whose associated values to be loaded into this cache by using the associated CacheLoader if this cache doesn't contain them.

The Ehcache native API provides similar functionality to loaders using the decorator SelfPopulatingCache

Specified by:

loadAll in interface Ehcache

Throws:

CacheException

getQuiet

public final Element getQuiet(Serializable key)
                       throws IllegalStateException,
                              CacheException

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

Specified by:

getQuiet in interface Ehcache

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:

isExpired(net.sf.ehcache.Element)

getQuiet

public final Element getQuiet(Object key)
                       throws IllegalStateException,
                              CacheException

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

Listeners are not called.

Specified by:

getQuiet in interface Ehcache

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

Since:

1.2

See Also:

isExpired(net.sf.ehcache.Element)

getKeys

public final List getKeys()
                   throws IllegalStateException,
                          CacheException

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

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). On a single CPU 1.8Ghz P4, approximately 8ms is required for each 1000 entries.

Specified by:

getKeys in interface Ehcache

Returns:

a list of Object keys

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

getKeysWithExpiryCheck

public final List getKeysWithExpiryCheck()
                                  throws IllegalStateException,
                                         CacheException

Returns a list of all element keys 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 Ehcache

Returns:

a list of Object keys

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

getKeysNoDuplicateCheck

public final List getKeysNoDuplicateCheck()
                                   throws 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 Ehcache

Returns:

a list of Object keys

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

public final boolean remove(Serializable key)
                     throws 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.

Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

remove in interface Ehcache

Parameters:

key - the element key to operate on

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 final boolean remove(Object key)
                     throws 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.

Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

remove in interface Ehcache

Parameters:

key - the element key to operate on

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

Since:

1.2

remove

public final boolean remove(Serializable key,
                            boolean doNotNotifyCacheReplicators)
                     throws 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.

Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

remove in interface Ehcache

Parameters:

key - the element key to operate on

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 final boolean remove(Object key,
                            boolean doNotNotifyCacheReplicators)
                     throws 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.

Synchronization is handled within the method.

Specified by:

remove in interface Ehcache

Parameters:

key - the element key to operate on

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

removeQuiet

public final boolean removeQuiet(Serializable key)
                          throws IllegalStateException

Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Listeners are not called.

Specified by:

removeQuiet in interface Ehcache

Parameters:

key - the element key to operate on

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 final boolean removeQuiet(Object key)
                          throws IllegalStateException

Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Listeners are not called.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

removeQuiet in interface Ehcache

Parameters:

key - the element key to operate on

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

Since:

1.2

removeWithWriter

public boolean removeWithWriter(Object key)
                         throws IllegalStateException

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

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()
               throws IllegalStateException,
                      CacheException

Removes all cached items. Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

removeAll in interface Ehcache

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

removeAll

public void removeAll(boolean doNotNotifyCacheReplicators)
               throws IllegalStateException,
                      CacheException

Removes all cached items. Synchronization is handled within the method.

Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.

Specified by:

removeAll in interface 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:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

dispose

public void dispose()
             throws IllegalStateException

Starts an orderly shutdown of the Cache. Steps are:

1. Completes any outstanding CacheLoader loads.
2. Completes any outstanding CacheWriter operations.
3. Disposes any cache extensions.
4. Disposes any cache event listeners. The listeners normally complete, so for example distributed caching operations will complete.
5. Flushes all cache items from memory to the disk store, if any
6. changes status to shutdown, so that any cache operations after this point throw IllegalStateException

This method should be invoked only by CacheManager, as a cache's lifecycle is bound into that of it's cache manager.

Specified by:

dispose in interface Ehcache

Throws:

IllegalStateException - if the cache is already Status.STATUS_SHUTDOWN

getCacheConfiguration

public 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 Ehcache

flush

public final void flush()
                 throws IllegalStateException,
                        CacheException

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

Specified by:

flush in interface Ehcache

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

getSize

public final int getSize()
                  throws IllegalStateException,
                         CacheException

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

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.

Note:getSize() is a very expensive operation in off-heap, disk and Terracotta implementations.

Specified by:

getSize in interface Ehcache

Returns:

The size value

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

getSizeBasedOnAccuracy

public int getSizeBasedOnAccuracy(int statisticsAccuracy)
                           throws IllegalStateException,
                                  CacheException

Accurately measuring statistics can be expensive. Returns the size of the cache based on the accuracy setting

Specified by:

getSizeBasedOnAccuracy in interface Ehcache

Parameters:

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

Returns:

the size of the cache based on the current accuracy setting

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

CacheException

calculateInMemorySize

public final long calculateInMemorySize()
                                 throws IllegalStateException,
                                        CacheException

Gets the size of the memory store for this cache. This method relies on calculating Serialized sizes. If the Element values are not Serializable they will show as zero.

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 Ehcache

Returns:

the approximate size of the memory store in bytes

Throws:

IllegalStateException

CacheException

calculateOffHeapSize

public final long calculateOffHeapSize()
                                throws IllegalStateException,
                                       CacheException

Gets the size of the off-heap store for this cache.

Specified by:

calculateOffHeapSize in interface Ehcache

Returns:

the size of the off-heap store in bytes

Throws:

IllegalStateException

CacheException

getMemoryStoreSize

public final long getMemoryStoreSize()
                              throws IllegalStateException

Returns the number of elements in the memory store.

Specified by:

getMemoryStoreSize in interface Ehcache

Returns:

the number of elements in the memory store

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

getOffHeapStoreSize

public long getOffHeapStoreSize()
                         throws IllegalStateException

Returns the number of elements in the off-heap store.

Specified by:

getOffHeapStoreSize in interface Ehcache

Returns:

the number of elements in the off-heap store

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

getDiskStoreSize

public final int getDiskStoreSize()
                           throws IllegalStateException

Returns the number of elements in the disk store.

Specified by:

getDiskStoreSize in interface Ehcache

Returns:

the number of elements in the disk store.

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

getStatus

public final Status getStatus()

Gets the status attribute of the Cache.

Specified by:

getStatus in interface Ehcache

Returns:

The status value from the Status enum class

getName

public final String getName()

Gets the cache name.

Specified by:

getName in interface Ehcache

setName

public final void setName(String name)
                   throws IllegalArgumentException

Sets the cache name which will name.

Specified by:

setName in interface Ehcache

Parameters:

name - the name of the cache. Should not be null. Should also not contain any '/' characters, as these interfere with distribution

Throws:

IllegalArgumentException - if an illegal name is used.

toString

public String toString()

Returns a String representation of Cache.

Specified by:

toString in interface Ehcache

Overrides:

toString in class Object

isExpired

public final boolean isExpired(Element element)
                        throws IllegalStateException,
                               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 Ehcache

Parameters:

element - the element to check

Returns:

true if it has expired

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

NullPointerException - if the element is null todo this does not need to be synchronized

clone

public final Cache clone()
                  throws 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 stores have been created.

A new, empty, RegisteredEventListeners is created on clone.

Specified by:

clone in interface Ehcache

Overrides:

clone in class Object

Returns:

an object of type Cache

Throws:

CloneNotSupportedException

getStoreMBean

public final Object getStoreMBean()

Get the optional store management bean for this cache.

getCacheEventNotificationService

public final RegisteredEventListeners getCacheEventNotificationService()

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

Specified by:

getCacheEventNotificationService in interface Ehcache

Returns:

the RegisteredEventListeners instance for this cache.

isElementInMemory

public final boolean isElementInMemory(Serializable key)

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

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Specified by:

isElementInMemory in interface Ehcache

Returns:

true if an element matching the key is found in memory

isElementInMemory

public final boolean isElementInMemory(Object key)

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

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Specified by:

isElementInMemory in interface Ehcache

Returns:

true if an element matching the key is found in memory

Since:

1.2

isElementOffHeap

public final boolean isElementOffHeap(Object key)

Whether an Element is stored in the cache in off-heap memory, indicating an intermediate cost of retrieval.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Returns:

true if an element matching the key is found in off-heap

Since:

2.3

isElementOnDisk

public final boolean isElementOnDisk(Serializable key)

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

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Specified by:

isElementOnDisk in interface Ehcache

Returns:

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

isElementOnDisk

public final boolean isElementOnDisk(Object key)

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

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Specified by:

isElementOnDisk in interface Ehcache

Returns:

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

Since:

1.2

getGuid

public final 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 Ehcache

Returns:

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

Since:

1.2

getCacheManager

public final 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 Ehcache

Returns:

the manager or null if there is none

clearStatistics

public void clearStatistics()
                     throws IllegalStateException

Resets statistics counters back to 0.

Specified by:

clearStatistics in interface Ehcache

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

getStatisticsAccuracy

public int getStatisticsAccuracy()

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

Specified by:

getStatisticsAccuracy in interface 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 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 Ehcache

isKeyInCache

public boolean isKeyInCache(Object key)

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

This method is not synchronized. It is possible that an element may exist in the cache and be removed before the check gets to it, or vice versa. Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Specified by:

isKeyInCache in interface Ehcache

Parameters:

key - the key to check.

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(Object value)

An extremely expensive check to see if the value exists in the cache. This implementation is O(n). Ehcache is not designed for efficient access in this manner.

This method is not synchronized. It is possible that an element may exist in the cache and be removed before the check gets to it, or vice versa. Because it is slow to execute the probability of that this will have happened.

Specified by:

isValueInCache in interface 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 Statistics getStatistics()
                         throws 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.

Note, the getSize() method will have the same value as the size reported by Statistics for the statistics accuracy of Statistics.STATISTICS_ACCURACY_BEST_EFFORT.

Specified by:

getStatistics in interface Ehcache

Returns:

the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.

Throws:

IllegalStateException - if the cache is not Status.STATUS_ALIVE

getAverageSearchTime

public long getAverageSearchTime()

Get the average search execution time (in millis) for searches that have completed in the last sample period

Specified by:

getAverageSearchTime in interface Ehcache

getSearchesPerSecond

public long getSearchesPerSecond()

Get the number of search executions that have completed in the last second

Specified by:

getSearchesPerSecond in interface Ehcache

setCacheManager

public void setCacheManager(CacheManager cacheManager)

For use by CacheManager.

Specified by:

setCacheManager in interface Ehcache

Parameters:

cacheManager - the CacheManager for this cache to use.

getBootstrapCacheLoader

public BootstrapCacheLoader getBootstrapCacheLoader()

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

Specified by:

getBootstrapCacheLoader in interface Ehcache

Returns:

the BootstrapCacheLoader to use

setBootstrapCacheLoader

public void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
                             throws CacheException

Sets the bootstrap cache loader.

Specified by:

setBootstrapCacheLoader in interface Ehcache

Parameters:

bootstrapCacheLoader - the loader to be used

Throws:

CacheException - if this method is called after the cache is initialized

setDiskStorePath

public void setDiskStorePath(String diskStorePath)
                      throws CacheException

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

Specified by:

setDiskStorePath in interface Ehcache

Parameters:

diskStorePath - the new path to be used.

Throws:

CacheException - if this method is called after the cache is initialized

equals

public boolean equals(Object object)

An equals method which follows the contract of Object.equals(Object)

An Cache is equal to another one if it implements Ehcache and has the same GUID.

Overrides:

equals in class Object

Parameters:

object - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the Object.equals(Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java(TM) programming language.)

This implementation use the GUID of the cache.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

Object.equals(Object), Hashtable

registerCacheExtension

public void registerCacheExtension(CacheExtension cacheExtension)

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

If the CacheExtension is not initialised, initialise it.

Specified by:

registerCacheExtension in interface Ehcache

getRegisteredCacheExtensions

public List<CacheExtension> getRegisteredCacheExtensions()

Specified by:

getRegisteredCacheExtensions in interface Ehcache

Returns:

the cache extensions as a live list

unregisterCacheExtension

public void unregisterCacheExtension(CacheExtension cacheExtension)

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

Specified by:

unregisterCacheExtension in interface Ehcache

getAverageGetTime

public float getAverageGetTime()

The average get time in ms.

Specified by:

getAverageGetTime in interface Ehcache

setCacheExceptionHandler

public void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler)

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

The ExceptionHandler is only used if this Cache's methods are accessed using ExceptionHandlingDynamicCacheProxy.

Specified by:

setCacheExceptionHandler in interface Ehcache

See Also:

ExceptionHandlingDynamicCacheProxy

getCacheExceptionHandler

public CacheExceptionHandler getCacheExceptionHandler()

Gets the ExceptionHandler on this Cache, or null if there isn't one.

The ExceptionHandler is only used if this Cache's methods are accessed using ExceptionHandlingDynamicCacheProxy.

Specified by:

getCacheExceptionHandler in interface Ehcache

See Also:

ExceptionHandlingDynamicCacheProxy

registerCacheLoader

public void registerCacheLoader(CacheLoader cacheLoader)

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

If the CacheLoader is not initialised, initialise it.

Specified by:

registerCacheLoader in interface Ehcache

Parameters:

cacheLoader - A Cache Loader to register

unregisterCacheLoader

public void unregisterCacheLoader(CacheLoader cacheLoader)

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

Specified by:

unregisterCacheLoader in interface Ehcache

Parameters:

cacheLoader - A Cache Loader to unregister

getRegisteredCacheLoaders

public List<CacheLoader> getRegisteredCacheLoaders()

Specified by:

getRegisteredCacheLoaders in interface Ehcache

Returns:

the cache loaders as a live list

registerCacheWriter

public void registerCacheWriter(CacheWriter cacheWriter)

Register the CacheWriter for this cache. It will then be tied into the cache lifecycle.

If the CacheWriter is not initialised, initialise it.

Specified by:

registerCacheWriter in interface Ehcache

Parameters:

cacheWriter - A CacheWriter to register

unregisterCacheWriter

public void unregisterCacheWriter()

Unregister the CacheWriter from the cache. It will then be detached from the cache lifecycle.

If not CacheWriter was registered beforehand this operation has no effect.

Specified by:

unregisterCacheWriter in interface Ehcache

getRegisteredCacheWriter

public CacheWriter getRegisteredCacheWriter()

Retrieves the CacheWriter that was registered for this cache.

Specified by:

getRegisteredCacheWriter in interface Ehcache

Returns:

the registered CacheWriter; or null if none was registered before

isDisabled

public boolean isDisabled()

Whether this cache is disabled. "Disabled" means:

1. bootstrap is disabled
2. puts are discarded
3. putQuiets are discarded
4. gets return null

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 Ehcache

Returns:

true if the cache is disabled.

See Also:

?

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 Ehcache

Parameters:

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

See Also:

isDisabled()

getMemoryStoreEvictionPolicy

public Policy getMemoryStoreEvictionPolicy()

Returns:

the current in-memory eviction policy. This may not be the configured policy, if it has been dynamically set.

setMemoryStoreEvictionPolicy

public void setMemoryStoreEvictionPolicy(Policy policy)

Sets the eviction policy strategy. The Cache will use a policy at startup. There are three policies which can be configured: LRU, LFU and FIFO. However many other policies are possible. That the policy has access to the whole element enables policies based on the key, value, metadata, statistics, or a combination of any of the above. It is safe to change the policy of a store at any time. The new policy takes effect immediately.

Parameters:

policy - the new policy

getLiveCacheStatistics

public LiveCacheStatistics getLiveCacheStatistics()
                                           throws IllegalStateException

This is different from Ehcache.getStatistics() in the way that values returned from LiveCacheStatistics will reflect the current state of the cache (and not a snapshot of the cache when the api's were called like Ehcache.getStatistics())

Specified by:

getLiveCacheStatistics in interface Ehcache

Returns:

The LiveCacheStatistics associated with this cache

Throws:

IllegalStateException

registerCacheUsageListener

public void registerCacheUsageListener(CacheUsageListener cacheUsageListener)
                                throws IllegalStateException

Registers a CacheUsageListener which will be notified of the cache usage. Implementations of CacheUsageListener should override the Object.equals(Object) and Object.hashCode() methods as it is used for equality check

Specified by:

registerCacheUsageListener in interface Ehcache

Throws:

IllegalStateException

removeCacheUsageListener

public void removeCacheUsageListener(CacheUsageListener cacheUsageListener)
                              throws IllegalStateException

Remove an already registered CacheUsageListener, if any. Depends on the Object.equals(Object) method.

Specified by:

removeCacheUsageListener in interface Ehcache

Throws:

IllegalStateException

isStatisticsEnabled

public boolean isStatisticsEnabled()

Returns true if statistics collection is enabled

Specified by:

isStatisticsEnabled in interface Ehcache

Returns:

true if statistics is enabled, false otherwise

setStatisticsEnabled

public void setStatisticsEnabled(boolean enableStatistics)

Enable/disable statistics collection. Enabling statistics does not have any effect on sampled statistics. To enable sampled statistics, use Ehcache.setSampledStatisticsEnabled(boolean) with parameter true. Disabling statistics also disables the sampled statistics collection if it is enabled

Specified by:

setStatisticsEnabled in interface Ehcache

getSampledCacheStatistics

public SampledCacheStatistics getSampledCacheStatistics()

Returns sampled statistics for this cache.

Specified by:

getSampledCacheStatistics in interface Ehcache

Returns:

The sampled cache statistics

setSampledStatisticsEnabled

public void setSampledStatisticsEnabled(boolean enableStatistics)

Enable/disable sampled statistics collection. Enabling sampled statistics also enables the normal statistics collection if its not already enabled. Disabling sampled statistics does not have any effect on normal statistics.

Specified by:

setSampledStatisticsEnabled in interface Ehcache

isSampledStatisticsEnabled

public boolean isSampledStatisticsEnabled()

Returns if sampled statistics collection is enabled or disabled

Specified by:

isSampledStatisticsEnabled in interface Ehcache

Returns:

true if sampled statistics is enabled, false otherwise

See Also:

Ehcache.isSampledStatisticsEnabled()

getInternalContext

public Object getInternalContext()

This should not be used return some internal context (generally will be null)

Specified by:

getInternalContext in interface Ehcache

disableDynamicFeatures

public void disableDynamicFeatures()

Disables dynamic configuration and disable/enable for this cache.

This is a one time operation. Once an Ehcache instance has had its dynamic operations disabled they cannot be re-enabled.

Specified by:

disableDynamicFeatures in interface Ehcache

isClusterCoherent

@Deprecated
public boolean isClusterCoherent()

Deprecated. use isClusterBulkLoadEnabled() instead

Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

isClusterCoherent in interface Ehcache

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

isNodeCoherent

@Deprecated
public boolean isNodeCoherent()

Deprecated. use isNodeBulkLoadEnabled() instead

Returns true if the cache is in coherent mode for the current node. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

isNodeCoherent in interface Ehcache

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

setNodeCoherent

@Deprecated
public void setNodeCoherent(boolean coherent)

Deprecated. use setNodeBulkLoadEnabled(boolean) instead

Sets the cache in coherent or incoherent mode depending on the parameter on this node. Calling setNodeCoherent(true) when the cache is already in coherent mode or calling setNodeCoherent(false) when already in incoherent mode will be a no-op.

It applies to coherent clustering mechanisms only e.g. Terracotta

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

Specified by:

setNodeCoherent in interface Ehcache

Parameters:

coherent - true transitions to coherent mode, false to incoherent mode

waitUntilClusterCoherent

@Deprecated
public void waitUntilClusterCoherent()

Deprecated. use waitUntilClusterBulkLoadComplete() instead

This method waits until the cache is in coherent mode in all the connected nodes. If the cache is already in coherent mode it returns immediately

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

waitUntilClusterCoherent in interface Ehcache

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Description copied from interface: Ehcache

Add a PropertyChangeListener.

Specified by:

addPropertyChangeListener in interface Ehcache

Parameters:

listener -

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Description copied from interface: Ehcache

Remove a PropertyChangeListener.

Specified by:

removePropertyChangeListener in interface Ehcache

Parameters:

listener -

firePropertyChange

public void firePropertyChange(String propertyName,
                               Object oldValue,
                               Object newValue)

Parameters:

propertyName -

oldValue -

newValue -

putIfAbsent

public Element putIfAbsent(Element element)
                    throws NullPointerException

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

Specified by:

putIfAbsent in interface Ehcache

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

removeElement

public boolean removeElement(Element element)
                      throws NullPointerException

Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.

Specified by:

removeElement in interface Ehcache

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

replace

public boolean replace(Element old,
                       Element element)
                throws NullPointerException,
                       IllegalArgumentException

Replace the cached element only if the current Element is equal to the supplied old Element.

Specified by:

replace in interface Ehcache

Parameters:

old - Element to be test against

element - Element to be cached

Returns:

true is 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

Replace the cached element only if an Element is currently cached for this key

Specified by:

replace in interface Ehcache

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

clusterCoherent

public void clusterCoherent(boolean clusterCoherent)

Inform of cluster coherence.

Specified by:

clusterCoherent in interface StoreListener

See Also:

StoreListener.clusterCoherent(boolean)

getSearchAttribute

public <T> Attribute<T> getSearchAttribute(String attributeName)
                                throws CacheException

Retrieve the given named search attribute

Specified by:

getSearchAttribute in interface Ehcache

Type Parameters:

T - type of the attribute

Parameters:

attributeName - the name of the attribute to retrieve

Returns:

the search attribute

Throws:

CacheException - if no such attribute is defined for the given name

createQuery

public Query createQuery()

Create a new query builder for this cache

Specified by:

createQuery in interface Ehcache

Returns:

a new query builder

isSearchable

public boolean isSearchable()

Is this cache searchable?

Specified by:

isSearchable in interface Ehcache

Returns:

true if this cache is searchable

getLockForKey

protected Sync getLockForKey(Object key)

Gets the lock for a given key

Parameters:

key -

Returns:

the lock object for the passed in key

acquireReadLockOnKey

public void acquireReadLockOnKey(Object key)

Acquires the proper read lock for a given cache key

Specified by:

acquireReadLockOnKey in interface Ehcache

Parameters:

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

acquireWriteLockOnKey

public void acquireWriteLockOnKey(Object key)

Acquires the proper write lock for a given cache key

Specified by:

acquireWriteLockOnKey in interface Ehcache

Parameters:

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

tryReadLockOnKey

public boolean tryReadLockOnKey(Object key,
                                long timeout)
                         throws 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

Specified by:

tryReadLockOnKey in interface Ehcache

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:

InterruptedException

tryWriteLockOnKey

public boolean tryWriteLockOnKey(Object key,
                                 long timeout)
                          throws 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

Specified by:

tryWriteLockOnKey in interface Ehcache

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:

InterruptedException

releaseReadLockOnKey

public void releaseReadLockOnKey(Object key)

Release a held read lock for the passed in key

Specified by:

releaseReadLockOnKey in interface Ehcache

Parameters:

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

releaseWriteLockOnKey

public void releaseWriteLockOnKey(Object key)

Release a held write lock for the passed in key

Specified by:

releaseWriteLockOnKey in interface Ehcache

Parameters:

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

isReadLockedByCurrentThread

public boolean isReadLockedByCurrentThread(Object key)

Returns true if a read lock for the key is held by the current thread

Specified by:

isReadLockedByCurrentThread in interface Ehcache

Returns:

true if a read lock for the key is held by the current thread

isWriteLockedByCurrentThread

public boolean isWriteLockedByCurrentThread(Object key)

Returns true if a write lock for the key is held by the current thread

Specified by:

isWriteLockedByCurrentThread in interface Ehcache

Returns:

true if a write lock for the key is held by the current thread

isClusterBulkLoadEnabled

public boolean isClusterBulkLoadEnabled()
                                 throws UnsupportedOperationException,
                                        TerracottaNotRunningException

Returns true if at least one node in the cluster is in bulk-load mode. Returns false otherwise.

NOTE: if Ehcache.isNodeBulkLoadEnabled() returns true, this method will always return true. Applies to caches clustered with Terracotta only.

Specified by:

isClusterBulkLoadEnabled in interface Ehcache

Returns:

true if the cache is in bulk-load mode cluster-wide, false otherwise

Throws:

UnsupportedOperationException - if the cache is not clustered with Terracotta

TerracottaNotRunningException

isNodeBulkLoadEnabled

public boolean isNodeBulkLoadEnabled()
                              throws UnsupportedOperationException,
                                     TerracottaNotRunningException

Returns true if the current node is in bulk-load mode. Returns false otherwise.

NOTE: if this method returns true, Ehcache.isClusterBulkLoadEnabled() method will always return true. Applies to caches clustered with Terracotta only.

Specified by:

isNodeBulkLoadEnabled in interface Ehcache

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

Throws:

UnsupportedOperationException - if the cache is not clustered with Terracotta

TerracottaNotRunningException

setNodeBulkLoadEnabled

public void setNodeBulkLoadEnabled(boolean enabledBulkLoad)
                            throws UnsupportedOperationException,
                                   TerracottaNotRunningException

Enable/disable bulk-load mode in this node for this cache. Calling setBulkLoadEnabled(true) when the cache is already in bulk-load mode or calling setBulkLoadEnabled(false) when already NOT in bulk-load mode will be a no-op.

Applies to caches clustered with Terracotta only.

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:

setNodeBulkLoadEnabled in interface Ehcache

Parameters:

enabledBulkLoad - true enables bulk-load, false disables it if not already disabled

Throws:

UnsupportedOperationException - if the cache is not clustered with Terracotta

TerracottaNotRunningException

waitUntilClusterBulkLoadComplete

public void waitUntilClusterBulkLoadComplete()
                                      throws UnsupportedOperationException,
                                             TerracottaNotRunningException

This method waits until all the connected nodes have disabled bulk-load. Or in other words, calling this method will block until all connected nodes in the cluster disables bulk-load. If none of the nodes did not enable bulk-load this method will return immediately

Applies to caches clustered with Terracotta only.

Specified by:

waitUntilClusterBulkLoadComplete in interface Ehcache

Throws:

UnsupportedOperationException - if the cache is not clustered with Terracotta

TerracottaNotRunningException