net.sf.ehcache

Class Cache

public class Cache extends Object implements Ehcache

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_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 is invoked.

Cache is threadsafe.

Statistics on cache usage are collected and made available through public methods.

Version: $Id: Cache.java 191 2006-09-03 22:41:48Z gregluck $

Author: Greg Luck

Field Summary
static StringDEFAULT_CACHE_NAME
A reserved word for cache names.
static longDEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
The default interval between runs of the expiry thread.
static StringNET_SF_EHCACHE_DISABLED
System Property based method of disabling ehcache.
Constructor Summary
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 Constructor

The ConfigurationFactory and clients can create these.

Method Summary
voidbootstrap()
Bootstrap command.
longcalculateInMemorySize()
Gets the size of the memory store for this cache.
voidclearStatistics()
Resets statistics counters back to 0.
Objectclone()
Clones a cache.
voiddispose()
Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
booleanequals(Object object)
An equals method which follows the contract of Object#equals(Object)
voidevictExpiredElements()
Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
voidflush()
Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
Elementget(Serializable key)
Gets an element from the cache.
Elementget(Object key)
Gets an element from the cache.
BootstrapCacheLoadergetBootstrapCacheLoader()
Accessor for the BootstrapCacheLoader associated with this cache.
RegisteredEventListenersgetCacheEventNotificationService()
Use this to access the service in order to register and unregister listeners
CacheManagergetCacheManager()
Gets the CacheManager managing this cache.
longgetDiskExpiryThreadIntervalSeconds()
DiskStoregetDiskStore()
Gets the internal DiskStore.
intgetDiskStoreHitCount()
Number of times a requested item was found in the Disk Store.
intgetDiskStoreSize()
Returns the number of elements in the disk store.
StringgetGuid()
The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.
intgetHitCount()
The number of times a requested item was found in the cache.
ListgetKeys()
Returns a list of all element keys in the cache, whether or not they are expired.
ListgetKeysNoDuplicateCheck()
Returns a list of all elements in the cache, whether or not they are expired.
ListgetKeysWithExpiryCheck()
Returns a list of all element keys in the cache.
intgetMaxElementsInMemory()
Gets the maximum number of elements to hold in memory.
MemoryStoregetMemoryStore()
Gets the internal MemoryStore.
MemoryStoreEvictionPolicygetMemoryStoreEvictionPolicy()
The policy used to evict elements from the MemoryStore.
intgetMemoryStoreHitCount()
Number of times a requested item was found in the Memory Store.
longgetMemoryStoreSize()
Returns the number of elements in the memory store.
intgetMissCountExpired()
Number of times a requested element was found but was expired.
intgetMissCountNotFound()
Number of times a requested element was not found in the cache.
StringgetName()
Gets the cache name.
ElementgetQuiet(Serializable key)
Gets an element from the cache, without updating Element statistics.
ElementgetQuiet(Object key)
Gets an element from the cache, without updating Element statistics.
intgetSize()
Gets the size of the cache.
StatisticsgetStatistics()
{@inheritDoc }

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

intgetStatisticsAccuracy()
Accurately measuring statistics can be expensive.
StatusgetStatus()
Gets the status attribute of the Cache.
longgetTimeToIdleSeconds()
Gets timeToIdleSeconds.
longgetTimeToLiveSeconds()
Gets timeToLiveSeconds.
inthashCode()
Returns a hash code value for the object.
voidinitialise()
Newly created caches do not have a MemoryStore or a DiskStore.
booleanisDiskPersistent()
booleanisElementInMemory(Serializable key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
booleanisElementInMemory(Object key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
booleanisElementOnDisk(Serializable key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
booleanisElementOnDisk(Object key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
booleanisEternal()
Are elements eternal.
booleanisExpired(Element element)
Checks whether this cache element has expired.
booleanisKeyInCache(Object key)
An inexpensive check to see if the key exists in the cache.
booleanisOverflowToDisk()
Does the overflow go to disk.
booleanisValueInCache(Object value)
An extremely expensive check to see if the value exists in the cache.
voidput(Element element)
Put an element in the cache.
voidput(Element element, boolean doNotNotifyCacheReplicators)
Put an element in the cache.
voidputQuiet(Element element)
Put an element in the cache, without updating statistics, or updating listeners.
booleanremove(Serializable key)
Removes an Element from the Cache.
booleanremove(Object key)
Removes an Element from the Cache.
booleanremove(Serializable key, boolean doNotNotifyCacheReplicators)
Removes an Element from the Cache.
booleanremove(Object key, boolean doNotNotifyCacheReplicators)
Removes an Element from the Cache.
voidremoveAll()
Removes all cached items.
voidremoveAll(boolean doNotNotifyCacheReplicators)
Removes all cached items.
booleanremoveQuiet(Serializable key)
Removes an Element from the Cache, without notifying listeners.
booleanremoveQuiet(Object key)
Removes an Element from the Cache, without notifying listeners.
voidsetBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
Sets the bootstrap cache loader.
voidsetCacheManager(CacheManager cacheManager)
For use by CacheManager.
voidsetDiskStorePath(String diskStorePath)
DiskStore paths can conflict between CacheManager instances.
voidsetName(String name)
Sets the cache name which will name.
voidsetStatisticsAccuracy(int statisticsAccuracy)
Sets the statistics accuracy.
StringtoString()
Returns a String representation of Cache.

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.

DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS

public static final long DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
The default interval between runs of the expiry thread.

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.

Constructor Detail

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 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 maxElementsInMemory the maximum number of elements in memory, before they are evicted 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

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 to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters: name the name of the cache maxElementsInMemory the maximum number of elements in memory, before they are evicted 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

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 to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters: name the name of the cache maxElementsInMemory the maximum number of elements in memory, before they are evicted 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

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 Constructor

The ConfigurationFactory and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Parameters: name the name of the cache maxElementsInMemory the maximum number of elements in memory, before they are evicted 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

Method Detail

bootstrap

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

calculateInMemorySize

public final long calculateInMemorySize()
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

Returns: the approximate size of the memory store in bytes

Throws: IllegalStateException

clearStatistics

public void clearStatistics()
Resets statistics counters back to 0.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

clone

public final Object clone()
Clones a cache. This is only legal if the cache has not been initialized. At that point only primitives have been set and no LruMemoryStore or DiskStore has been created.

A new, empty, RegisteredEventListeners is created on clone.

Returns: an object of type Cache

Throws: CloneNotSupportedException

dispose

public void dispose()
Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.

Should be invoked only by CacheManager.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

equals

public boolean equals(Object object)
An equals method which follows the contract of Object#equals(Object)

Parameters: object the reference object with which to compare.

Returns: true if this object is the same as the obj argument; false otherwise. Same for a Cache means, the same GUID

See Also: hashCode java.util.Hashtable

evictExpiredElements

public void evictExpiredElements()
Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.

flush

public final void flush()
Flushes all cache items from memory to the disk store, and from the DiskStore to disk.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

get

public final Element get(Serializable key)
Gets an element from the cache. Updates Element Statistics

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

Synchronization is handled within the method.

Parameters: key a serializable value

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE

See Also: Cache

get

public final Element get(Object key)
Gets an element from the cache. Updates Element Statistics

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

Synchronization is handled within the method.

Parameters: key an Object value

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE

Since: 1.2

See Also: Cache

getBootstrapCacheLoader

public BootstrapCacheLoader getBootstrapCacheLoader()
Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.

getCacheEventNotificationService

public final RegisteredEventListeners getCacheEventNotificationService()
Use this to access the service in order to register and unregister listeners

Returns: the RegisteredEventListeners instance for this cache.

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.

Returns: the manager or null if there is none

getDiskExpiryThreadIntervalSeconds

public final long getDiskExpiryThreadIntervalSeconds()

Returns: the interval between runs of the expiry thread, where it checks the disk store for expired elements. It is not the the timeToLiveSeconds.

getDiskStore

final DiskStore getDiskStore()
Gets the internal DiskStore.

Returns: the DiskStore referenced by this cache

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getDiskStoreHitCount

public final int getDiskStoreHitCount()
Number of times a requested item was found in the Disk Store.

getDiskStoreSize

public final int getDiskStoreSize()
Returns the number of elements in the disk store.

Returns: the number of elements in the disk store.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

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.

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

Since: 1.2

getHitCount

public final int getHitCount()
The number of times a requested item was found in the cache.

Returns: the number of times a requested item was found in the cache

getKeys

public final List getKeys()
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.

Returns: a list of Object keys

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getKeysNoDuplicateCheck

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

Returns: a list of Object keys

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getKeysWithExpiryCheck

public final List getKeysWithExpiryCheck()
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 syncrhonized, 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.

Returns: a list of Object keys

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getMaxElementsInMemory

public final int getMaxElementsInMemory()
Gets the maximum number of elements to hold in memory.

getMemoryStore

final MemoryStore getMemoryStore()
Gets the internal MemoryStore.

Returns: the MemoryStore referenced by this cache

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getMemoryStoreEvictionPolicy

public final MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy()
The policy used to evict elements from the MemoryStore. This can be one of:
  1. LRU - least recently used
  2. LFU - least frequently used
  3. FIFO - first in first out, the oldest element by creation time
The default value is LRU

Since: 1.2

getMemoryStoreHitCount

public final int getMemoryStoreHitCount()
Number of times a requested item was found in the Memory Store.

Returns: Number of times a requested item was found in the Memory Store.

getMemoryStoreSize

public final long getMemoryStoreSize()
Returns the number of elements in the memory store.

Returns: the number of elements in the memory store

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getMissCountExpired

public final int getMissCountExpired()
Number of times a requested element was found but was expired.

getMissCountNotFound

public final int getMissCountNotFound()
Number of times a requested element was not found in the cache. This may be because it expired, in which case this will also be recorded in Cache, or because it was simply not there.

getName

public final String getName()
Gets the cache name.

getQuiet

public final Element getQuiet(Serializable key)
Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

Synchronization is handled within the method.

Parameters: key a serializable value

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE

See Also: Cache

getQuiet

public final Element getQuiet(Object key)
Gets an element from the cache, without updating Element statistics. Cache statistics are not updated.

Synchronization is handled within the method.

Parameters: key a serializable value

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE

Since: 1.2

See Also: Cache

getSize

public final int getSize()
Gets the size of the cache. This is a subtle concept. See below.

The size is the number of Elements in the MemoryStore plus the number of Elements in the DiskStore.

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

Expired elements are removed from the the memory store when getting an expired element, or when attempting to spool an expired element to disk.

Expired elements are removed from the disk store when getting an expired element, or when the expiry thread runs, which is once every five minutes.

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

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

Returns: The size value

Throws: IllegalStateException if the cache is not STATUS_ALIVE

getStatistics

public Statistics getStatistics()
{@inheritDoc }

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

getStatisticsAccuracy

public int getStatisticsAccuracy()
Accurately measuring statistics can be expensive. Returns the current accuracy setting.

Returns: one of STATISTICS_ACCURACY_BEST_EFFORT, STATISTICS_ACCURACY_GUARANTEED, STATISTICS_ACCURACY_NONE

getStatus

public final Status getStatus()
Gets the status attribute of the Cache.

Returns: The status value from the Status enum class

getTimeToIdleSeconds

public final long getTimeToIdleSeconds()
Gets timeToIdleSeconds.

getTimeToLiveSeconds

public final long getTimeToLiveSeconds()
Gets timeToLiveSeconds.

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:

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 JavaTM programming language.)

This implementation use the GUID of the cache.

Returns: a hash code value for this object.

See Also: Object#equals(Object) java.util.Hashtable

initialise

public void initialise()
Newly created caches do not have a MemoryStore or a DiskStore.

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

isDiskPersistent

public final boolean isDiskPersistent()

Returns: true if the cache overflows to disk and the disk is persistent between restarts

isElementInMemory

public final boolean isElementInMemory(Serializable key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

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.

Returns: true if an element matching the key is found in memory

Since: 1.2

isElementOnDisk

public final boolean isElementOnDisk(Serializable key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

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.

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

Since: 1.2

isEternal

public final boolean isEternal()
Are elements eternal.

isExpired

public final boolean isExpired(Element element)
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.

Returns: true if it has expired

Throws: IllegalStateException if the cache is not STATUS_ALIVE NullPointerException if the element is null

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 aned be removed before the check gets to it, or vice versa.

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.

isOverflowToDisk

public final boolean isOverflowToDisk()
Does the overflow go to disk.

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

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.

put

public final void put(Element element)
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:

Synchronization is handled within the method.

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE IllegalArgumentException if the element is null

put

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

Synchronization is handled within the method.

Parameters: element An object. If Serializable it can fully participate in replication and the DiskStore. doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Throws: IllegalStateException if the cache is not STATUS_ALIVE IllegalArgumentException if the element is null

putQuiet

public final void putQuiet(Element element)
Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used in conjunction with Cache. Synchronization is handled within the method.

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

Throws: IllegalStateException if the cache is not STATUS_ALIVE IllegalArgumentException if the element is null

remove

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

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_ALIVE

remove

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

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_ALIVE

Since: 1.2

remove

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

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_ALIVE

UNKNOWN: SameParameterValue

remove

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

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_ALIVE

removeAll

public void removeAll()
Removes all cached items. Synchronization is handled within the method.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

removeAll

public void removeAll(boolean doNotNotifyCacheReplicators)
Removes all cached items. Synchronization is handled within the method.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

removeQuiet

public final boolean removeQuiet(Serializable key)
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Synchronization is handled within the method.

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_ALIVE

removeQuiet

public final boolean removeQuiet(Object key)
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Synchronization is handled within the method.

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_ALIVE

Since: 1.2

setBootstrapCacheLoader

public void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
Sets the bootstrap cache loader.

Parameters: bootstrapCacheLoader the loader to be used

Throws: CacheException if this method is called after the cache is initialized

setCacheManager

public void setCacheManager(CacheManager cacheManager)
For use by CacheManager.

Parameters: cacheManager the CacheManager for this cache to use.

setDiskStorePath

public void setDiskStorePath(String diskStorePath)
DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.

Parameters: diskStorePath the new path to be used.

Throws: CacheException if this method is called after the cache is initialized

setName

public final void setName(String name)
Sets the cache name which will name.

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.

setStatisticsAccuracy

public void setStatisticsAccuracy(int statisticsAccuracy)
Sets the statistics accuracy.

Parameters: statisticsAccuracy one of STATISTICS_ACCURACY_BEST_EFFORT, STATISTICS_ACCURACY_GUARANTEED, STATISTICS_ACCURACY_NONE

toString

public final String toString()
Returns a String representation of Cache.