net.sf.ehcache
Interface Ehcache

All Superinterfaces:

java.lang.Cloneable

All Known Implementing Classes:

BlockingCache, Cache, SelfPopulatingCache, UpdatingSelfPopulatingCache

public interface Ehcache
extends java.lang.Cloneable

An interface for Ehcache.

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

A reference to an EhCache can be obtained through the CacheManager. An Ehcache 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.

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

Version:

$Id: Ehcache.java 704 2008-07-13 00:17:52Z gregluck $

Author:

Greg Luck

Method Summary

void	bootstrap() Bootstrap command.
long	calculateInMemorySize() Gets the size of the memory store for this cache Warning: This method can be very expensive to run.
void	clearStatistics() Resets statistics counters back to 0.
java.lang.Object	clone() Clones a cache.
void	dispose() Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
void	evictExpiredElements() Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
void	flush() Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
Element	get(java.lang.Object key) Gets an element from the cache.
Element	get(java.io.Serializable key) Gets an element from the cache.
java.util.Map	getAllWithLoader(java.util.Collection keys, java.lang.Object loaderArgument) Warning: This method is related to the JSR107 specification, which is in draft.
float	getAverageGetTime() The average get time in ms.
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() Sets an ExceptionHandler on the Cache.
CacheLoader	getCacheLoader() Gets the CacheLoader registered in this cache
CacheManager	getCacheManager() Gets the CacheManager managing this cache.
long	getDiskExpiryThreadIntervalSeconds()
int	getDiskStoreSize() Returns the number of elements in the disk store.
java.lang.String	getGuid() The GUID for this cache instance can be used to determine whether two cache instance references are pointing to the same cache.
java.util.List	getKeys() Returns a list of all elements in the cache, whether or not they are expired.
java.util.List	getKeysNoDuplicateCheck() Returns a list of all elements in the cache, whether or not they are expired.
java.util.List	getKeysWithExpiryCheck() Returns a list of all elements in the cache.
int	getMaxElementsInMemory() Gets the maximum number of elements to hold in memory.
int	getMaxElementsOnDisk() Gets the maximum number of elements to hold on Disk.
MemoryStoreEvictionPolicy	getMemoryStoreEvictionPolicy() The policy used to evict elements from the MemoryStore.
long	getMemoryStoreSize() Returns the number of elements in the memory store.
java.lang.String	getName() Gets the cache name.
Element	getQuiet(java.lang.Object key) Gets an element from the cache, without updating Element statistics.
Element	getQuiet(java.io.Serializable key) Gets an element from the cache, without updating Element statistics.
int	getSize() Gets the size of the cache.
Statistics	getStatistics() Gets an immutable Statistics object representing the Cache statistics at the time.
int	getStatisticsAccuracy() Accurately measuring statistics can be expensive.
Status	getStatus() Gets the status attribute of the Cache.
long	getTimeToIdleSeconds() Gets timeToIdleSeconds.
long	getTimeToLiveSeconds() Gets timeToLiveSeconds.
Element	getWithLoader(java.lang.Object key, CacheLoader loader, java.lang.Object loaderArgument) Warning: This method is related to the JSR107 specification, which is in draft.
void	initialise() Newly created caches do not have a MemoryStore or a DiskStore.
boolean	isDisabled() Whether this cache is disabled.
boolean	isDiskPersistent()
boolean	isElementInMemory(java.lang.Object key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementInMemory(java.io.Serializable key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
boolean	isElementOnDisk(java.lang.Object key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isElementOnDisk(java.io.Serializable key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
boolean	isEternal() Are elements eternal.
boolean	isExpired(Element element) Checks whether this cache element has expired.
boolean	isKeyInCache(java.lang.Object key) An inexpensive check to see if the key exists in the cache.
boolean	isOverflowToDisk() Does the overflow go to disk.
boolean	isValueInCache(java.lang.Object value) An extremely expensive check to see if the value exists in the cache.
void	load(java.lang.Object key) Warning: This method is related to the JSR107 specification, which is in draft.
void	loadAll(java.util.Collection keys, java.lang.Object argument) Warning: This method is related to the JSR107 specification, which is in draft.
void	put(Element element) Put an element in the cache.
void	put(Element element, boolean doNotNotifyCacheReplicators) Put an element in the cache.
void	putQuiet(Element element) Put an element in the cache, without updating statistics, or updating listeners.
void	registerCacheExtension(CacheExtension cacheExtension) Register a CacheExtension with the cache.
boolean	remove(java.lang.Object key) Removes an Element from the Cache.
boolean	remove(java.lang.Object key, boolean doNotNotifyCacheReplicators) Removes an Element from the Cache.
boolean	remove(java.io.Serializable key) Removes an Element from the Cache.
boolean	remove(java.io.Serializable key, boolean doNotNotifyCacheReplicators) Removes an Element from the Cache.
void	removeAll() Removes all cached items.
void	removeAll(boolean doNotNotifyCacheReplicators) Removes all cached items.
boolean	removeQuiet(java.lang.Object key) Removes an Element from the Cache, without notifying listeners.
boolean	removeQuiet(java.io.Serializable key) Removes an Element from the Cache, without notifying listeners.
void	setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) Sets the bootstrap cache loader.
void	setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler) Sets an ExceptionHandler on the Cache.
void	setCacheLoader(CacheLoader cacheLoader) Setter for the CacheLoader.
void	setCacheManager(CacheManager cacheManager) Sets the CacheManager
void	setDisabled(boolean disabled) Disables or enables this cache.
void	setDiskStorePath(java.lang.String diskStorePath) DiskStore paths can conflict between CacheManager instances.
void	setName(java.lang.String name) Sets the cache name which will name.
void	setStatisticsAccuracy(int statisticsAccuracy) Sets the statistics accuracy.
java.lang.String	toString() Returns a String representation of Cache.
void	unregisterCacheExtension(CacheExtension cacheExtension) Unregister a CacheExtension with the cache.

Method Detail

put

void put(Element element)
         throws java.lang.IllegalArgumentException,
                java.lang.IllegalStateException,
                CacheException

Put an element in the cache.

Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

Also notifies the CacheEventListener that:

• the element was put, but only if the Element was actually put.
• if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested

Parameters:

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

Throws:

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

java.lang.IllegalArgumentException - if the element is null

CacheException

put

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

Put an element in the cache.

Resets the access statistics on the element, which would be the case if it has previously been gotten from a cache, and is now being put back.

Also notifies the CacheEventListener that:

• the element was put, but only if the Element was actually put.
• if the element exists in the cache, that an update has occurred, even if the element would be expired if it was requested

Parameters:

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

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Throws:

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

java.lang.IllegalArgumentException - if the element is null

CacheException

putQuiet

void putQuiet(Element element)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalStateException,
                     CacheException

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

Parameters:

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

Throws:

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

java.lang.IllegalArgumentException - if the element is null

CacheException

get

Element get(java.io.Serializable key)
            throws java.lang.IllegalStateException,
                   CacheException

Gets an element from the cache. Updates Element Statistics

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

Parameters:

key - a serializable value

Returns:

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

Throws:

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

CacheException

See Also:

isExpired(net.sf.ehcache.Element)

get

Element get(java.lang.Object key)
            throws java.lang.IllegalStateException,
                   CacheException

Gets an element from the cache. Updates Element Statistics

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

Parameters:

key - an Object value

Returns:

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

Throws:

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

CacheException

Since:

1.2

See Also:

isExpired(net.sf.ehcache.Element)

getQuiet

Element getQuiet(java.io.Serializable key)
                 throws java.lang.IllegalStateException,
                        CacheException

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

Parameters:

key - a serializable value

Returns:

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

Throws:

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

CacheException

See Also:

isExpired(net.sf.ehcache.Element)

getQuiet

Element getQuiet(java.lang.Object key)
                 throws java.lang.IllegalStateException,
                        CacheException

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

Parameters:

key - a serializable value

Returns:

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

Throws:

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

CacheException

Since:

1.2

See Also:

isExpired(net.sf.ehcache.Element)

getKeys

java.util.List getKeys()
                       throws java.lang.IllegalStateException,
                              CacheException

Returns a list of all elements 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:

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

CacheException

getKeysWithExpiryCheck

java.util.List getKeysWithExpiryCheck()
                                      throws java.lang.IllegalStateException,
                                             CacheException

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

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

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

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

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

Returns:

a list of Object keys

Throws:

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

CacheException

getKeysNoDuplicateCheck

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

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

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

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

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

This is the fastest getKeys method

Returns:

a list of Object keys

Throws:

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

remove

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

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

Also notifies the CacheEventListener after the element was removed.

Parameters:

key -

Returns:

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

Throws:

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

remove

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

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

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Parameters:

key -

Returns:

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

Throws:

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

Since:

1.2

remove

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

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

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Parameters:

key -

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Returns:

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

Throws:

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

remove

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

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

Also notifies the CacheEventListener after the element was removed, but only if an Element with the key actually existed.

Parameters:

key -

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Returns:

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

Throws:

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

removeQuiet

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

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

Parameters:

key -

Returns:

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

Throws:

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

removeQuiet

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

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

Parameters:

key -

Returns:

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

Throws:

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

Since:

1.2

removeAll

void removeAll()
               throws java.lang.IllegalStateException,
                      CacheException

Removes all cached items.

Throws:

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

CacheException

removeAll

void removeAll(boolean doNotNotifyCacheReplicators)
               throws java.lang.IllegalStateException,
                      CacheException

Removes all cached items.

Parameters:

doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers

Throws:

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

CacheException

flush

void flush()
           throws java.lang.IllegalStateException,
                  CacheException

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

Throws:

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

CacheException

getSize

int getSize()
            throws java.lang.IllegalStateException,
                   CacheException

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

The size is the number of Elements in the MemoryStore plus the number of Elements in the 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:

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

CacheException

calculateInMemorySize

long calculateInMemorySize()
                           throws java.lang.IllegalStateException,
                                  CacheException

Gets the size of the memory store for this cache

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

Returns:

the approximate size of the memory store in bytes

Throws:

java.lang.IllegalStateException

CacheException

getMemoryStoreSize

long getMemoryStoreSize()
                        throws java.lang.IllegalStateException

Returns the number of elements in the memory store.

Returns:

the number of elements in the memory store

Throws:

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

getDiskStoreSize

int getDiskStoreSize()
                     throws java.lang.IllegalStateException

Returns the number of elements in the disk store.

Returns:

the number of elements in the disk store.

Throws:

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

getStatus

Status getStatus()

Gets the status attribute of the Cache.

Returns:

The status value from the Status enum class

getName

java.lang.String getName()

Gets the cache name.

setName

void setName(java.lang.String name)

Sets the cache name which will name.

Parameters:

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

getTimeToIdleSeconds

long getTimeToIdleSeconds()

Gets timeToIdleSeconds.

getTimeToLiveSeconds

long getTimeToLiveSeconds()

Gets timeToLiveSeconds.

isEternal

boolean isEternal()

Are elements eternal.

isOverflowToDisk

boolean isOverflowToDisk()

Does the overflow go to disk.

getMaxElementsInMemory

int getMaxElementsInMemory()

Gets the maximum number of elements to hold in memory.

getMaxElementsOnDisk

int getMaxElementsOnDisk()

Gets the maximum number of elements to hold on Disk.

getMemoryStoreEvictionPolicy

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

toString

java.lang.String toString()

Returns a String representation of Cache.

Overrides:

toString in class java.lang.Object

isExpired

boolean isExpired(Element element)
                  throws java.lang.IllegalStateException,
                         java.lang.NullPointerException

Checks whether this cache element has expired.

The element is expired if:

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

Parameters:

element - the element to check

Returns:

true if it has expired

Throws:

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

java.lang.NullPointerException - if the element is null

clone

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

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

A new, empty, RegisteredEventListeners is created on clone.

Returns:

an object of type Cache

Throws:

java.lang.CloneNotSupportedException

isDiskPersistent

boolean isDiskPersistent()

Returns:

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

getDiskExpiryThreadIntervalSeconds

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.

getCacheEventNotificationService

RegisteredEventListeners getCacheEventNotificationService()

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

Returns:

the RegisteredEventListeners instance for this cache.

isElementInMemory

boolean isElementInMemory(java.io.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

boolean isElementInMemory(java.lang.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

boolean isElementOnDisk(java.io.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

boolean isElementOnDisk(java.lang.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

getGuid

java.lang.String getGuid()

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

Returns:

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

Since:

1.2

getCacheManager

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

clearStatistics

void clearStatistics()

Resets statistics counters back to 0.

getStatisticsAccuracy

int getStatisticsAccuracy()

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

Returns:

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

setStatisticsAccuracy

void setStatisticsAccuracy(int statisticsAccuracy)

Sets the statistics accuracy.

Parameters:

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

evictExpiredElements

void evictExpiredElements()

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

isKeyInCache

boolean isKeyInCache(java.lang.Object key)

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

Parameters:

key - the key to check for

Returns:

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

isValueInCache

boolean isValueInCache(java.lang.Object value)

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

Parameters:

value - to check for

Returns:

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

getStatistics

Statistics getStatistics()
                         throws java.lang.IllegalStateException

Gets an immutable Statistics object representing the Cache statistics at the time. How the statistics are calculated depends on the statistics accuracy setting. The only aspect of statistics sensitive to the accuracy setting is object size. How that is calculated is discussed below.

Best Effort Size

This result is returned when the statistics accuracy setting is Statistics.STATISTICS_ACCURACY_BEST_EFFORT.

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

This number is the actual number of elements, including expired elements that have not been removed. Any duplicates between stores are accounted for.

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

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

Guaranteed Accuracy Size

This result is returned when the statistics accuracy setting is Statistics.STATISTICS_ACCURACY_GUARANTEED.

This method accounts for elements which might be expired or duplicated between stores. It take approximately 200ms per 1000 elements to execute.

Fast but non-accurate Size

This result is returned when the statistics accuracy setting is Statistics.STATISTICS_ACCURACY_NONE.

The number given may contain expired elements. In addition if the DiskStore is used it may contain some double counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take 36ms.

Returns:

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

Throws:

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

setCacheManager

void setCacheManager(CacheManager cacheManager)

Sets the CacheManager

Parameters:

cacheManager - the CacheManager for this cache to use.

getBootstrapCacheLoader

BootstrapCacheLoader getBootstrapCacheLoader()

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

Returns:

the BootstrapCacheLoader to use

setBootstrapCacheLoader

void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
                             throws CacheException

Sets the bootstrap cache loader.

Parameters:

bootstrapCacheLoader - the loader to be used

Throws:

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

setDiskStorePath

void setDiskStorePath(java.lang.String diskStorePath)
                      throws CacheException

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

initialise

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

bootstrap

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.

dispose

void dispose()
             throws java.lang.IllegalStateException

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

Should be invoked only by CacheManager.

Throws:

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

getCacheConfiguration

CacheConfiguration getCacheConfiguration()

Gets the cache configuration this cache was created with.

Things like listeners that are added dynamically are excluded.

registerCacheExtension

void registerCacheExtension(CacheExtension cacheExtension)

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

If the CacheExtension is not initialised, initialise it.

unregisterCacheExtension

void unregisterCacheExtension(CacheExtension cacheExtension)

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

getAverageGetTime

float getAverageGetTime()

The average get time in ms.

setCacheExceptionHandler

void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler)

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

getCacheExceptionHandler

CacheExceptionHandler getCacheExceptionHandler()

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

setCacheLoader

void setCacheLoader(CacheLoader cacheLoader)

Setter for the CacheLoader. Changing the CacheLoader takes immediate effect.

Parameters:

cacheLoader - the loader to dynamically load new cache entries

getCacheLoader

CacheLoader getCacheLoader()

Gets the CacheLoader registered in this cache

Returns:

the loader, or null if there is none

getWithLoader

Element getWithLoader(java.lang.Object key,
                      CacheLoader loader,
                      java.lang.Object loaderArgument)
                      throws CacheException

Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.

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

If the object is not in the cache, the associated cache loader will be called. That is either the CacheLoader passed in, or if null, the one associated with the cache. If both are null, no load is performed and null is returned.

Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

Parameters:

key - key whose associated value is to be returned.

loader - the override loader to use. If null, the cache's default loader will be used

loaderArgument - an argument to pass to the CacheLoader.

Returns:

an element if it existed or could be loaded, otherwise null

Throws:

CacheException

getAllWithLoader

java.util.Map getAllWithLoader(java.util.Collection keys,
                               java.lang.Object loaderArgument)
                               throws CacheException

Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.

The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

Note. If the getAll exceeds the maximum cache size, the returned map will necessarily be less than the number specified.

Because this method may take a long time to complete, it is not synchronized. The underlying cache operations are synchronized.

The constructs package provides similar functionality using the decorator SelfPopulatingCache

Parameters:

keys - a collection of keys to be returned/loaded

loaderArgument - an argument to pass to the CacheLoader.

Returns:

a Map populated from the Cache. If there are no elements, an empty Map is returned.

Throws:

CacheException

load

void load(java.lang.Object key)
          throws CacheException

Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.

The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified object into the cache using the associated cacheloader. If the object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

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

Parameters:

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

Throws:

CacheException

loadAll

void loadAll(java.util.Collection keys,
             java.lang.Object argument)
             throws CacheException

Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.

The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load the specified objects into the cache using the associated cache loader. If the an object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) should be logged. The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method.

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

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

Throws:

CacheException

isDisabled

boolean isDisabled()

Whether this cache is disabled. "Disabled" means:

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

In all other respects the cache continues as it is.

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

Returns:

true if the cache is disabled.

setDisabled

void setDisabled(boolean disabled)

Disables or enables this cache. This call overrides the previous value of disabled.

Parameters:

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

See Also:

isDisabled()