net.sf.ehcache.constructs.blocking

Class BlockingCache

public class BlockingCache extends Object implements Ehcache

A blocking decorator for an Ehcache, backed by a Ehcache.

It allows concurrent read access to elements already in the cache. If the element is null, other reads will block until an element with the same key is put into the cache.

This is useful for constructing read-through or self-populating caches.

This implementation uses the Mutex class from Doug Lea's concurrency package. If you wish to use this class, you will need the concurrent package in your class path.

It features:

This class has been updated to use Lock striping. The Mutex implementation gives scalability but creates many Mutex objects of 24 bytes each. Lock striping limits their number to 100.

A version of this class is planned which will dynamically use JDK5's concurrency package, which is based on Doug Lea's, so as to avoid a dependency on his package for JDK5 systems. This will not be implemented until JDK5 is released on MacOSX and Linux, as JDK5 will be required to compile it, though any version from JDK1.2 up will be able to run the code, falling back to Doug Lea's concurrency package, if the JDK5 package is not found in the classpath.

The Mutex class does not appear in the JDK5 concurrency package. Doug Lea has generously offered the following advice:

"You should just be able to use ReentrantLock here. We supply ReentrantLock, but not Mutex because the number of cases where a non-reentrant mutex is preferable is small, and most people are more familiar with reentrant seamantics. If you really need a non-reentrant one, the javadocs for class AbstractQueuedSynchronizer include sample code for them."

-Doug

"Hashtable / synchronizedMap uses the "one big fat lock" approach to guard the mutable state of the map. That works, but is a big concurrency bottleneck, as you've observed. You went to the opposite extreme, one lock per key. That works (as long as you've got sufficient synchronization in the cache itself to protect its own data structures.)

Lock striping is a middle ground, partitioning keys into a fixed number of subsets, like the trick used at large theaters for will-call ticket pickup -- there are separate lines for "A-F, G-M, N-R, and S-Z". This way, there are a fixed number of locks, each guarding (hopefully) 1/Nth of the keys." - Brian Goetz

Further improvements to hashing suggested by Joe Bowbeer.

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

Author: Greg Luck

Field Summary
protected Ehcachecache
The backing Cache
protected Mutex[]locks
Based on the lock striping concept from Brian Goetz.
static intLOCK_NUMBER
The default number of locks to use.
protected inttimeoutMillis
The amount of time to block a thread before a LockTimeoutException is thrown
Constructor Summary
BlockingCache(Ehcache cache)
Creates a BlockingCache which decorates the supplied cache.
Method Summary
voidbootstrap()
Bootstrap command.
longcalculateInMemorySize()
Gets the size of the memory store for this cache

Warning: This method can be very expensive to run.

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.
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(Object key)
Looks up an entry.
Elementget(Serializable key)
Gets an element from the cache.
BootstrapCacheLoadergetBootstrapCacheLoader()
Accessor for the BootstrapCacheLoader associated with this cache.
protected EhcachegetCache()
Retrieve the EHCache backing cache
RegisteredEventListenersgetCacheEventNotificationService()
Use this to access the service in order to register and unregister listeners
CacheManagergetCacheManager()
Gets the CacheManager managing this cache.
longgetDiskExpiryThreadIntervalSeconds()
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 the keys for this cache.
ListgetKeysNoDuplicateCheck()
Returns a list of all elements in the cache, whether or not they are expired.
ListgetKeysWithExpiryCheck()
Returns a list of all elements in the cache.
protected MutexgetLockForKey(Object key)
Gets the Mutex to use for a given key.
intgetMaxElementsInMemory()
Gets the maximum number of elements to hold in memory.
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()
Returns this cache's 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()
Gets an immutable Statistics object representing the Cache statistics at the time.
intgetStatisticsAccuracy()
Accurately measuring statistics can be expensive.
StatusgetStatus()
Gets the status attribute of the Cache.
intgetTimeoutMillis()
Gets the time to wait to acquire a lock.
longgetTimeToIdleSeconds()
Gets timeToIdleSeconds.
longgetTimeToLiveSeconds()
Gets timeToLiveSeconds.
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.
Stringliveness()
Synchronized version of getName to test liveness of the object lock.
voidput(Element element)
Adds an entry and unlocks it
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)
Sets the 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.
voidsetTimeoutMillis(int timeoutMillis)
Sets the time to wait to acquire a lock.

Field Detail

cache

protected final Ehcache cache
The backing Cache

locks

protected final Mutex[] locks
Based on the lock striping concept from Brian Goetz. See Java Concurrency in Practice 11.4.3

LOCK_NUMBER

public static final int LOCK_NUMBER
The default number of locks to use. Must be a power of 2

timeoutMillis

protected int timeoutMillis
The amount of time to block a thread before a LockTimeoutException is thrown

Constructor Detail

BlockingCache

public BlockingCache(Ehcache cache)
Creates a BlockingCache which decorates the supplied cache.

Parameters: cache a backing ehcache.

Throws: CacheException

Since: 1.2

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 long calculateInMemorySize()
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: IllegalStateException

clearStatistics

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

clone

public 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

evictExpiredElements

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

flush

public 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 Element get(Object key)
Looks up an entry. Blocks if the entry is null until a call to BlockingCache is done to put an Element in.

If a put is not done, the lock is never released

Note. If a LockTimeoutException is thrown while doing a BlockingCache it means the lock was never acquired, therefore it is a threading error to call BlockingCache

Throws: LockTimeoutException if timeout millis is non zero and this method has been unable to acquire a lock in that time

get

public 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

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: BlockingCache

getBootstrapCacheLoader

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

getCache

protected Ehcache getCache()
Retrieve the EHCache backing cache

getCacheEventNotificationService

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

Returns: the RegisteredEventListeners instance for this cache.

getCacheManager

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

getDiskStoreHitCount

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

getDiskStoreSize

public 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 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 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 List getKeys()
Returns the keys for this cache.

Returns: The keys of this cache. This is not a live set, so it will not track changes to the key set.

getKeysNoDuplicateCheck

public 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 List getKeysWithExpiryCheck()
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: IllegalStateException if the cache is not STATUS_ALIVE

getLockForKey

protected Mutex getLockForKey(Object key)
Gets the Mutex to use for a given key.

Parameters: key the key

Returns: one of a limited number of Mutexes.

getMaxElementsInMemory

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

getMemoryStoreEvictionPolicy

public 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 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 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 int getMissCountExpired()
Number of times a requested element was found but was expired.

getMissCountNotFound

public 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 BlockingCache, or because it was simply not there.

getName

public String getName()
Returns this cache's name

getQuiet

public Element getQuiet(Serializable key)
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: IllegalStateException if the cache is not STATUS_ALIVE

See Also: BlockingCache

getQuiet

public Element getQuiet(Object key)
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: IllegalStateException if the cache is not STATUS_ALIVE

Since: 1.2

See Also: BlockingCache

getSize

public 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()
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_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_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_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: IllegalStateException if the cache is not STATUS_ALIVE

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 Status getStatus()
Gets the status attribute of the Cache.

Returns: The status value from the Status enum class

getTimeoutMillis

public int getTimeoutMillis()
Gets the time to wait to acquire a lock.

Returns: the time in ms.

getTimeToIdleSeconds

public long getTimeToIdleSeconds()
Gets timeToIdleSeconds.

getTimeToLiveSeconds

public long getTimeToLiveSeconds()
Gets timeToLiveSeconds.

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 boolean isDiskPersistent()

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

isElementInMemory

public 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 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 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 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 boolean isEternal()
Are elements eternal.

isExpired

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

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.

isOverflowToDisk

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

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.

liveness

public String liveness()
Synchronized version of getName to test liveness of the object lock.

The time taken for this method to return is a useful measure of runtime contention on the cache.

put

public void put(Element element)
Adds an entry and unlocks it

put

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

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 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 BlockingCache

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

Parameters: key

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

Parameters: key

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

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: IllegalStateException if the cache is not STATUS_ALIVE

UNKNOWN: SameParameterValue

remove

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

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: IllegalStateException if the cache is not STATUS_ALIVE

removeAll

public void removeAll()
Removes all cached items.

Throws: IllegalStateException if the cache is not STATUS_ALIVE

removeAll

public void removeAll(boolean doNotNotifyCacheReplicators)
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: IllegalStateException if the cache is not STATUS_ALIVE

removeQuiet

public boolean removeQuiet(Serializable key)
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: IllegalStateException if the cache is not STATUS_ALIVE

removeQuiet

public boolean removeQuiet(Object key)
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: 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: net.sf.ehcache.CacheException if this method is called after the cache is initialized

setCacheManager

public void setCacheManager(CacheManager cacheManager)
Sets the CacheManager

Parameters: cacheManager

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: net.sf.ehcache.CacheException if this method is called after the cache is initialized

setName

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

Parameters: name the name of the cache. Should not be null.

setStatisticsAccuracy

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

Parameters: statisticsAccuracy one of STATISTICS_ACCURACY_BEST_EFFORT, STATISTICS_ACCURACY_GUARANTEED, STATISTICS_ACCURACY_NONE

setTimeoutMillis

public void setTimeoutMillis(int timeoutMillis)
Sets the time to wait to acquire a lock. This may be modified at any time.

The consequences of setting a timeout are:

  1. if a lock cannot be acquired in the given time a LockTimeoutException is thrown.
  2. if there is a queue of threads waiting for the first thread to complete, but it does not complete within the time out period, the successive threads may find that they have exceeded their lock timeouts and fail. This is usually a good thing because it stops a build up of threads from overwhelming a busy resource, but it does need to be considered in the design of user interfaces. The timeout should be set no greater than the time a user would be expected to wait before considering the action will never return
  3. it will be common to see a number of threads timeout trying to get the same lock. This is a normal and desired consequence.
The consequences of not setting a timeout (or setting it to 0) are:
  1. There are no partial failures in the system. But there is a greater possibility that a temporary overload in one part of the system can cause a back up that may take a long time to recover from.
  2. A failing method that perhaps fails because a resource is overloaded will be hit by each thread in turn, no matter whether there is a still a user who cares about getting a response.

Parameters: timeoutMillis the time in ms. Must be a positive number. 0 means wait forever.