| java.lang.Object net.sf.ehcache.Cache
Cache | public class Cache implements Ehcache(Code) | | 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
net.sf.ehcache.store.Store s.
A reference to a Cache can be obtained through the
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 the
Cache.getStatistics() methods.
Various decorators are available for Cache, such as BlockingCache, SelfPopulatingCache and the dynamic proxy
ExceptionHandlingDynamicCacheProxy. See each class for details.
author: Greg Luck version: $Id: Cache.java 581 2008-02-20 10:09:03Z gregluck $ |
Inner Class :class KeyedFuture | |
Constructor Summary | |
public | Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds) 1.0 Constructor.
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache 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. | public | Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds) 1.1 Constructor.
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. | public | Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners) 1.2 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. | public | Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader) 1.2.1 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. | public | Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk) 1.2.4 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. | public | Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk, int diskSpoolBufferSizeMB) 1.2.4 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. |
Method Summary | |
Future | asynchronousLoad(Object key, CacheLoader specificLoader, Object argument) Does the asynchronous loading.
Parameters: specificLoader - a specific loader to use. | Future | asynchronousLoadAll(Collection keys, Object argument) Does the asynchronous loading. | public void | bootstrap() Bootstrap command. | final public synchronized long | calculateInMemorySize() Gets the size of the memory store for this cache. | public synchronized void | clearStatistics() Resets statistics counters back to 0. | final public Object | clone() Clones a cache. | protected Store | createDiskStore() Creates a disk store. | public synchronized void | dispose() Starts an orderly shutdown of the Cache. | public boolean | equals(Object object) An equals method which follows the contract of
Object.equals(Object)
An Cache is equal to another one if it implements Ehcache and has the same GUID.
Parameters: object - the reference object with which to compare. | public void | evictExpiredElements() Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted. | final public synchronized void | flush() Flushes all cache items from memory to the disk store, and from the DiskStore to disk. | final public Element | get(Serializable key) Gets an element from the cache. | final public Element | get(Object key) Gets an element from the cache. | public Map | getAllWithLoader(Collection keys, Object loaderArgument) Warning: This method is related to the JSR107 specification, which is in draft. | public float | getAverageGetTime() The average get time in ms. | public BootstrapCacheLoader | getBootstrapCacheLoader() Accessor for the BootstrapCacheLoader associated with this cache. | public CacheConfiguration | getCacheConfiguration() Gets the cache configuration this cache was created with. | final public RegisteredEventListeners | getCacheEventNotificationService() | public CacheExceptionHandler | getCacheExceptionHandler() Gets the ExceptionHandler on this Cache, or null if there isn't one. | public CacheLoader | getCacheLoader() | final public CacheManager | getCacheManager() Gets the CacheManager managing this cache. | final public long | getDiskExpiryThreadIntervalSeconds() the interval between runsof the expiry thread, where it checks the disk store for expired elements. | final Store | getDiskStore() Gets the internal DiskStore. | final public int | getDiskStoreHitCount() Number of times a requested item was found in the Disk Store.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. | final public int | getDiskStoreSize() Returns the number of elements in the disk store. | ThreadPoolExecutor | getExecutorService() Gets the executor service. | final 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.
the globally unique identifier for this cache instance. | final public int | getHitCount() The number of times a requested item was found in the cache.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. | final public synchronized List | getKeys() Returns a list of all element keys in the cache, whether or not they are expired.
The returned keys are unique and can be considered a set.
The List returned is not live. | final public synchronized 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. | final public List | getKeysWithExpiryCheck() Returns a list of all element keys in the cache. | final public int | getMaxElementsInMemory() Gets the maximum number of elements to hold in memory. | public int | getMaxElementsOnDisk() | final MemoryStore | getMemoryStore() Gets the internal MemoryStore. | final public MemoryStoreEvictionPolicy | getMemoryStoreEvictionPolicy() The policy used to evict elements from the
net.sf.ehcache.store.MemoryStore . | final public int | getMemoryStoreHitCount() Number of times a requested item was found in the Memory Store.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. | final public long | getMemoryStoreSize() Returns the number of elements in the memory store. | final public int | getMissCountExpired() Number of times a requested element was found but was expired.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. | final public int | getMissCountNotFound() Number of times a requested element was not found in the cache. | final public String | getName() Gets the cache name. | final public Element | getQuiet(Serializable key) Gets an element from the cache, without updating Element statistics. | final public Element | getQuiet(Object key) Gets an element from the cache, without updating Element statistics. | final public synchronized int | getSize() Gets the size of the cache. | public Statistics | getStatistics()
Note, the
Cache.getSize method will have the same value as the size reported by Statistics
for the statistics accuracy of
Statistics.STATISTICS_ACCURACY_BEST_EFFORT . | public int | getStatisticsAccuracy() Accurately measuring statistics can be expensive. | final public Status | getStatus() Gets the status attribute of the Cache. | final public long | getTimeToIdleSeconds() Gets timeToIdleSeconds. | final public long | getTimeToLiveSeconds() Gets timeToLiveSeconds. | public Element | getWithLoader(Object key, CacheLoader loader, Object loaderArgument) Warning: This method is related to the JSR107 specification, which is in draft. | public int | hashCode() Returns a hash code value for the object. | public void | initialise() Newly created caches do not have a
net.sf.ehcache.store.MemoryStore or a
net.sf.ehcache.store.DiskStore . | final public boolean | isDiskPersistent() | final public boolean | isElementInMemory(Serializable key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval. | final public boolean | isElementInMemory(Object key) Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval. | final public boolean | isElementOnDisk(Serializable key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval. | final public boolean | isElementOnDisk(Object key) Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval. | final public boolean | isEternal() Are elements eternal. | final public boolean | isExpired(Element element) Checks whether this cache element has expired. | public boolean | isKeyInCache(Object key) An inexpensive check to see if the key exists in the cache.
This method is not synchronized. | final public boolean | isOverflowToDisk() Does the overflow go to disk. | public boolean | isValueInCache(Object value) An extremely expensive check to see if the value exists in the cache. | public void | load(Object key) Warning: This method is related to the JSR107 specification, which is in draft. | public void | loadAll(Collection keys, Object argument) Warning: This method is related to the JSR107 specification, which is in draft. | final public void | put(Element element) Put an element in the cache.
Resets the access statistics on the element, which would be the case if it has previously been
gotten from a cache, and is now being put back.
Also notifies the CacheEventListener that:
- 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
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: element - An object. | final 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:
- 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
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: element - An object. | final public void | putQuiet(Element element) Put an element in the cache, without updating statistics, or updating listeners. | public void | registerCacheExtension(CacheExtension cacheExtension) Register a
CacheExtension with the cache. | final public boolean | remove(Serializable key) Removes an
Element from the Cache. | final public boolean | remove(Object key) Removes an
Element from the Cache. | final public boolean | remove(Serializable key, boolean doNotNotifyCacheReplicators) Removes an
Element from the Cache. | final public boolean | remove(Object key, boolean doNotNotifyCacheReplicators) Removes an
Element from the Cache. | public void | removeAll() Removes all cached items. | public void | removeAll(boolean doNotNotifyCacheReplicators) Removes all cached items. | final public boolean | removeQuiet(Serializable key) Removes an
Element from the Cache, without notifying listeners. | final public boolean | removeQuiet(Object key) Removes an
Element from the Cache, without notifying listeners. | public void | setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) Sets the bootstrap cache loader. | public void | setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler) Sets an ExceptionHandler on the Cache. | public void | setCacheLoader(CacheLoader cacheLoader) Setter for the CacheLoader. | public void | setCacheManager(CacheManager cacheManager) For use by CacheManager. | public void | setDiskStorePath(String diskStorePath) DiskStore paths can conflict between CacheManager instances. | final public void | setName(String name) Sets the cache name which will name.
Parameters: name - the name of the cache. | public void | setStatisticsAccuracy(int statisticsAccuracy) Sets the statistics accuracy. | final public String | toString() Returns a
String representation of
Cache . | public void | unregisterCacheExtension(CacheExtension cacheExtension) Unregister a
CacheExtension with the cache. |
DEFAULT_CACHE_NAME | final public static String DEFAULT_CACHE_NAME(Code) | | A reserved word for cache names. It denotes a default configuration
which is applied to caches created without configuration.
|
DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS | final public static long DEFAULT_EXPIRY_THREAD_INTERVAL_SECONDS(Code) | | The default interval between runs of the expiry thread.
|
NET_SF_EHCACHE_DISABLED | final public static String NET_SF_EHCACHE_DISABLED(Code) | | System Property based method of disabling ehcache. If disabled no elements will be added to a cache.
Set the property "net.sf.ehcache.disabled=true" to disable ehcache.
This can easily be done using java -Dnet.sf.ehcache.disabled=true in the command line.
|
Cache | public Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds)(Code) | | 1.0 Constructor.
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
This constructor creates disk stores, if specified, that do not persist between restarts.
The default expiry thread interval of 120 seconds is used. This is the interval between runs
of the expiry thread, where it checks the disk store for expired elements. It is not the
the timeToLiveSeconds.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: overflowToDisk - whether to use the disk store Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date since: 1.0 |
Cache | public Cache(String name, int maxElementsInMemory, boolean overflowToDisk, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds)(Code) | | 1.1 Constructor.
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: overflowToDisk - whether to use the disk store Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date Parameters: diskPersistent - whether to persist the cache to disk between JVM restarts Parameters: diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended since: 1.1 |
Cache | public Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners)(Code) | | 1.2 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU. Parameters: overflowToDisk - whether to use the disk store Parameters: diskStorePath - this parameter is ignored. CacheManager sets it using setter injection. Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date Parameters: diskPersistent - whether to persist the cache to disk between JVM restarts Parameters: diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended Parameters: registeredEventListeners - a notification service. Optionally null, in which case a newone with no registered listeners will be created. since: 1.2 |
Cache | public Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader)(Code) | | 1.2.1 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU. Parameters: overflowToDisk - whether to use the disk store Parameters: diskStorePath - this parameter is ignored. CacheManager sets it using setter injection. Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date Parameters: diskPersistent - whether to persist the cache to disk between JVM restarts Parameters: diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended Parameters: registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created. Parameters: bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required. since: 1.2.1 |
Cache | public Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk)(Code) | | 1.2.4 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU. Parameters: overflowToDisk - whether to use the disk store Parameters: diskStorePath - this parameter is ignored. CacheManager sets it using setter injection. Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date Parameters: diskPersistent - whether to persist the cache to disk between JVM restarts Parameters: diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended Parameters: registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created. Parameters: bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required. since: 1.2.4 |
Cache | public Cache(String name, int maxElementsInMemory, MemoryStoreEvictionPolicy memoryStoreEvictionPolicy, boolean overflowToDisk, String diskStorePath, boolean eternal, long timeToLiveSeconds, long timeToIdleSeconds, boolean diskPersistent, long diskExpiryThreadIntervalSeconds, RegisteredEventListeners registeredEventListeners, BootstrapCacheLoader bootstrapCacheLoader, int maxElementsOnDisk, int diskSpoolBufferSizeMB)(Code) | | 1.2.4 Constructor
The
net.sf.ehcache.config.ConfigurationFactory and clients can create these.
A client can specify their own settings here and pass the
Cache object
into
CacheManager.addCache to specify parameters other than the defaults.
Only the CacheManager can initialise them.
Parameters: name - the name of the cache. Note that "default" is a reserved name for the defaultCache. Parameters: maxElementsInMemory - the maximum number of elements in memory, before they are evicted Parameters: memoryStoreEvictionPolicy - one of LRU, LFU and FIFO. Optionally null, in which case it will be set to LRU. Parameters: overflowToDisk - whether to use the disk store Parameters: diskStorePath - this parameter is ignored. CacheManager sets it using setter injection. Parameters: eternal - whether the elements in the cache are eternal, i.e. never expire Parameters: timeToLiveSeconds - the default amount of time to live for an element from its creation date Parameters: timeToIdleSeconds - the default amount of time to live for an element from its last accessed or modified date Parameters: diskPersistent - whether to persist the cache to disk between JVM restarts Parameters: diskExpiryThreadIntervalSeconds - how often to run the disk store expiry thread. A large number of 120 seconds plus is recommended Parameters: registeredEventListeners - a notification service. Optionally null, in which case a new one with no registered listeners will be created. Parameters: bootstrapCacheLoader - the BootstrapCacheLoader to use to populate the cache when it is first initialised. Null if none is required. Parameters: diskSpoolBufferSizeMB - the amount of memory to allocate the write buffer for puts to the DiskStore. since: 1.2.4 |
asynchronousLoad | Future asynchronousLoad(Object key, CacheLoader specificLoader, Object argument)(Code) | | Does the asynchronous loading.
Parameters: specificLoader - a specific loader to use. If null the default loader is used. a Future which can be used to monitor execution |
asynchronousLoadAll | Future asynchronousLoadAll(Collection keys, Object argument)(Code) | | Does the asynchronous loading.
Parameters: argument - the loader argument a Future which can be used to monitor execution |
bootstrap | public void bootstrap()(Code) | | 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 | final public synchronized long calculateInMemorySize() throws IllegalStateException, CacheException(Code) | | Gets the size of the memory store for this cache. This method relies on calculating
Serialized sizes. If the Element values are not Serializable they will show as zero.
Warning: This method can be very expensive to run. Allow approximately 1 second
per 1MB of entries. Running this method could create liveness problems
because the object lock is held for a long period
the approximate size of the memory store in bytes throws: IllegalStateException - |
createDiskStore | protected Store createDiskStore()(Code) | | Creates a disk store.
|
dispose | public synchronized void dispose() throws IllegalStateException(Code) | | Starts an orderly shutdown of the Cache. Steps are:
- Completes any outstanding CacheLoader loads.
- Disposes any cache extensions.
- Disposes any cache event listeners. The listeners normally complete, so for example distributed caching operations will complete.
- Flushes all cache items from memory to the disk store, if any
- changes status to shutdown, so that any cache operations after this point throw IllegalStateException
This method should be invoked only by CacheManager, as a cache's lifecycle is bound into that of it's cache manager.
throws: IllegalStateException - if the cache is already Status.STATUS_SHUTDOWN |
equals | public boolean equals(Object object)(Code) | | An equals method which follows the contract of
Object.equals(Object)
An Cache is equal to another one if it implements Ehcache and has the same GUID.
Parameters: object - the reference object with which to compare. true if this object is the same as the objargument; false otherwise. See Also: Cache.hashCode() See Also: java.util.Hashtable |
evictExpiredElements | public void evictExpiredElements()(Code) | | Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
|
getAllWithLoader | public Map getAllWithLoader(Collection keys, Object loaderArgument) throws CacheException(Code) | | 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
net.sf.ehcache.constructs.blocking.SelfPopulatingCache Parameters: keys - a collection of keys to be returned/loaded Parameters: loaderArgument - an argument to pass to the CacheLoader. a Map populated from the Cache. If there are no elements, an empty Map is returned. throws: CacheException - |
getAverageGetTime | public float getAverageGetTime()(Code) | | The average get time in ms.
|
getBootstrapCacheLoader | public BootstrapCacheLoader getBootstrapCacheLoader()(Code) | | Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
|
getCacheConfiguration | public CacheConfiguration getCacheConfiguration()(Code) | | Gets the cache configuration this cache was created with.
Things like listeners that are added dynamically are excluded.
|
getCacheEventNotificationService | final public RegisteredEventListeners getCacheEventNotificationService()(Code) | | Use this to access the service in order to register and unregister listeners
the RegisteredEventListeners instance for this cache. |
getCacheLoader | public CacheLoader getCacheLoader()(Code) | | Gets the CacheLoader registered in this cache
the loader, or null if there is none |
getCacheManager | final public CacheManager getCacheManager()(Code) | | Gets the CacheManager managing this cache. For a newly created cache this will be null until
it has been added to a CacheManager.
the manager or null if there is none |
getDiskExpiryThreadIntervalSeconds | final public long getDiskExpiryThreadIntervalSeconds()(Code) | | the interval between runsof the expiry thread, where it checks the disk store for expired elements. It is not thethe timeToLiveSeconds. |
getDiskStoreHitCount | final public int getDiskStoreHitCount()(Code) | | Number of times a requested item was found in the Disk Store.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. Use
net.sf.ehcache.Statistics which contains this statistic.
net.sf.ehcache.Statistics |
getExecutorService | ThreadPoolExecutor getExecutorService()(Code) | | Gets the executor service. This is not publically accessible. |
getGuid | final public String getGuid()(Code) | | The GUID for this cache instance can be used to determine whether two cache instance references
are pointing to the same cache.
the globally unique identifier for this cache instance. This is guaranteed to be unique. since: 1.2 |
getHitCount | final public int getHitCount()(Code) | | The number of times a requested item was found in the cache.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. Use
net.sf.ehcache.Statistics which contains this statistic.
the number of times a requested item was found in the cachenet.sf.ehcache.Statistics |
getKeys | final public synchronized List getKeys() throws IllegalStateException, CacheException(Code) | | Returns a list of all element keys in the cache, whether or not they are expired.
The returned keys are unique and can be considered a set.
The List returned is not live. It is a copy.
The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
for each 1000 entries.
a list of Object keys throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
getKeysNoDuplicateCheck | final public synchronized List getKeysNoDuplicateCheck() throws IllegalStateException(Code) | | 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
a list of Object keys throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
getKeysWithExpiryCheck | final public List getKeysWithExpiryCheck() throws IllegalStateException, CacheException(Code) | | Returns a list of all element keys in the cache. Only keys of non-expired
elements are returned.
The returned keys are unique and can be considered a set.
The List returned is not live. It is a copy.
The time taken is O(n), where n is the number of elements in the cache. On
a 1.8Ghz P4, the time taken is approximately 200ms per 1000 entries. This method
is not syncrhonized, because it relies on a non-live list returned from
Cache.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.
a list of Object keys throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
getMaxElementsInMemory | final public int getMaxElementsInMemory()(Code) | | Gets the maximum number of elements to hold in memory.
|
getMaxElementsOnDisk | public int getMaxElementsOnDisk()(Code) | | Gets the maximum number of elements to hold on Disk
|
getMemoryStoreEvictionPolicy | final public MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy()(Code) | | The policy used to evict elements from the
net.sf.ehcache.store.MemoryStore .
This can be one of:
- LRU - least recently used
- LFU - least frequently used
- FIFO - first in first out, the oldest element by creation time
The default value is LRU
since: 1.2 |
getMemoryStoreHitCount | final public int getMemoryStoreHitCount()(Code) | | Number of times a requested item was found in the Memory Store.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. Use
net.sf.ehcache.Statistics which contains this statistic.
Number of times a requested item was found in the Memory Store.net.sf.ehcache.Statistics |
getMissCountExpired | final public int getMissCountExpired()(Code) | | Number of times a requested element was found but was expired.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. Use
net.sf.ehcache.Statistics which contains this statistic.
net.sf.ehcache.Statistics |
getMissCountNotFound | final public int getMissCountNotFound()(Code) | | Number of times a requested element was not found in the cache. This
may be because it expired, in which case this will also be recorded in
Cache.getMissCountExpired ,
or because it was simply not there.
The internal representation of this statistic has been changed to a long
to cater for real world situations when an int is not sufficient to hold it.
If the statistic is larger than Integer.MAX_VALUE a nonsensical value
will be returned. Use
net.sf.ehcache.Statistics which contains this statistic.
net.sf.ehcache.Statistics |
getName | final public String getName()(Code) | | Gets the cache name.
|
getSize | final public synchronized int getSize() throws IllegalStateException, CacheException(Code) | | Gets the size of the cache. This is a subtle concept. See below.
The size is the number of
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
Cache.getKeysWithExpiryCheck() .size(),
although see that method for the approximate time that would take.
To get a very fast result, use
Cache.getKeysNoDuplicateCheck() .size(). If the disk store
is being used, there will be some duplicates.
The size value throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
getStatus | final public Status getStatus()(Code) | | Gets the status attribute of the Cache.
The status value from the Status enum class |
getTimeToIdleSeconds | final public long getTimeToIdleSeconds()(Code) | | Gets timeToIdleSeconds.
|
getTimeToLiveSeconds | final public long getTimeToLiveSeconds()(Code) | | Gets timeToLiveSeconds.
|
getWithLoader | public Element getWithLoader(Object key, CacheLoader loader, Object loaderArgument) throws CacheException(Code) | | 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. Parameters: loader - the override loader to use. If null, the cache's default loader will be used Parameters: loaderArgument - an argument to pass to the CacheLoader. an element if it existed or could be loaded, otherwise null throws: CacheException - |
hashCode | public int hashCode()(Code) | | Returns a hash code value for the object. This method is
supported for the benefit of hashtables such as those provided by
java.util.Hashtable .
The general contract of hashCode is:
- Whenever it is invoked on the same object more than once during
an execution of a Java application, the hashCode method
must consistently return the same integer, provided no information
used in equals comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
- If two objects are equal according to the equals(Object)
method, then calling the
hashCode method on each of
the two objects must produce the same integer result.
- It is not required that if two objects are unequal
according to the
Object.equals(Object) method, then calling the hashCode method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hashtables.
As much as is reasonably practical, the hashCode method defined by
class Object does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
JavaTM programming language.)
This implementation use the GUID of the cache.
a hash code value for this object. See Also: Object.equals(Object) See Also: java.util.Hashtable |
isDiskPersistent | final public boolean isDiskPersistent()(Code) | | true if the cache overflows to disk and the disk is persistent between restarts |
isElementInMemory | final public boolean isElementInMemory(Serializable key)(Code) | | Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
true if an element matching the key is found in memory |
isElementInMemory | final public boolean isElementInMemory(Object key)(Code) | | Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
true if an element matching the key is found in memory since: 1.2 |
isElementOnDisk | final public boolean isElementOnDisk(Serializable key)(Code) | | Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
true if an element matching the key is found in the diskStore |
isElementOnDisk | final public boolean isElementOnDisk(Object key)(Code) | | Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
true if an element matching the key is found in the diskStore since: 1.2 |
isEternal | final public boolean isEternal()(Code) | | Are elements eternal.
|
isKeyInCache | public boolean isKeyInCache(Object key)(Code) | | An inexpensive check to see if the key exists in the cache.
This method is not synchronized. It is possible that an element may exist in the cache aned be removed
before the check gets to it, or vice versa.
Parameters: key - the key to check. true if an Element matching the key is found in the cache. No assertions are made about the state of the Element. |
isOverflowToDisk | final public boolean isOverflowToDisk()(Code) | | Does the overflow go to disk.
|
isValueInCache | public boolean isValueInCache(Object value)(Code) | | An extremely expensive check to see if the value exists in the cache. This implementation is O(n). Ehcache
is not designed for efficient access in this manner.
This method is not synchronized. It is possible that an element may exist in the cache aned be removed
before the check gets to it, or vice versa. Because it is slow to execute the probability of that this will
have happened.
Parameters: value - to check for true if an Element matching the key is found in the cache. No assertions are made about the state of the Element. |
load | public void load(Object key) throws CacheException(Code) | | 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
net.sf.ehcache.constructs.blocking.SelfPopulatingCache Parameters: key - key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it. throws: CacheException - |
loadAll | public void loadAll(Collection keys, Object argument) throws CacheException(Code) | | 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
net.sf.ehcache.constructs.blocking.SelfPopulatingCache |
put | final public void put(Element element) throws IllegalArgumentException, IllegalStateException, CacheException(Code) | | 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
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: element - An object. If Serializable it can fully participate in replication and the DiskStore. throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE throws: IllegalArgumentException - if the element is null throws: CacheException - |
put | final public void put(Element element, boolean doNotNotifyCacheReplicators) throws IllegalArgumentException, IllegalStateException, CacheException(Code) | | 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
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: element - An object. If Serializable it can fully participate in replication and the DiskStore. Parameters: doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate afurther notification to doNotNotifyCacheReplicators cache peers throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE throws: IllegalArgumentException - if the element is null |
registerCacheExtension | public void registerCacheExtension(CacheExtension cacheExtension)(Code) | | Register a
CacheExtension with the cache. It will then be tied into the cache lifecycle.
If the CacheExtension is not initialised, initialise it.
|
remove | final public boolean remove(Serializable key) throws IllegalStateException(Code) | | 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.
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: key - the element key to operate on true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
remove | final public boolean remove(Object key) throws IllegalStateException(Code) | | Removes an
Element from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: key - the element key to operate on true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE since: 1.2 |
remove | final public boolean remove(Serializable key, boolean doNotNotifyCacheReplicators) throws IllegalStateException(Code) | | Removes an
Element from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: key - the element key to operate on Parameters: doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate afurther notification to doNotNotifyCacheReplicators cache peers true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
remove | final public boolean remove(Object key, boolean doNotNotifyCacheReplicators) throws IllegalStateException(Code) | | Removes an
Element from the Cache. This also removes it from any
stores it may be in.
Also notifies the CacheEventListener after the element was removed, but only if an Element
with the key actually existed.
Synchronization is handled within the method.
Parameters: key - the element key to operate on Parameters: doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate afurther notification to doNotNotifyCacheReplicators cache peers true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
removeAll | public void removeAll(boolean doNotNotifyCacheReplicators) throws IllegalStateException, CacheException(Code) | | Removes all cached items.
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
removeQuiet | final public boolean removeQuiet(Serializable key) throws IllegalStateException(Code) | | Removes an
Element from the Cache, without notifying listeners. This also removes it from any
stores it may be in.
Synchronization is handled within the method.
Parameters: key - the element key to operate on true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE |
removeQuiet | final public boolean removeQuiet(Object key) throws IllegalStateException(Code) | | Removes an
Element from the Cache, without notifying listeners. This also removes it from any
stores it may be in.
Synchronization is handled within the method.
Caches which use synchronous replication can throw RemoteCacheException here if the replication to the cluster fails.
This exception should be caught in those cirucmstances.
Parameters: key - the element key to operate on true if the element was removed, false if it was not found in the cache throws: IllegalStateException - if the cache is not Status.STATUS_ALIVE since: 1.2 |
setBootstrapCacheLoader | public void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) throws CacheException(Code) | | Sets the bootstrap cache loader.
Parameters: bootstrapCacheLoader - the loader to be used throws: CacheException - if this method is called after the cache is initialized |
setCacheLoader | public void setCacheLoader(CacheLoader cacheLoader)(Code) | | Setter for the CacheLoader. Changing the CacheLoader takes immediate effect.
Parameters: cacheLoader - the loader to dynamically load new cache entries |
setCacheManager | public void setCacheManager(CacheManager cacheManager)(Code) | | For use by CacheManager.
Parameters: cacheManager - the CacheManager for this cache to use. |
setDiskStorePath | public void setDiskStorePath(String diskStorePath) throws CacheException(Code) | | DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
Parameters: diskStorePath - the new path to be used. throws: CacheException - if this method is called after the cache is initialized |
setName | final public void setName(String name) throws IllegalArgumentException(Code) | | Sets the cache name which will name.
Parameters: name - the name of the cache. Should not be null. Should also not contain any '/' characters, as these interferewith distribution throws: IllegalArgumentException - if an illegal name is used. |
unregisterCacheExtension | public void unregisterCacheExtension(CacheExtension cacheExtension)(Code) | | Unregister a
CacheExtension with the cache. It will then be detached from the cache lifecycle.
|
|
|