net.sf.ehcache.constructs.blocking
public class BlockingCache extends Object implements Ehcache
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 $
Field Summary | |
---|---|
protected Ehcache | cache
The backing Cache |
protected Mutex[] | locks
Based on the lock striping concept from Brian Goetz. |
static int | LOCK_NUMBER
The default number of locks to use. |
protected int | timeoutMillis
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 | |
---|---|
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. |
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(Object key)
Looks up an entry. |
Element | get(Serializable key)
Gets an element from the cache. |
BootstrapCacheLoader | getBootstrapCacheLoader()
Accessor for the BootstrapCacheLoader associated with this cache. |
protected Ehcache | getCache()
Retrieve the EHCache backing cache |
RegisteredEventListeners | getCacheEventNotificationService()
Use this to access the service in order to register and unregister listeners
|
CacheManager | getCacheManager()
Gets the CacheManager managing this cache. |
long | getDiskExpiryThreadIntervalSeconds() |
int | getDiskStoreHitCount()
Number of times a requested item was found in the Disk Store. |
int | getDiskStoreSize()
Returns the number of elements in the disk store.
|
String | getGuid()
The GUID for this cache instance can be used to determine whether two cache instance references
are pointing to the same cache.
|
int | getHitCount()
The number of times a requested item was found in the cache.
|
List | getKeys()
Returns the keys for this cache.
|
List | getKeysNoDuplicateCheck()
Returns a list of all elements in the cache, whether or not they are expired.
|
List | getKeysWithExpiryCheck()
Returns a list of all elements in the cache. |
protected Mutex | getLockForKey(Object key)
Gets the Mutex to use for a given key. |
int | getMaxElementsInMemory()
Gets the maximum number of elements to hold in memory. |
MemoryStoreEvictionPolicy | getMemoryStoreEvictionPolicy()
The policy used to evict elements from the MemoryStore.
|
int | getMemoryStoreHitCount()
Number of times a requested item was found in the Memory Store.
|
long | getMemoryStoreSize()
Returns the number of elements in the memory store.
|
int | getMissCountExpired()
Number of times a requested element was found but was expired. |
int | getMissCountNotFound()
Number of times a requested element was not found in the cache. |
String | getName()
Returns this cache's name |
Element | getQuiet(Serializable key)
Gets an element from the cache, without updating Element statistics. |
Element | getQuiet(Object 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.
|
int | getTimeoutMillis()
Gets the time to wait to acquire a lock.
|
long | getTimeToIdleSeconds()
Gets timeToIdleSeconds. |
long | getTimeToLiveSeconds()
Gets timeToLiveSeconds. |
void | initialise()
Newly created caches do not have a MemoryStore or a DiskStore.
|
boolean | isDiskPersistent() |
boolean | isElementInMemory(Serializable key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
|
boolean | isElementInMemory(Object key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
|
boolean | isElementOnDisk(Serializable key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
|
boolean | isElementOnDisk(Object 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(Object key)
An inexpensive check to see if the key exists in the cache.
|
boolean | isOverflowToDisk()
Does the overflow go to disk. |
boolean | isValueInCache(Object value)
An extremely expensive check to see if the value exists in the cache.
|
String | liveness()
Synchronized version of getName to test liveness of the object lock.
|
void | put(Element element)
Adds an entry and unlocks it |
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. |
boolean | remove(Serializable key)
Removes an Element from the Cache. |
boolean | remove(Object key)
Removes an Element from the Cache. |
boolean | remove(Serializable key, boolean doNotNotifyCacheReplicators)
Removes an Element from the Cache. |
boolean | remove(Object 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(Serializable key)
Removes an Element from the Cache, without notifying listeners. |
boolean | removeQuiet(Object key)
Removes an Element from the Cache, without notifying listeners. |
void | setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
Sets the bootstrap cache loader.
|
void | setCacheManager(CacheManager cacheManager)
Sets the CacheManager
|
void | setDiskStorePath(String diskStorePath)
DiskStore paths can conflict between CacheManager instances. |
void | setName(String name)
Sets the cache name which will name.
|
void | setStatisticsAccuracy(int statisticsAccuracy)
Sets the statistics accuracy.
|
void | setTimeoutMillis(int timeoutMillis)
Sets the time to wait to acquire a lock. |
Parameters: cache a backing ehcache.
Throws: CacheException
Since: 1.2
Returns: the approximate size of the memory store in bytes
Throws: IllegalStateException
Returns: an object of type Cache
Throws: CloneNotSupportedException
Throws: IllegalStateException if the cache is not STATUS_ALIVE
Throws: IllegalStateException if the cache is not STATUS_ALIVE
Throws: LockTimeoutException if timeout millis is non zero and this method has been unable to acquire a lock in that time
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
Returns: the RegisteredEventListeners instance for this cache.
Returns: the manager or null if there is none
Returns: the interval between runs of the expiry thread, where it checks the disk store for expired elements. It is not the the timeToLiveSeconds.
Returns: the number of elements in the disk store.
Throws: IllegalStateException if the cache is not STATUS_ALIVE
Returns: the globally unique identifier for this cache instance. This is guaranteed to be unique.
Since: 1.2
Returns: the number of times a requested item was found in the cache
Returns: The keys of this cache. This is not a live set, so it will not track changes to the key set.
Returns: a list of Object keys
Throws: IllegalStateException if the cache is not STATUS_ALIVE
Returns: a list of Object keys
Throws: IllegalStateException if the cache is not STATUS_ALIVE
Parameters: key the key
Returns: one of a limited number of Mutexes.
Since: 1.2
Returns: Number of times a requested item was found in the Memory Store.
Returns: the number of elements in the memory store
Throws: IllegalStateException if the cache is not STATUS_ALIVE
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
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
Returns: The size value
Throws: IllegalStateException if the cache is not STATUS_ALIVE
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
Returns: one of STATISTICS_ACCURACY_BEST_EFFORT, STATISTICS_ACCURACY_GUARANTEED, STATISTICS_ACCURACY_NONE
Returns: The status value from the Status enum class
Returns: the time in ms.
Returns: true if the cache overflows to disk and the disk is persistent between restarts
Returns: true if an element matching the key is found in memory
Returns: true if an element matching the key is found in memory
Since: 1.2
Returns: true if an element matching the key is found in the diskStore
Returns: true if an element matching the key is found in the diskStore
Since: 1.2
Returns: true if it has expired
Throws: IllegalStateException if the cache is not STATUS_ALIVE NullPointerException if the element is null
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.
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.
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
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
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
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
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
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
Throws: IllegalStateException if the cache is not STATUS_ALIVE
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
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
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
Parameters: bootstrapCacheLoader the loader to be used
Throws: net.sf.ehcache.CacheException if this method is called after the cache is initialized
Parameters: cacheManager
Parameters: diskStorePath the new path to be used.
Throws: net.sf.ehcache.CacheException if this method is called after the cache is initialized
Parameters: name the name of the cache. Should not be null.
Parameters: statisticsAccuracy one of STATISTICS_ACCURACY_BEST_EFFORT, STATISTICS_ACCURACY_GUARANTEED, STATISTICS_ACCURACY_NONE
Parameters: timeoutMillis the time in ms. Must be a positive number. 0 means wait forever.