|
ehcache | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.sf.ehcache.Cache
Cache is the central class in ehcache. Caches have Element
s and are managed
by the CacheManager
. The Cache performs logical actions. It delegates physical
implementations to its Store
s.
CacheManager
. A Cache thus obtained
is guaranteed to have status Status.STATUS_ALIVE
. This status is checked for any method which
throws IllegalStateException
and the same thrown if it is not alive. This would normally
happen if a call is made after CacheManager.shutdown()
is invoked.
Cache is threadsafe.
Statistics on cache usage are collected and made available through public methods.
Field Summary | |
static java.lang.String |
DEFAULT_CACHE_NAME
A reserved word for cache names. |
static long |
DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
The default interval between runs of the expiry thread. |
static java.lang.String |
NET_SF_EHCACHE_DISABLED
System Property based method of disabling ehcache. |
Constructor Summary | |
Cache(java.lang.String name,
int maxElementsInMemory,
boolean overflowToDisk,
boolean eternal,
long timeToLiveSeconds,
long timeToIdleSeconds)
1.0 Constructor. |
|
Cache(java.lang.String name,
int maxElementsInMemory,
boolean overflowToDisk,
boolean eternal,
long timeToLiveSeconds,
long timeToIdleSeconds,
boolean diskPersistent,
long diskExpiryThreadIntervalSeconds)
1.1 Constructor. |
|
Cache(java.lang.String name,
int maxElementsInMemory,
MemoryStoreEvictionPolicy memoryStoreEvictionPolicy,
boolean overflowToDisk,
java.lang.String diskStorePath,
boolean eternal,
long timeToLiveSeconds,
long timeToIdleSeconds,
boolean diskPersistent,
long diskExpiryThreadIntervalSeconds,
RegisteredEventListeners registeredEventListeners)
1.2 Constructor The ConfigurationFactory and clients can create these. |
Method Summary | |
long |
calculateInMemorySize()
Gets the size of the memory store for this cache Warning: This method can be very expensive to run. |
java.lang.Object |
clone()
Clones a cache. |
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. |
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. |
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. |
int |
getHitCount()
The number of times a requested item was found in the 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. |
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. |
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. |
Status |
getStatus()
Gets the status attribute of the Cache. |
long |
getTimeToIdleSeconds()
Gets timeToIdleSeconds. |
long |
getTimeToLiveSeconds()
Gets timeToLiveSeconds. |
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 |
isOverflowToDisk()
Does the overflow go to disk. |
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. |
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. |
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. |
java.lang.String |
toString()
Returns a String representation of Cache . |
Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final java.lang.String DEFAULT_CACHE_NAME
public static final java.lang.String NET_SF_EHCACHE_DISABLED
java -Dnet.sf.ehcache.disabled=true
in the command line.
public static final long DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS
Constructor Detail |
public Cache(java.lang.String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds)
ConfigurationFactory
and clients can create these.
A client can specify their own settings here and pass the Cache
object
into CacheManager.addCache(java.lang.String)
to specify parameters other than the defaults.
Only the CacheManager can initialise them.
This constructor creates disk stores, if specified, that do not persist between restarts.
The default expiry thread interval of 120 seconds is used. This is the interval between runs
of the expiry thread, where it checks the disk store for expired elements. It is not the
the timeToLiveSeconds.
name
- Cache namemaxElementsInMemory
- Max elements in memoryoverflowToDisk
- Overflow to disk (boolean)eternal
- Whether the elements expiretimeToLiveSeconds
- timeToIdleSeconds
- public Cache(java.lang.String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds)
ConfigurationFactory
and clients can create these.
A client can specify their own settings here and pass the Cache
object
into CacheManager.addCache(java.lang.String)
to specify parameters other than the defaults.
Only the CacheManager can initialise them.
name
- maxElementsInMemory
- overflowToDisk
- eternal
- timeToLiveSeconds
- timeToIdleSeconds
- diskPersistent
- diskExpiryThreadIntervalSeconds
- public Cache(java.lang.String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, java.lang.String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners)
ConfigurationFactory
and clients can create these.
A client can specify their own settings here and pass the Cache
object
into CacheManager.addCache(java.lang.String)
to specify parameters other than the defaults.
Only the CacheManager can initialise them.
name
- maxElementsInMemory
- memoryStoreEvictionPolicy
- one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU.overflowToDisk
- diskStorePath
- eternal
- timeToLiveSeconds
- timeToIdleSeconds
- diskPersistent
- diskExpiryThreadIntervalSeconds
- registeredEventListeners
- a notification service. Optionally null, in which case a new
one with no registered listeners will be created.Method Detail |
public final void put(Element element) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, CacheException
element
- An object. If Serializable it can fully participate in replication and the DiskStore.
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
java.lang.IllegalArgumentException
- if the element is null
CacheException
public final void put(Element element, boolean doNotNotifyCacheReplicators) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, CacheException
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
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
java.lang.IllegalArgumentException
- if the element is null
CacheException
public final void putQuiet(Element element) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, CacheException
getQuiet(java.io.Serializable)
element
- An object. If Serializable it can fully participate in replication and the DiskStore.
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
java.lang.IllegalArgumentException
- if the element is null
CacheException
public final Element get(java.io.Serializable key) throws java.lang.IllegalStateException, CacheException
getQuiet(Object)
to peak into the Element to see its last access time with get
key
- a serializable value
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final Element get(java.lang.Object key) throws java.lang.IllegalStateException, CacheException
getQuiet(Object)
to peak into the Element to see its last access time with get
key
- an Object value
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final Element getQuiet(java.io.Serializable key) throws java.lang.IllegalStateException, CacheException
key
- a serializable value
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final Element getQuiet(java.lang.Object key) throws java.lang.IllegalStateException, CacheException
key
- a serializable value
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
isExpired(net.sf.ehcache.Element)
public final java.util.List getKeys() throws java.lang.IllegalStateException, CacheException
Object
keys
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final java.util.List getKeysWithExpiryCheck() throws java.lang.IllegalStateException, CacheException
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.
Object
keys
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final java.util.List getKeysNoDuplicateCheck() throws java.lang.IllegalStateException
Object
keys
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(java.io.Serializable key) throws java.lang.IllegalStateException
Element
from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
key
-
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(java.lang.Object key) throws java.lang.IllegalStateException
Element
from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
key
-
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(java.io.Serializable key, boolean doNotNotifyCacheReplicators) throws java.lang.IllegalStateException
Element
from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
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
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean remove(java.lang.Object key, boolean doNotNotifyCacheReplicators) throws java.lang.IllegalStateException
Element
from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
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
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean removeQuiet(java.io.Serializable key) throws java.lang.IllegalStateException
Element
from the Cache, without notifying listeners. This also removes it from any
stores it may be in.
key
-
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final boolean removeQuiet(java.lang.Object key) throws java.lang.IllegalStateException
Element
from the Cache, without notifying listeners. This also removes it from any
stores it may be in.
key
-
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final void removeAll() throws java.lang.IllegalStateException, java.io.IOException, CacheException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
java.io.IOException
CacheException
public final void flush() throws java.lang.IllegalStateException, CacheException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final int getSize() throws java.lang.IllegalStateException, CacheException
Element
s in the MemoryStore
plus
the number of Element
s 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.
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
CacheException
public final long calculateInMemorySize() throws java.lang.IllegalStateException, CacheException
java.lang.IllegalStateException
CacheException
public final long getMemoryStoreSize() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final int getDiskStoreSize() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final Status getStatus()
public final int getHitCount() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final int getMemoryStoreHitCount() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final int getDiskStoreHitCount() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final int getMissCountNotFound() throws java.lang.IllegalStateException
getMissCountExpired()
,
or because it was simply not there.
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final int getMissCountExpired() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
public final java.lang.String getName()
public final long getTimeToIdleSeconds()
public final long getTimeToLiveSeconds()
public final boolean isEternal()
public final boolean isOverflowToDisk()
public final int getMaxElementsInMemory()
public final MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy()
MemoryStore
.
This can be one of:
public final java.lang.String toString()
String
representation of Cache
.
public final boolean isExpired(Element element) throws java.lang.IllegalStateException, java.lang.NullPointerException
java.lang.IllegalStateException
- if the cache is not Status.STATUS_ALIVE
java.lang.NullPointerException
- if the element is nullpublic final java.lang.Object clone() throws java.lang.CloneNotSupportedException
LruMemoryStore
or DiskStore
has been created.
A new, empty, RegisteredEventListeners is created on clone.
Cache
java.lang.CloneNotSupportedException
public final boolean isDiskPersistent()
public final long getDiskExpiryThreadIntervalSeconds()
public final RegisteredEventListeners getCacheEventNotificationService()
public final boolean isElementInMemory(java.io.Serializable key)
public final boolean isElementInMemory(java.lang.Object key)
public final boolean isElementOnDisk(java.io.Serializable key)
public final boolean isElementOnDisk(java.lang.Object key)
public final java.lang.String getGuid()
public final CacheManager getCacheManager()
|
ehcache | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |