public class Cache extends Object implements InternalEhcache, StoreListener
Element
s and are managed
by the CacheManager
. The Cache performs logical actions. It delegates physical
implementations to its Store
s.
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.
Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
Cache(CacheConfiguration cacheConfiguration)
2.0 and higher Constructor
|
Cache(CacheConfiguration cacheConfiguration,
RegisteredEventListeners registeredEventListeners,
BootstrapCacheLoader bootstrapCacheLoader)
2.0 and higher Constructor
|
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
|
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
|
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
|
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
|
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
|
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,
boolean terracottaCoherentReads)
1.7.0 Constructor
|
Modifier and Type | Method and Description |
---|---|
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()
Deprecated.
|
long |
calculateOffHeapSize()
Deprecated.
|
long |
calculateOnDiskSize()
Deprecated.
|
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) |
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<Object,Element> |
getAll(Collection<?> keys)
Gets all the elements from the cache for the keys provided.
|
Map |
getAllWithLoader(Collection keys,
Object loaderArgument)
The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
|
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()
Deprecated.
|
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
|
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.
|
protected Sync |
getLockForKey(Object key)
Gets the lock for a given key
|
Policy |
getMemoryStoreEvictionPolicy() |
long |
getMemoryStoreSize()
Deprecated.
|
String |
getName()
Gets the cache name.
|
long |
getOffHeapStoreSize()
Deprecated.
|
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. |
<T> Attribute<T> |
getSearchAttribute(String attributeName)
Retrieve the given named search attribute
|
Set<Attribute> |
getSearchAttributes() |
int |
getSize()
Gets the size of the cache.
|
StatisticsGateway |
getStatistics()
Gets an immutable Statistics object representing the Cache statistics at the time.
|
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.
|
boolean |
hasAbortedSizeOf()
Check if the cache may contain elements which the SizeOf engine could not fully size.
|
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 |
isSearchable()
Is this cache searchable?
|
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.
|
void |
putAll(Collection<Element> elements)
Puts a collection of elements in to the cache.
|
Element |
putIfAbsent(Element element)
Put an element in the cache if no element is currently mapped to the elements key.
|
Element |
putIfAbsent(Element element,
boolean doNotNotifyCacheReplicators)
Put an element in the cache if no element is currently mapped to the elements key.
|
void |
putQuiet(Element element)
Put an element in the cache, without updating statistics, or updating listeners.
|
void |
putWithWriter(Element element)
Put an element in the cache writing through a CacheWriter.
|
void |
recalculateSize(Object key)
Recalculate the size of the element mapped to the key
|
void |
registerCacheExtension(CacheExtension cacheExtension)
Register a
CacheExtension with the cache. |
void |
registerCacheLoader(CacheLoader cacheLoader)
Register a
CacheLoader with the cache. |
void |
registerCacheWriter(CacheWriter cacheWriter)
Register the
CacheWriter for this cache. |
void |
registerDynamicAttributesExtractor(DynamicAttributesExtractor extractor)
Allows user to register a dynamic attribute extractor with a searchable cache that is dynamically indexable,
as indicated by its configuration.
|
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 |
removeAll(Collection<?> keys)
Removes given set of
Element from the Cache. |
void |
removeAll(Collection<?> keys,
boolean doNotNotifyCacheReplicators)
Removes all cached items.
|
Element |
removeAndReturnElement(Object key)
Removes an
Element from the Cache and returns it. |
boolean |
removeElement(Element element)
Remove the Element mapped to the key for the supplied element if the value of the supplied Element
compares equal to the value of the cached Element.
|
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 |
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 |
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()
|
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 |
public static final String DEFAULT_CACHE_NAME
public static final String NET_SF_EHCACHE_DISABLED
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.
public static final String NET_SF_EHCACHE_USE_CLASSIC_LRU
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.
public static final long DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
public Cache(CacheConfiguration cacheConfiguration)
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.
cacheConfiguration
- the configuration that should be used to create the cache withpublic Cache(CacheConfiguration cacheConfiguration, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader)
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.
cacheConfiguration
- the configuration that should be used to create the cache withregisteredEventListeners
- 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.public Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds)
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.
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 storeeternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified dateCache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
public Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds)
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.
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 storeeternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedCache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
public Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- a notification service. Optionally null, in which case a new
one with no registered listeners will be created.Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
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)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- 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(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
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)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- 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.Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
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)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- 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.Cache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
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)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- 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 cacheCache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
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, boolean terracottaCoherentReads)
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.
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 storediskStorePath
- this parameter is ignored. CacheManager sets it using setter injection.eternal
- whether the elements in the cache are eternal, i.e. never expiretimeToLiveSeconds
- the default amount of time to live for an element from its creation datetimeToIdleSeconds
- the default amount of time to live for an element from its last accessed or modified datediskPersistent
- whether to persist the cache to disk between JVM restartsdiskExpiryThreadIntervalSeconds
- how often to run the disk store expiry thread. A large number of 120 seconds plus is recommendedregisteredEventListeners
- 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 cacheisTerracottaClustered
- whether to cluster this cache with TerracottaterracottaCoherentReads
- whether this cache should use coherent reads (usually should be true) unless optimizing for read-onlyCache(CacheConfiguration, RegisteredEventListeners, BootstrapCacheLoader),
for full construction support of version 2.0 and higher features.
public TransactionManagerLookup getTransactionManagerLookup()
TransactionManagerLookup
instancepublic void setTransactionManagerLookup(TransactionManagerLookup lookup)
initialise()
is calledsetTransactionManagerLookup
in interface Ehcache
lookup
- The TransactionManagerLookup
instancepublic void initialise()
Store
.
This method creates the store and makes the cache ready to accept elements
initialise
in interface Ehcache
public CacheWriterManager getWriterManager()
getWriterManager
in interface Ehcache
protected DiskStore createDiskStore()
protected boolean isDiskStore()
public boolean isTerracottaClustered()
true
when the cache is clustered by Terracotta; or false
otherwisepublic void bootstrap()
public final void put(Element element) throws IllegalArgumentException, IllegalStateException, CacheException
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:
put
in interface Ehcache
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.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
- in case of errorIllegalArgumentException
- if the element is nullpublic void putAll(Collection<Element> elements) throws IllegalArgumentException, IllegalStateException, CacheException
This method will throw a NullPointerException
if a null element or null key is encountered
in the collection, and a partial completion may result (as only some of the elements may have been put).
For each element that is put the registered CacheEventListener
s are notified of a newly put item
(notifyElementPut(...)
)
regardless of whether the individual put is a new put or an update.
putAll
in interface Ehcache
elements
- the collection of elements to be put in the cache.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
- a runtime cache exceptionIllegalArgumentException
public final void put(Element element, boolean doNotNotifyCacheReplicators) throws IllegalArgumentException, IllegalStateException, CacheException
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:
put
in interface Ehcache
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 peersIllegalStateException
- if the cache is not Status.STATUS_ALIVE
IllegalArgumentException
- if the element is nullCacheException
public void putWithWriter(Element element) throws IllegalArgumentException, IllegalStateException, CacheException
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:
putWithWriter
in interface Ehcache
element
- An object. If Serializable it can fully participate in replication and the DiskStore.IllegalArgumentException
- if the element is nullIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
- if no CacheWriter was registeredpublic final void putQuiet(Element element) throws IllegalArgumentException, IllegalStateException, CacheException
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.
putQuiet
in interface Ehcache
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.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
IllegalArgumentException
- if the element is nullCacheException
public final Element get(Serializable key) throws IllegalStateException, CacheException
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.
get
in interface Ehcache
key
- a serializable value. Null keys are not stored so get(null) always returns nullIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final Element get(Object key) throws IllegalStateException, CacheException
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.
get
in interface Ehcache
key
- an Object valueIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public Map<Object,Element> getAll(Collection<?> keys) throws IllegalStateException, CacheException
Note that the Element's lastAccessTime is always the time of this get.
Use Ehcache.getQuiet(Object)
to peek into the Element to see its last access time with get
getAll
in interface Ehcache
keys
- a collection of keys for which value is to be fetchedIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
Ehcache.isExpired(net.sf.ehcache.Element)
public Element getWithLoader(Object key, CacheLoader loader, Object loaderArgument) throws CacheException
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.
Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.
getWithLoader
in interface Ehcache
key
- key whose associated value is to be returned.loader
- the override loader to use. If null, the cache's default loader will be usedloaderArgument
- an argument to pass to the CacheLoader.CacheException
- if the loading failspublic void load(Object key) throws CacheException
The Ehcache native API provides similar functionality to loaders using the
decorator SelfPopulatingCache
load
in interface Ehcache
key
- key whose associated value to be loaded using the associated CacheLoader if this cache doesn't contain it.CacheException
- in case of errorpublic Map getAllWithLoader(Collection keys, Object loaderArgument) throws CacheException
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
getAllWithLoader
in interface Ehcache
keys
- a collection of keys to be returned/loadedloaderArgument
- an argument to pass to the CacheLoader.CacheException
- in case of errorpublic void loadAll(Collection keys, Object argument) throws CacheException
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
loadAll
in interface Ehcache
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.argument
- can be anything that makes sense to the loader
The Ehcache native API provides similar functionality to loaders using the
decorator SelfPopulatingCache
CacheException
public final Element getQuiet(Serializable key) throws IllegalStateException, CacheException
getQuiet
in interface Ehcache
key
- a serializable valueIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final Element getQuiet(Object key) throws IllegalStateException, CacheException
Listeners are not called.
getQuiet
in interface Ehcache
key
- a serializable valueIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final List getKeys() throws IllegalStateException, CacheException
The returned keys are unique and can almost be considered a set. See CacheKeySet
for
more details.
The List returned is not live. It is a copy.
The time taken is O(n). For large caches - or caches with high-latency storage this method can take a very long time to complete, may cause timeouts if using features such NonStopCache or transactions, and is not guaranteed to give a consistent view of the cache entry set. Usage is highly discouraged.
getKeys
in interface Ehcache
Object
keysIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
CacheKeySet
public final List getKeysWithExpiryCheck() throws IllegalStateException, CacheException
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.
getKeysWithExpiryCheck
in interface Ehcache
Object
keysIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final List getKeysNoDuplicateCheck() throws IllegalStateException
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
getKeysNoDuplicateCheck
in interface Ehcache
Object
keysIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(Serializable key) throws IllegalStateException
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.
remove
in interface Ehcache
key
- the element key to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(Object key) throws IllegalStateException
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.
remove
in interface Ehcache
key
- the element key to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final Element removeAndReturnElement(Object key) throws IllegalStateException
Element
from the Cache and returns it. 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.
removeAndReturnElement
in interface InternalEhcache
key
- the element key to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public void removeAll(Collection<?> keys) throws IllegalStateException
Element
from the Cache. This also removes them from any
stores it may be in. Throws a NullPointerException if any key in the collection is null
Also notifies the CacheEventListener after the elements were removed. Notification is sent for every key irrespective of whether the key was present in the cache or not This operation is partially completed if any element or any key is null
removeAll
in interface Ehcache
keys
- a collection of keys to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final void removeAll(Collection<?> keys, boolean doNotNotifyCacheReplicators) throws IllegalStateException
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.
removeAll
in interface Ehcache
keys
- a collection of keys to operate ondoNotNotifyCacheReplicators
- whether the put is coming from a doNotNotifyCacheReplicators cache peer,
in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peersIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(Serializable key, boolean doNotNotifyCacheReplicators) throws IllegalStateException
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.
remove
in interface Ehcache
key
- the element key to operate ondoNotNotifyCacheReplicators
- whether the remove is coming from a doNotNotifyCacheReplicators cache peer, in which case this remove should not initiate a
further notification to doNotNotifyCacheReplicators cache peersIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(Object key, boolean doNotNotifyCacheReplicators) throws IllegalStateException
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.
remove
in interface Ehcache
key
- the element key to operate ondoNotNotifyCacheReplicators
- whether the remove is coming from a doNotNotifyCacheReplicators cache peer, in which case this remove should not initiate a
further notification to doNotNotifyCacheReplicators cache peersIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean removeQuiet(Serializable key) throws IllegalStateException
Element
from the Cache, without notifying listeners. This also removes it from any
stores it may be in.
Listeners are not called.
removeQuiet
in interface Ehcache
key
- the element key to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean removeQuiet(Object key) throws IllegalStateException
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.
removeQuiet
in interface Ehcache
key
- the element key to operate onIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public boolean removeWithWriter(Object key) throws IllegalStateException
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.
removeWithWriter
in interface Ehcache
key
- of the element to removeIllegalStateException
- if the cache is not Status.STATUS_ALIVE
public void removeAll() throws IllegalStateException, CacheException
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.
removeAll
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public void removeAll(boolean doNotNotifyCacheReplicators) throws IllegalStateException, CacheException
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails. This exception should be caught in those circumstances.
removeAll
in interface Ehcache
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 peersIllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public void dispose() throws IllegalStateException
dispose
in interface Ehcache
IllegalStateException
- if the cache is already Status.STATUS_SHUTDOWN
public CacheConfiguration getCacheConfiguration()
Things like listeners that are added dynamically are excluded.
getCacheConfiguration
in interface Ehcache
public final void flush() throws IllegalStateException, CacheException
flush
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final int getSize() throws IllegalStateException, CacheException
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.
getSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
@Deprecated public final long calculateInMemorySize() throws IllegalStateException, CacheException
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
calculateInMemorySize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public boolean hasAbortedSizeOf()
hasAbortedSizeOf
in interface Ehcache
@Deprecated public final long calculateOffHeapSize() throws IllegalStateException, CacheException
calculateOffHeapSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
@Deprecated public final long calculateOnDiskSize() throws IllegalStateException, CacheException
calculateOnDiskSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
@Deprecated public final long getMemoryStoreSize() throws IllegalStateException
getMemoryStoreSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
@Deprecated public long getOffHeapStoreSize() throws IllegalStateException
getOffHeapStoreSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
@Deprecated public final int getDiskStoreSize() throws IllegalStateException
getDiskStoreSize
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final Status getStatus()
public final String getName()
public final void setName(String name) throws IllegalArgumentException
setName
in interface Ehcache
name
- the name of the cache. Should not be null. Should also not contain any '/' characters, as these interfere
with distributionIllegalArgumentException
- if an illegal name is used.public String toString()
public final boolean isExpired(Element element) throws IllegalStateException, NullPointerException
The element is expired if:
isExpired
in interface Ehcache
element
- the element to checkIllegalStateException
- if the cache is not Status.STATUS_ALIVE
NullPointerException
- if the element is null
todo this does not need to be synchronizedpublic final Cache clone() throws CloneNotSupportedException
A new, empty, RegisteredEventListeners is created on clone.
public final Object getStoreMBean()
public final RegisteredEventListeners getCacheEventNotificationService()
getCacheEventNotificationService
in interface Ehcache
public final boolean isElementInMemory(Serializable key)
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.
isElementInMemory
in interface Ehcache
key
- the key of the element to removepublic final boolean isElementInMemory(Object key)
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.
isElementInMemory
in interface Ehcache
key
- the key of the element to removepublic final boolean isElementOffHeap(Object key)
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.
key
- key to look forpublic final boolean isElementOnDisk(Serializable key)
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.
isElementOnDisk
in interface Ehcache
key
- key to look forpublic final boolean isElementOnDisk(Object key)
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.
isElementOnDisk
in interface Ehcache
key
- key to look forpublic final String getGuid()
public final CacheManager getCacheManager()
getCacheManager
in interface Ehcache
public void evictExpiredElements()
evictExpiredElements
in interface Ehcache
public boolean isKeyInCache(Object key)
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.
isKeyInCache
in interface Ehcache
key
- the key to check.public boolean isValueInCache(Object value)
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.
isValueInCache
in interface Ehcache
value
- to check forpublic StatisticsGateway getStatistics() throws IllegalStateException
Note, the getSize()
method will have the same value as the size
reported by Statistics for the statistics accuracy of
getStatistics
in interface Ehcache
IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public void setCacheManager(CacheManager cacheManager)
setCacheManager
in interface Ehcache
cacheManager
- the CacheManager for this cache to use.public BootstrapCacheLoader getBootstrapCacheLoader()
getBootstrapCacheLoader
in interface Ehcache
public void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) throws CacheException
setBootstrapCacheLoader
in interface Ehcache
bootstrapCacheLoader
- the loader to be usedCacheException
- if this method is called after the cache is initializedpublic boolean equals(Object object)
Object.equals(Object)
An Cache is equal to another one if it implements Ehcache and has the same GUID.
equals
in class Object
object
- the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.hashCode()
,
Hashtable
public int hashCode()
java.util.Hashtable
.
The general contract of hashCode
is:
hashCode
method on each of
the two objects must produce the same integer result.
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.
hashCode
in class Object
Object.equals(Object)
,
Hashtable
public void registerCacheExtension(CacheExtension cacheExtension)
CacheExtension
with the cache. It will then be tied into the cache lifecycle.
If the CacheExtension is not initialised, initialise it.
registerCacheExtension
in interface Ehcache
cacheExtension
- the cache extensionpublic List<CacheExtension> getRegisteredCacheExtensions()
getRegisteredCacheExtensions
in interface Ehcache
public void unregisterCacheExtension(CacheExtension cacheExtension)
CacheExtension
with the cache. It will then be detached from the cache lifecycle.unregisterCacheExtension
in interface Ehcache
cacheExtension
- the cache extensionpublic void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler)
The ExceptionHandler is only used if this Cache's methods are accessed using
ExceptionHandlingDynamicCacheProxy
.
setCacheExceptionHandler
in interface Ehcache
cacheExceptionHandler
- the cache exception handlerExceptionHandlingDynamicCacheProxy
public CacheExceptionHandler getCacheExceptionHandler()
The ExceptionHandler is only used if this Cache's methods are accessed using
ExceptionHandlingDynamicCacheProxy
.
getCacheExceptionHandler
in interface Ehcache
ExceptionHandlingDynamicCacheProxy
public void registerCacheLoader(CacheLoader cacheLoader)
CacheLoader
with the cache. It will then be tied into the cache lifecycle.
The CacheLoader instance will be initialized when the cache itself is being initialized.
Should the cache already be initialized, CacheLoader.init()
will not be invoked.
If the loader requires initialization, the user will have to call it manually before registering it with a Cache instance
that's already alive
registerCacheLoader
in interface Ehcache
cacheLoader
- A Cache Loader to registerpublic void unregisterCacheLoader(CacheLoader cacheLoader)
CacheLoader
with the cache. It will then be detached from the cache lifecycle.unregisterCacheLoader
in interface Ehcache
cacheLoader
- A Cache Loader to unregisterpublic List<CacheLoader> getRegisteredCacheLoaders()
getRegisteredCacheLoaders
in interface Ehcache
public void registerCacheWriter(CacheWriter cacheWriter)
CacheWriter
for this cache. It will then be tied into the cache lifecycle.
If the CacheWriter
is not initialised, initialise it.
registerCacheWriter
in interface Ehcache
cacheWriter
- A CacheWriter to registerpublic void unregisterCacheWriter()
CacheWriter
from the cache. It will then be detached from the cache lifecycle.
If not CacheWriter
was registered beforehand this operation has no effect.
unregisterCacheWriter
in interface Ehcache
public CacheWriter getRegisteredCacheWriter()
CacheWriter
that was registered for this cache.getRegisteredCacheWriter
in interface Ehcache
CacheWriter
; or null
if none was registered beforepublic void registerDynamicAttributesExtractor(DynamicAttributesExtractor extractor)
registerDynamicAttributesExtractor
in interface Ehcache
extractor
- the dynamic attribute extractorpublic boolean isDisabled()
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.
isDisabled
in interface Ehcache
?
public void setDisabled(boolean disabled)
net.sf.ehcache.disabled
system property is setsetDisabled
in interface Ehcache
disabled
- true if you wish to disable, false to enableisDisabled()
public Policy getMemoryStoreEvictionPolicy()
public void setMemoryStoreEvictionPolicy(Policy policy)
policy
- the new policypublic Object getInternalContext()
getInternalContext
in interface Ehcache
public void disableDynamicFeatures()
This is a one time operation. Once an Ehcache instance has had its dynamic operations disabled they cannot be re-enabled.
disableDynamicFeatures
in interface Ehcache
@Deprecated public boolean isClusterCoherent()
isClusterBulkLoadEnabled()
insteadIt applies to coherent clustering mechanisms only e.g. Terracotta
isClusterCoherent
in interface Ehcache
@Deprecated public boolean isNodeCoherent()
isNodeBulkLoadEnabled()
insteadIt applies to coherent clustering mechanisms only e.g. Terracotta
isNodeCoherent
in interface Ehcache
@Deprecated public void setNodeCoherent(boolean coherent)
setNodeBulkLoadEnabled(boolean)
insteadsetNodeCoherent(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.
setNodeCoherent
in interface Ehcache
coherent
- true transitions to coherent mode, false to incoherent mode@Deprecated public void waitUntilClusterCoherent()
waitUntilClusterBulkLoadComplete()
insteadIt applies to coherent clustering mechanisms only e.g. Terracotta
waitUntilClusterCoherent
in interface Ehcache
public void addPropertyChangeListener(PropertyChangeListener listener)
Ehcache
addPropertyChangeListener
in interface Ehcache
listener
- the PropertyChangeListener
to addpublic void removePropertyChangeListener(PropertyChangeListener listener)
Ehcache
removePropertyChangeListener
in interface Ehcache
listener
- the PropertyChangeListener
to removepublic void firePropertyChange(String propertyName, Object oldValue, Object newValue)
propertyName
- the name of the property that changedoldValue
- the old value of the property that changednewValue
- the new value of the property that changedpublic Element putIfAbsent(Element element) throws NullPointerException
putIfAbsent
in interface Ehcache
element
- element to be addedNullPointerException
- if the element is null, or has a null keypublic Element putIfAbsent(Element element, boolean doNotNotifyCacheReplicators) throws NullPointerException
putIfAbsent
in interface Ehcache
element
- element to be addeddoNotNotifyCacheReplicators
- whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
further notification to doNotNotifyCacheReplicators cache peersNullPointerException
- if the element is null, or has a null keypublic boolean removeElement(Element element) throws NullPointerException
This is equivalent to
if (elementValueComparator.equals(cache.get(element.getObjectKey()), element)) { return cache.remove(element.getObjectKey()); } else return false;except that the action is performed atomically.
removeElement
in interface Ehcache
element
- Element to be removedtrue
if the value was removedNullPointerException
- if the element is null, or has a null keyCacheConfiguration.addElementValueComparator(net.sf.ehcache.config.ElementValueComparatorConfiguration)
public boolean replace(Element old, Element element) throws NullPointerException, IllegalArgumentException
replace
in interface Ehcache
old
- Element to be test againstelement
- Element to be cachedNullPointerException
- if the either Element is null or has a null keyIllegalArgumentException
- if the two Element keys are non-null but not equalpublic Element replace(Element element) throws NullPointerException
replace
in interface Ehcache
element
- Element to be cachedNullPointerException
- if the Element is null or has a null keypublic void clusterCoherent(boolean clusterCoherent)
clusterCoherent
in interface StoreListener
clusterCoherent
- if the cluster is coherentStoreListener.clusterCoherent(boolean)
public Set<Attribute> getSearchAttributes() throws CacheException
getSearchAttributes
in interface Ehcache
CacheException
- in case of errorpublic <T> Attribute<T> getSearchAttribute(String attributeName) throws CacheException
getSearchAttribute
in interface Ehcache
T
- type of the attributeattributeName
- the name of the attribute to retrieveCacheException
- if no such attribute is defined for the given namepublic Query createQuery()
createQuery
in interface Ehcache
public boolean isSearchable()
isSearchable
in interface Ehcache
protected Sync getLockForKey(Object key)
key
- the key we want the lock forpublic void acquireReadLockOnKey(Object key)
acquireReadLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingpublic void acquireWriteLockOnKey(Object key)
acquireWriteLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingpublic boolean tryReadLockOnKey(Object key, long timeout) throws InterruptedException
tryReadLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingtimeout
- - millis until giveup on getting the lockInterruptedException
- in case the thread was interruptedpublic boolean tryWriteLockOnKey(Object key, long timeout) throws InterruptedException
tryWriteLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingtimeout
- - millis until giveup on getting the lockInterruptedException
- in case the thread was interruptedpublic void releaseReadLockOnKey(Object key)
releaseReadLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingpublic void releaseWriteLockOnKey(Object key)
releaseWriteLockOnKey
in interface Ehcache
key
- - The key that retrieves a value that you want to protect via lockingpublic boolean isReadLockedByCurrentThread(Object key) throws UnsupportedOperationException
Only Terracotta clustered cache instances currently support querying a thread's read lock hold status.
isReadLockedByCurrentThread
in interface Ehcache
key
- the keyUnsupportedOperationException
- if querying the read lock state is not supportedpublic boolean isWriteLockedByCurrentThread(Object key)
isWriteLockedByCurrentThread
in interface Ehcache
key
- the keypublic boolean isClusterBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException
NOTE: if Ehcache.isNodeBulkLoadEnabled()
returns true, this method will always return true.
Applies to caches clustered with Terracotta only.
isClusterBulkLoadEnabled
in interface Ehcache
UnsupportedOperationException
- if the cache is not clustered with TerracottaTerracottaNotRunningException
public boolean isNodeBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException
NOTE: if this method returns true, Ehcache.isClusterBulkLoadEnabled()
method will always return true.
Applies to caches clustered with Terracotta only.
isNodeBulkLoadEnabled
in interface Ehcache
UnsupportedOperationException
- if the cache is not clustered with TerracottaTerracottaNotRunningException
public void setNodeBulkLoadEnabled(boolean enabledBulkLoad) throws UnsupportedOperationException, TerracottaNotRunningException
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.
setNodeBulkLoadEnabled
in interface Ehcache
enabledBulkLoad
- true enables bulk-load, false disables it if not already disabledUnsupportedOperationException
- if the cache is not clustered with TerracottaTerracottaNotRunningException
public void waitUntilClusterBulkLoadComplete() throws UnsupportedOperationException, TerracottaNotRunningException
Applies to caches clustered with Terracotta only.
waitUntilClusterBulkLoadComplete
in interface Ehcache
UnsupportedOperationException
- if the cache is not clustered with TerracottaTerracottaNotRunningException
public void recalculateSize(Object key)
recalculateSize
in interface InternalEhcache
key
- the keyCopyright 2001-2020, Terracotta, Inc.