ehcache

net.sf.ehcache
Interface Ehcache

All Superinterfaces:
Cloneable
All Known Subinterfaces:
InternalEhcache
All Known Implementing Classes:
BlockingCache, Cache, ClassLoaderAwareCache, EhcacheDecoratorAdapter, InternalClassLoaderAwareCache, SelfPopulatingCache, UpdatingSelfPopulatingCache

public interface Ehcache
extends Cloneable

An interface for Ehcache.

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

A reference to an EhCache can be obtained through the CacheManager. An Ehcache thus obtained is guaranteed to have status Status.STATUS_ALIVE. This status is checked for any method which throws IllegalStateException and the same thrown if it is not alive. This would normally happen if a call is made after CacheManager.shutdown() is invoked.

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

Version:
$Id: Ehcache.java 5443 2012-04-03 13:27:26Z alexsnaps $
Author:
Greg Luck

Method Summary
 void acquireReadLockOnKey(Object key)
          Acquires the proper read lock for a given cache key
 void acquireWriteLockOnKey(Object key)
          Acquires the proper write lock for a given cache key
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a PropertyChangeListener.
 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.

 long calculateOffHeapSize()
          Gets the size of the off-heap store for this cache
 long calculateOnDiskSize()
          Gets the size of the on-disk store for this cache
 void clearStatistics()
          Resets statistics counters back to 0.
 Object clone()
          Clones a cache.
 Query createQuery()
          Create a new query builder for this cache
 void disableDynamicFeatures()
          Disables dynamic configuration and disable/enable for this 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)
          Gets an element from the cache.
 Element get(Serializable key)
          Gets an element from the cache.
 Map<Object,Element> getAll(Collection<?> keys)
          Gets all the elements from the cache for the keys provided.
 Map getAllWithLoader(Collection keys, Object loaderArgument)
          The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
 float getAverageGetTime()
          The average get time in ms.
 long getAverageSearchTime()
          Get the average search execution time (in millis) for searches that have completed in the last sample period
 BootstrapCacheLoader getBootstrapCacheLoader()
          Accessor for the BootstrapCacheLoader associated with this cache.
 CacheConfiguration getCacheConfiguration()
          Gets the cache configuration this cache was created with.
 RegisteredEventListeners getCacheEventNotificationService()
          Use this to access the service in order to register and unregister listeners
 CacheExceptionHandler getCacheExceptionHandler()
          Sets an ExceptionHandler on the Cache.
 CacheManager getCacheManager()
          Gets the CacheManager managing this cache.
 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.
 Object getInternalContext()
          This should not be used return some internal context (generally will be null)
 List getKeys()
          Returns a list of all elements in the cache, whether or not they are expired.
 List getKeysNoDuplicateCheck()
          Deprecated. versions since 2.1 do not return duplicates
 List getKeysWithExpiryCheck()
          Returns a list of all elements in the cache.
 LiveCacheStatistics getLiveCacheStatistics()
          This is different from getStatistics() in the way that values returned from LiveCacheStatistics will reflect the current state of the cache (and not a snapshot of the cache when the api's were called like getStatistics())
 long getMemoryStoreSize()
          Returns the number of elements in the memory store.
 String getName()
          Gets the cache name.
 long getOffHeapStoreSize()
          Returns the number of elements in the off-heap store.
 Element getQuiet(Object key)
          Gets an element from the cache, without updating Element statistics.
 Element getQuiet(Serializable key)
          Gets an element from the cache, without updating Element statistics.
 List<CacheExtension> getRegisteredCacheExtensions()
           
 List<CacheLoader> getRegisteredCacheLoaders()
           
 CacheWriter getRegisteredCacheWriter()
          Retrieves the CacheWriter that was registered for this cache.
 SampledCacheStatistics getSampledCacheStatistics()
          Returns sampled statistics for this cache.
<T> Attribute<T>
getSearchAttribute(String attributeName)
          Retrieve the given named search attribute
 long getSearchesPerSecond()
          Get the number of search executions that have completed in the last second
 int getSize()
          Gets the size of the cache.
 int getSizeBasedOnAccuracy(int statisticsAccuracy)
          Accurately measuring statistics can be expensive.
 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.
 Element getWithLoader(Object key, CacheLoader loader, Object loaderArgument)
          This method will return, from the cache, the object associated with the argument "key".
 CacheWriterManager getWriterManager()
          Obtain the writer manager that's used by this cache instance.
 boolean hasAbortedSizeOf()
          Check if the cache may contain elements which the SizeOf engine could not fully size.
 void initialise()
          Newly created caches do not have a MemoryStore or a DiskStore.
 boolean isClusterBulkLoadEnabled()
          Returns true if at least one node in the cluster is in bulk-load mode.
 boolean isClusterCoherent()
          Deprecated. Use isClusterBulkLoadEnabled() instead
 boolean isDisabled()
          Whether this cache is disabled.
 boolean isElementInMemory(Object key)
          Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
 boolean isElementInMemory(Serializable key)
          Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
 boolean isElementOnDisk(Object key)
          Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
 boolean isElementOnDisk(Serializable key)
          Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
 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 isNodeBulkLoadEnabled()
          Returns true if the current node is in bulk-load mode.
 boolean isNodeCoherent()
          Deprecated. Use isNodeBulkLoadEnabled() instead
 boolean isPinned(Object key)
          Check if the key is pinned
 boolean isReadLockedByCurrentThread(Object key)
          Returns true if a read lock for the key is held by the current thread
 boolean isSampledStatisticsEnabled()
          Returns if sampled statistics collection is enabled or disabled
 boolean isSearchable()
          Is this cache searchable?
 boolean isStatisticsEnabled()
          Returns true if statistics collection is enabled
 boolean isValueInCache(Object value)
          An extremely expensive check to see if the value exists in the cache.
 boolean isWriteLockedByCurrentThread(Object key)
          Returns true if a write lock for the key is held by the current thread
 void load(Object key)
          The load method provides a means to "pre load" the cache.
 void loadAll(Collection keys, Object argument)
          The loadAll method provides a means to "pre load" objects into the cache.
 void put(Element element)
          Put an element in the cache.
 void put(Element element, boolean doNotNotifyCacheReplicators)
          Put an element in the cache.
 void putAll(Collection<Element> elements)
          Puts a collection of elements in the cache.
 Element putIfAbsent(Element element)
          Put an element in the cache if no element is currently mapped to the elements key.
 Element putIfAbsent(Element element, boolean doNotNotifyCacheReplicators)
          Put an element in the cache if no element is currently mapped to the elements key.
 void putQuiet(Element element)
          Put an element in the cache, without updating statistics, or updating listeners.
 void putWithWriter(Element element)
          Put an element in the cache writing through a CacheWriter.
 void registerCacheExtension(CacheExtension cacheExtension)
          Register a CacheExtension with the cache.
 void registerCacheLoader(CacheLoader cacheLoader)
          Register a CacheLoader with the cache.
 void registerCacheUsageListener(CacheUsageListener cacheUsageListener)
          Registers a CacheUsageListener which will be notified of the cache usage.
 void registerCacheWriter(CacheWriter cacheWriter)
          Register the CacheWriter for this cache.
 void releaseReadLockOnKey(Object key)
          Release a held read lock for the passed in key
 void releaseWriteLockOnKey(Object key)
          Release a held write lock for the passed in key
 boolean remove(Object key)
          Removes an Element from the Cache.
 boolean remove(Object key, boolean doNotNotifyCacheReplicators)
          Removes an Element from the Cache.
 boolean remove(Serializable key)
          Removes an Element from the Cache.
 boolean remove(Serializable key, boolean doNotNotifyCacheReplicators)
          Removes an Element from the Cache.
 void removeAll()
          Removes all cached items.
 void removeAll(boolean doNotNotifyCacheReplicators)
          Removes all cached items.
 void removeAll(Collection<?> keys)
          Removes given set of Element from the Cache.
 void removeAll(Collection<?> keys, boolean doNotNotifyCacheReplicators)
          Removes all cached items.
 void removeCacheUsageListener(CacheUsageListener cacheUsageListener)
          Remove an already registered CacheUsageListener, if any.
 boolean removeElement(Element element)
          Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remove a PropertyChangeListener.
 boolean removeQuiet(Object key)
          Removes an Element from the Cache, without notifying listeners.
 boolean removeQuiet(Serializable key)
          Removes an Element from the Cache, without notifying listeners.
 boolean removeWithWriter(Object key)
          Removes an Element from the Cache and any stores it might be in.
 Element replace(Element element)
          Replace the cached element only if an Element is currently cached for this key
 boolean replace(Element old, Element element)
          Replace the cached element only if the current Element is equal to the supplied old Element.
 void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
          Sets the bootstrap cache loader.
 void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler)
          Sets an ExceptionHandler on the Cache.
 void setCacheManager(CacheManager cacheManager)
          Sets the CacheManager
 void setDisabled(boolean disabled)
          Disables or enables this cache.
 void setDiskStorePath(String diskStorePath)
          DiskStore paths can conflict between CacheManager instances.
 void setName(String name)
          Sets the cache name which will name.
 void setNodeBulkLoadEnabled(boolean enabledBulkLoad)
          Enable/disable bulk-load mode in this node for this cache.
 void setNodeCoherent(boolean coherent)
          Deprecated. Use setNodeBulkLoadEnabled(boolean) instead
 void setPinned(Object key, boolean pinned)
          Mark the key as pinned or not.
 void setSampledStatisticsEnabled(boolean enableStatistics)
          Enable/disable sampled statistics collection.
 void setStatisticsAccuracy(int statisticsAccuracy)
          Sets the statistics accuracy.
 void setStatisticsEnabled(boolean enableStatistics)
          Enable/disable statistics collection.
 void setTransactionManagerLookup(TransactionManagerLookup transactionManagerLookup)
          This class is used to access the transaction manager used during XA.
 String toString()
          Returns a String representation of Cache.
 boolean tryReadLockOnKey(Object key, long timeout)
          Try to get a read lock on a given key.
 boolean tryWriteLockOnKey(Object key, long timeout)
          Try to get a write lock on a given key.
 void unpinAll()
          unpin all pinned keys
 void unregisterCacheExtension(CacheExtension cacheExtension)
          Unregister a CacheExtension with the cache.
 void unregisterCacheLoader(CacheLoader cacheLoader)
          Unregister a CacheLoader with the cache.
 void unregisterCacheWriter()
          Unregister the CacheWriter from the cache.
 void waitUntilClusterBulkLoadComplete()
          This method waits until all the connected nodes have disabled bulk-load.
 void waitUntilClusterCoherent()
          Deprecated. Use waitUntilClusterBulkLoadComplete() instead
 

Method Detail

unpinAll

void unpinAll()
unpin all pinned keys


isPinned

boolean isPinned(Object key)
Check if the key is pinned

Parameters:
key - the key to be checked
Returns:
true if the element is pinned

setPinned

void setPinned(Object key,
               boolean pinned)
Mark the key as pinned or not. Pinning is associated with key. Once the key is pinned, the mapping is held in the memory until setPinned(key, false) is called. replace(net.sf.ehcache.Element, net.sf.ehcache.Element) and remove(java.io.Serializable) does not change the pin state of key. This comes with little memory overhead that even if key is removed, it is still held in memory.

Parameters:
key - the key to be pinned or not
pinned - true if the key should be pinned, false otherwise

put

void put(Element element)
         throws IllegalArgumentException,
                IllegalStateException,
                CacheException
Put an element in the cache.

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

Also notifies the CacheEventListener that:

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
IllegalArgumentException - if the element is null
CacheException

putAll

void putAll(Collection<Element> elements)
            throws IllegalArgumentException,
                   IllegalStateException,
                   CacheException
Puts a collection of elements in the cache. Throws a NullPointerException if any element in the collection is null. Also notifies the CacheEventListener that: This operation is partially completed if any element or any key is null

Parameters:
elements - a collection of elements to be put in the cache. If elements are Serializable it can fully participate in replication and the DiskStore.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
IllegalArgumentException

put

void put(Element element,
         boolean doNotNotifyCacheReplicators)
         throws IllegalArgumentException,
                IllegalStateException,
                CacheException
Put an element in the cache.

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

Also notifies the CacheEventListener that:

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.STATUS_ALIVE
IllegalArgumentException - if the element is null
CacheException

putQuiet

void putQuiet(Element element)
              throws IllegalArgumentException,
                     IllegalStateException,
                     CacheException
Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used in conjunction with getQuiet(java.io.Serializable)

Parameters:
element - An object. If Serializable it can fully participate in replication and the DiskStore.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
IllegalArgumentException - if the element is null
CacheException

putWithWriter

void putWithWriter(Element element)
                   throws IllegalArgumentException,
                          IllegalStateException,
                          CacheException
Put an element in the cache writing through a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

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, if the writer operation succeeds, that:

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
IllegalArgumentException - if the element is null
CacheException - if no CacheWriter was registered

putIfAbsent

Element putIfAbsent(Element element)
                    throws NullPointerException
Put an element in the cache if no element is currently mapped to the elements key.

Parameters:
element - element to be added
Returns:
the element previously cached for this key, or null if none.
Throws:
NullPointerException - if the element is null, or has a null key

putIfAbsent

Element putIfAbsent(Element element,
                    boolean doNotNotifyCacheReplicators)
                    throws NullPointerException
Put an element in the cache if no element is currently mapped to the elements key.

Parameters:
element - element to be added
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:
the element previously cached for this key, or null if none.
Throws:
NullPointerException - if the element is null, or has a null key

removeElement

boolean removeElement(Element element)
                      throws NullPointerException
Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.

Parameters:
element - Element to be removed
Returns:
true if the value was removed
Throws:
NullPointerException - if the element is null, or has a null key

replace

boolean replace(Element old,
                Element element)
                throws NullPointerException,
                       IllegalArgumentException
Replace the cached element only if the current Element is equal to the supplied old Element.

Parameters:
old - Element to be test against
element - Element to be cached
Returns:
true is the Element was replaced
Throws:
NullPointerException - if the either Element is null or has a null key
IllegalArgumentException - if the two Element keys are non-null but not equal

replace

Element replace(Element element)
                throws NullPointerException
Replace the cached element only if an Element is currently cached for this key

Parameters:
element - Element to be cached
Returns:
the Element previously cached for this key, or null if no Element was cached
Throws:
NullPointerException - if the Element is null or has a null key

get

Element get(Serializable key)
            throws IllegalStateException,
                   CacheException
Gets an element from the cache. Updates Element Statistics

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

Parameters:
key - a serializable value
Returns:
the element, or null, if it does not exist.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
See Also:
isExpired(net.sf.ehcache.Element)

get

Element get(Object key)
            throws IllegalStateException,
                   CacheException
Gets an element from the cache. Updates Element Statistics

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

Parameters:
key - an Object value
Returns:
the element, or null, if it does not exist.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
Since:
1.2
See Also:
isExpired(net.sf.ehcache.Element)

getAll

Map<Object,Element> getAll(Collection<?> keys)
                           throws IllegalStateException,
                                  CacheException,
                                  NullPointerException
Gets all the elements from the cache for the keys provided. Updates Element Statistics Throws a NullPointerException if any key in the collection is null

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

Parameters:
keys - a collection of keys for which value is to be fetched
Returns:
Map of key and elements for the provided keys, value will be null for the keys which do not exist
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
NullPointerException - if any key is null in the collection
CacheException
See Also:
isExpired(net.sf.ehcache.Element)

getQuiet

Element getQuiet(Serializable key)
                 throws IllegalStateException,
                        CacheException
Gets an element from the cache, without updating Element statistics. Cache statistics are still updated.

Parameters:
key - a serializable value
Returns:
the element, or null, if it does not exist.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
Since:
2.5
See Also:
isExpired(net.sf.ehcache.Element)

getQuiet

Element getQuiet(Object key)
                 throws IllegalStateException,
                        CacheException
Gets an element from the cache, without updating Element statistics. Cache statistics are also not updated.

Parameters:
key - a serializable value
Returns:
the element, or null, if it does not exist.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException
Since:
1.2
See Also:
isExpired(net.sf.ehcache.Element)

getKeys

List getKeys()
             throws IllegalStateException,
                    CacheException
Returns a list of all elements in the cache, whether or not they are expired.

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

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

The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required for each 1000 entries.

Returns:
a list of Object keys
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

getKeysWithExpiryCheck

List getKeysWithExpiryCheck()
                            throws IllegalStateException,
                                   CacheException
Returns a list of all elements in the cache. Only keys of non-expired elements are returned.

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

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

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

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

Returns:
a list of Object keys
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

getKeysNoDuplicateCheck

@Deprecated
List getKeysNoDuplicateCheck()
                             throws IllegalStateException
Deprecated. versions since 2.1 do not return duplicates

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

remove

boolean remove(Serializable key)
               throws IllegalStateException
Removes an Element from the Cache. This also removes it from any stores it may be in.

Also notifies the CacheEventListener after the element was removed.

Parameters:
key -
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

boolean remove(Object key)
               throws IllegalStateException
Removes an Element from the Cache. This also removes it from any stores it may be in.

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

Parameters:
key -
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
Since:
1.2

removeAll

void removeAll(Collection<?> keys)
               throws IllegalStateException,
                      NullPointerException
Removes given set of Element from the Cache. This also removes them from any stores it may be in. Throws a NullPointerException if any key in the collection is null

Also notifies the CacheEventListener after the elements were removed. Notification is sent for every key irrespective of whether the key was present in the cache or not This operation is partially completed if any element or any key is null

Parameters:
keys - a collection of keys to operate on
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
NullPointerException - if any key is null in the collection

removeAll

void removeAll(Collection<?> keys,
               boolean doNotNotifyCacheReplicators)
               throws IllegalStateException,
                      NullPointerException
Removes all cached items.

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

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

remove

boolean remove(Serializable key,
               boolean doNotNotifyCacheReplicators)
               throws IllegalStateException
Removes an Element from the Cache. This also removes it from any stores it may be in.

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

Parameters:
key -
doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

remove

boolean remove(Object key,
               boolean doNotNotifyCacheReplicators)
               throws IllegalStateException
Removes an Element from the Cache. This also removes it from any stores it may be in.

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

Parameters:
key -
doNotNotifyCacheReplicators - whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeQuiet

boolean removeQuiet(Serializable key)
                    throws IllegalStateException
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Parameters:
key -
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

removeQuiet

boolean removeQuiet(Object key)
                    throws IllegalStateException
Removes an Element from the Cache, without notifying listeners. This also removes it from any stores it may be in.

Parameters:
key -
Returns:
true if the element was removed, false if it was not found in the cache
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
Since:
1.2

removeWithWriter

boolean removeWithWriter(Object key)
                         throws IllegalStateException,
                                CacheException
Removes an Element from the Cache and any stores it might be in. This also removes through to a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.

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.STATUS_ALIVE
CacheException - if no CacheWriter was registered
Since:
2.0

removeAll

void removeAll()
               throws IllegalStateException,
                      CacheException
Removes all cached items.

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

removeAll

void removeAll(boolean doNotNotifyCacheReplicators)
               throws IllegalStateException,
                      CacheException
Removes all cached items.

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

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

flush

void flush()
           throws IllegalStateException,
                  CacheException
Flushes all cache items from memory to the disk store, and from the DiskStore to disk.

Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

getSize

int getSize()
            throws IllegalStateException,
                   CacheException
Gets the size of the cache. This is a subtle concept. See below.

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

This number is the actual number of elements, including expired elements that have not been removed.

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

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

To get an exact size, which would exclude expired elements, use getKeysWithExpiryCheck().size(), although see that method for the approximate time that would take.

To get a very fast result, use getKeysNoDuplicateCheck().size(). If the disk store is being used, there will be some duplicates.

Note:getSize() is a very expensive operation in off-heap, disk and Terracotta implementations.

Returns:
The size value
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

getSizeBasedOnAccuracy

int getSizeBasedOnAccuracy(int statisticsAccuracy)
                           throws IllegalArgumentException,
                                  IllegalStateException,
                                  CacheException
Accurately measuring statistics can be expensive. Returns the size of the cache based on the accuracy setting

Parameters:
statisticsAccuracy - one of Statistics.STATISTICS_ACCURACY_BEST_EFFORT, Statistics.STATISTICS_ACCURACY_GUARANTEED, Statistics.STATISTICS_ACCURACY_NONE
Returns:
the size of the cache based on the current accuracy setting
Throws:
IllegalArgumentException - if the statisticsAccuracy is not one of the above
IllegalStateException - if the cache is not Status.STATUS_ALIVE
CacheException

calculateInMemorySize

long calculateInMemorySize()
                           throws IllegalStateException,
                                  CacheException
Gets the size of the memory store for this cache

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

Returns:
the approximate size of the memory store in bytes
Throws:
IllegalStateException
CacheException

calculateOffHeapSize

long calculateOffHeapSize()
                          throws IllegalStateException,
                                 CacheException
Gets the size of the off-heap store for this cache

Returns:
the size of the off-heap store in bytes
Throws:
IllegalStateException
CacheException

calculateOnDiskSize

long calculateOnDiskSize()
                         throws IllegalStateException,
                                CacheException
Gets the size of the on-disk store for this cache

Returns:
the size of the on-disk store in bytes
Throws:
IllegalStateException
CacheException

hasAbortedSizeOf

boolean hasAbortedSizeOf()
Check if the cache may contain elements which the SizeOf engine could not fully size.

Returns:
true if the cache may contain partially sized objects

getMemoryStoreSize

long getMemoryStoreSize()
                        throws IllegalStateException
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.STATUS_ALIVE

getOffHeapStoreSize

long getOffHeapStoreSize()
                         throws IllegalStateException
Returns the number of elements in the off-heap store.

Returns:
the number of elements in the off-heap store
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

getDiskStoreSize

int getDiskStoreSize()
                     throws IllegalStateException
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.STATUS_ALIVE

getStatus

Status getStatus()
Gets the status attribute of the Cache.

Returns:
The status value from the Status enum class

getName

String getName()
Gets the cache name.


setName

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

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

toString

String toString()
Returns a String representation of Cache.

Overrides:
toString in class Object

isExpired

boolean isExpired(Element element)
                  throws IllegalStateException,
                         NullPointerException
Checks whether this cache element has expired.

The element is expired if:

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

Parameters:
element - the element to check
Returns:
true if it has expired
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE
NullPointerException - if the element is null

clone

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

A new, empty, RegisteredEventListeners is created on clone.

Returns:
an object of type Cache
Throws:
CloneNotSupportedException

getCacheEventNotificationService

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

Returns:
the RegisteredEventListeners instance for this cache.

isElementInMemory

boolean isElementInMemory(Serializable key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Returns:
true if an element matching the key is found in memory

isElementInMemory

boolean isElementInMemory(Object key)
Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Returns:
true if an element matching the key is found in memory
Since:
1.2

isElementOnDisk

boolean isElementOnDisk(Serializable key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Returns:
true if an element matching the key is found in the diskStore

isElementOnDisk

boolean isElementOnDisk(Object key)
Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Returns:
true if an element matching the key is found in the diskStore
Since:
1.2

getGuid

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

Returns:
the globally unique identifier for this cache instance. This is guaranteed to be unique.
Since:
1.2

getCacheManager

CacheManager getCacheManager()
Gets the CacheManager managing this cache. For a newly created cache this will be null until it has been added to a CacheManager.

Returns:
the manager or null if there is none

clearStatistics

void clearStatistics()
Resets statistics counters back to 0.


getStatisticsAccuracy

int getStatisticsAccuracy()
Accurately measuring statistics can be expensive. Returns the current accuracy setting.

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

setStatisticsAccuracy

void setStatisticsAccuracy(int statisticsAccuracy)
Sets the statistics accuracy.

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

evictExpiredElements

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


isKeyInCache

boolean isKeyInCache(Object key)
An inexpensive check to see if the key exists in the cache.

Since no assertions are made about the state of the Element it is possible that the Element is expired, but this method still returns true.

Parameters:
key - the key to check for
Returns:
true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

isValueInCache

boolean isValueInCache(Object value)
An extremely expensive check to see if the value exists in the cache.

Parameters:
value - to check for
Returns:
true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.

getStatistics

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

Best Effort Size

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

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

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

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

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

Guaranteed Accuracy Size

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

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

Fast but non-accurate Size

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

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

Returns:
the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
Throws:
IllegalStateException - if the cache is not Status.STATUS_ALIVE

getLiveCacheStatistics

LiveCacheStatistics getLiveCacheStatistics()
                                           throws IllegalStateException
This is different from getStatistics() in the way that values returned from LiveCacheStatistics will reflect the current state of the cache (and not a snapshot of the cache when the api's were called like getStatistics())

Returns:
The LiveCacheStatistics associated with this cache
Throws:
IllegalStateException
Since:
1.7

registerCacheUsageListener

void registerCacheUsageListener(CacheUsageListener cacheUsageListener)
                                throws IllegalStateException
Registers a CacheUsageListener which will be notified of the cache usage. Implementations of CacheUsageListener should override the Object.equals(Object) and Object.hashCode() methods as it is used for equality check

Throws:
IllegalStateException
Since:
1.7

removeCacheUsageListener

void removeCacheUsageListener(CacheUsageListener cacheUsageListener)
                              throws IllegalStateException
Remove an already registered CacheUsageListener, if any. Depends on the Object.equals(Object) method.

Throws:
IllegalStateException
Since:
1.7

setCacheManager

void setCacheManager(CacheManager cacheManager)
Sets the CacheManager

Parameters:
cacheManager - the CacheManager for this cache to use.

getBootstrapCacheLoader

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

Returns:
the BootstrapCacheLoader to use

setBootstrapCacheLoader

void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader)
                             throws CacheException
Sets the bootstrap cache loader.

Parameters:
bootstrapCacheLoader - the loader to be used
Throws:
CacheException - if this method is called after the cache is initialized

setDiskStorePath

void setDiskStorePath(String diskStorePath)
                      throws CacheException
DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.

Parameters:
diskStorePath - the new path to be used.
Throws:
CacheException - if this method is called after the cache is initialized

initialise

void initialise()
Newly created caches do not have a MemoryStore or a DiskStore.

This method creates those and makes the cache ready to accept elements


bootstrap

void bootstrap()
Bootstrap command. This must be called after the Cache is intialised, during CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager initialise completes, otherwise they will happen in the background.


dispose

void dispose()
             throws IllegalStateException
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.STATUS_ALIVE

getCacheConfiguration

CacheConfiguration getCacheConfiguration()
Gets the cache configuration this cache was created with.

Things like listeners that are added dynamically are excluded.


registerCacheExtension

void registerCacheExtension(CacheExtension cacheExtension)
Register a CacheExtension with the cache. It will then be tied into the cache lifecycle.

If the CacheExtension is not initialised, initialise it.


unregisterCacheExtension

void unregisterCacheExtension(CacheExtension cacheExtension)
Unregister a CacheExtension with the cache. It will then be detached from the cache lifecycle.


getRegisteredCacheExtensions

List<CacheExtension> getRegisteredCacheExtensions()
Returns:
the cache extensions as a live list

getAverageGetTime

float getAverageGetTime()
The average get time in ms.


setCacheExceptionHandler

void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler)
Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.


getCacheExceptionHandler

CacheExceptionHandler getCacheExceptionHandler()
Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.


registerCacheLoader

void registerCacheLoader(CacheLoader cacheLoader)
Register a CacheLoader with the cache. It will then be tied into the cache lifecycle.

The CacheLoader instance will be initialized when the cache itself is being initialized. Should the cache already be initialized, CacheLoader.init() will not be invoked. If the loader requires initialization, the user will have to call it manually before registering it with a Cache instance that's already alive

Parameters:
cacheLoader - A Cache Loader to register
Since:
While the javadoc has changed in 2.5.2, the behavior has not.

unregisterCacheLoader

void unregisterCacheLoader(CacheLoader cacheLoader)
Unregister a CacheLoader with the cache. It will then be detached from the cache lifecycle.

Parameters:
cacheLoader - A Cache Loader to unregister

getRegisteredCacheLoaders

List<CacheLoader> getRegisteredCacheLoaders()
Returns:
the cache loaders as a live list

registerCacheWriter

void registerCacheWriter(CacheWriter cacheWriter)
Register the CacheWriter for this cache. It will then be tied into the cache lifecycle.

If the CacheWriter is not initialised, initialise it.

Parameters:
cacheWriter - A CacheWriter to register

unregisterCacheWriter

void unregisterCacheWriter()
Unregister the CacheWriter from the cache. It will then be detached from the cache lifecycle.

If not CacheWriter was registered beforehand this operation has no effect.


getRegisteredCacheWriter

CacheWriter getRegisteredCacheWriter()
Retrieves the CacheWriter that was registered for this cache.

Returns:
the registered CacheWriter; or null if none was registered before

getWithLoader

Element getWithLoader(Object key,
                      CacheLoader loader,
                      Object loaderArgument)
                      throws CacheException
This method will return, from the cache, the object associated with the argument "key".

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

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

Parameters:
key - key whose associated value is to be returned.
loader - the override loader to use. If null, the cache's default loader will be used
loaderArgument - an argument to pass to the CacheLoader.
Returns:
an element if it existed or could be loaded, otherwise null
Throws:
CacheException

getAllWithLoader

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

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

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

The constructs package provides similar functionality using the decorator SelfPopulatingCache

Parameters:
keys - a collection of keys to be returned/loaded
loaderArgument - an argument to pass to the CacheLoader.
Returns:
a Map populated from the Cache. If there are no elements, an empty Map is returned.
Throws:
CacheException

load

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

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

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

loadAll

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

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

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

Throws:
CacheException

isDisabled

boolean isDisabled()
Whether this cache is disabled. "Disabled" means:
  1. bootstrap is disabled
  2. puts are discarded
  3. putQuites are discarded
In all other respects the cache continues as it is.

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

Returns:
true if the cache is disabled.

setDisabled

void setDisabled(boolean disabled)
Disables or enables this cache. This call overrides the previous value of disabled.

Parameters:
disabled - true if you wish to disable, false to enable
See Also:
isDisabled()

isStatisticsEnabled

boolean isStatisticsEnabled()
Returns true if statistics collection is enabled

Returns:
true if statistics is enabled, false otherwise

setStatisticsEnabled

void setStatisticsEnabled(boolean enableStatistics)
Enable/disable statistics collection. Enabling statistics does not have any effect on sampled statistics. To enable sampled statistics, use setSampledStatisticsEnabled(boolean) with parameter true. Disabling statistics also disables the sampled statistics collection if it is enabled

Parameters:
enableStatistics -

getSampledCacheStatistics

SampledCacheStatistics getSampledCacheStatistics()
Returns sampled statistics for this cache.

Returns:
The sampled cache statistics

setSampledStatisticsEnabled

void setSampledStatisticsEnabled(boolean enableStatistics)
Enable/disable sampled statistics collection. Enabling sampled statistics also enables the normal statistics collection if its not already enabled. Disabling sampled statistics does not have any effect on normal statistics.

Parameters:
enableStatistics -

isSampledStatisticsEnabled

boolean isSampledStatisticsEnabled()
Returns if sampled statistics collection is enabled or disabled

Returns:
true if sampled statistics is enabled, false otherwise

getInternalContext

Object getInternalContext()
This should not be used return some internal context (generally will be null)


disableDynamicFeatures

void disableDynamicFeatures()
Disables dynamic configuration and disable/enable for this cache.

This is a one time operation. Once an Ehcache instance has had its dynamic operations disabled they cannot be re-enabled.


getWriterManager

CacheWriterManager getWriterManager()
Obtain the writer manager that's used by this cache instance.

Returns:
the writer manager that's set up for this cache

isClusterCoherent

@Deprecated
boolean isClusterCoherent()
                          throws TerracottaNotRunningException
Deprecated. Use isClusterBulkLoadEnabled() instead

Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Returns:
true if the cache is in coherent mode cluster-wide, false otherwise
Throws:
TerracottaNotRunningException

isNodeCoherent

@Deprecated
boolean isNodeCoherent()
                       throws TerracottaNotRunningException
Deprecated. Use isNodeBulkLoadEnabled() instead

Returns true if the cache is in coherent mode for the current node. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Returns:
true if the cache is in coherent mode cluster-wide, false otherwise
Throws:
TerracottaNotRunningException

setNodeCoherent

@Deprecated
void setNodeCoherent(boolean coherent)
                     throws UnsupportedOperationException,
                            TerracottaNotRunningException
Deprecated. Use setNodeBulkLoadEnabled(boolean) instead

Sets the cache in coherent or incoherent mode depending on the parameter on this node. Calling setNodeCoherent(true) when the cache is already in coherent mode or calling setNodeCoherent(false) when already in incoherent mode will be a no-op.

It applies to coherent clustering mechanisms only e.g. Terracotta

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the config.

Parameters:
coherent - true transitions to coherent mode, false to incoherent mode
Throws:
UnsupportedOperationException - if this cache does not support coherence, like RMI replication
TerracottaNotRunningException

waitUntilClusterCoherent

@Deprecated
void waitUntilClusterCoherent()
                              throws UnsupportedOperationException,
                                     TerracottaNotRunningException
Deprecated. Use waitUntilClusterBulkLoadComplete() instead

This method waits until the cache is in coherent mode in all the connected nodes. If the cache is already in coherent mode it returns immediately

It applies to coherent clustering mechanisms only e.g. Terracotta

Throws:
UnsupportedOperationException - if this cache does not support coherence, like RMI replication
TerracottaNotRunningException

setTransactionManagerLookup

void setTransactionManagerLookup(TransactionManagerLookup transactionManagerLookup)
This class is used to access the transaction manager used during XA.

Parameters:
transactionManagerLookup -

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener.

Parameters:
listener -

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
Remove a PropertyChangeListener.

Parameters:
listener -

getSearchAttribute

<T> Attribute<T> getSearchAttribute(String attributeName)
                                throws CacheException
Retrieve the given named search attribute

Type Parameters:
T - type of the attribute
Parameters:
attributeName - the name of the attribute to retrieve
Returns:
the search attribute
Throws:
CacheException - if no such attribute is defined for the given name

createQuery

Query createQuery()
Create a new query builder for this cache

Returns:
a new query builder

isSearchable

boolean isSearchable()
Is this cache searchable?

Returns:
true if this cache is searchable

getAverageSearchTime

long getAverageSearchTime()
Get the average search execution time (in millis) for searches that have completed in the last sample period


getSearchesPerSecond

long getSearchesPerSecond()
Get the number of search executions that have completed in the last second


acquireReadLockOnKey

void acquireReadLockOnKey(Object key)
Acquires the proper read lock for a given cache key

Parameters:
key - - The key that retrieves a value that you want to protect via locking

acquireWriteLockOnKey

void acquireWriteLockOnKey(Object key)
Acquires the proper write lock for a given cache key

Parameters:
key - - The key that retrieves a value that you want to protect via locking

tryReadLockOnKey

boolean tryReadLockOnKey(Object key,
                         long timeout)
                         throws InterruptedException
Try to get a read lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock

Parameters:
key - - The key that retrieves a value that you want to protect via locking
timeout - - millis until giveup on getting the lock
Returns:
whether the lock was awarded
Throws:
InterruptedException

tryWriteLockOnKey

boolean tryWriteLockOnKey(Object key,
                          long timeout)
                          throws InterruptedException
Try to get a write lock on a given key. If can't get it in timeout millis then return a boolean telling that it didn't get the lock

Parameters:
key - - The key that retrieves a value that you want to protect via locking
timeout - - millis until giveup on getting the lock
Returns:
whether the lock was awarded
Throws:
InterruptedException

releaseReadLockOnKey

void releaseReadLockOnKey(Object key)
Release a held read lock for the passed in key

Parameters:
key - - The key that retrieves a value that you want to protect via locking

releaseWriteLockOnKey

void releaseWriteLockOnKey(Object key)
Release a held write lock for the passed in key

Parameters:
key - - The key that retrieves a value that you want to protect via locking

isReadLockedByCurrentThread

boolean isReadLockedByCurrentThread(Object key)
                                    throws UnsupportedOperationException
Returns true if a read lock for the key is held by the current thread

Parameters:
key -
Returns:
true if a read lock for the key is held by the current thread
Throws:
UnsupportedOperationException - if querying the read lock state is not supported

isWriteLockedByCurrentThread

boolean isWriteLockedByCurrentThread(Object key)
                                     throws UnsupportedOperationException
Returns true if a write lock for the key is held by the current thread

Parameters:
key -
Returns:
true if a write lock for the key is held by the current thread
Throws:
UnsupportedOperationException - if querying the write lock state is not supported

isClusterBulkLoadEnabled

boolean isClusterBulkLoadEnabled()
                                 throws UnsupportedOperationException,
                                        TerracottaNotRunningException
Returns true if at least one node in the cluster is in bulk-load mode. Returns false otherwise.

NOTE: if isNodeBulkLoadEnabled() returns true, this method will always return true. Applies to caches clustered with Terracotta only.

Returns:
true if the cache is in bulk-load mode cluster-wide, false otherwise
Throws:
UnsupportedOperationException - if the cache is not clustered with Terracotta
TerracottaNotRunningException

isNodeBulkLoadEnabled

boolean isNodeBulkLoadEnabled()
                              throws UnsupportedOperationException,
                                     TerracottaNotRunningException
Returns true if the current node is in bulk-load mode. Returns false otherwise.

NOTE: if this method returns true, isClusterBulkLoadEnabled() method will always return true. Applies to caches clustered with Terracotta only.

Returns:
true if the cache is in coherent mode cluster-wide, false otherwise
Throws:
UnsupportedOperationException - if the cache is not clustered with Terracotta
TerracottaNotRunningException

setNodeBulkLoadEnabled

void setNodeBulkLoadEnabled(boolean enabledBulkLoad)
                            throws UnsupportedOperationException,
                                   TerracottaNotRunningException
Enable/disable bulk-load mode in this node for this cache. Calling setBulkLoadEnabled(true) when the cache is already in bulk-load mode or calling setBulkLoadEnabled(false) when already NOT in bulk-load mode will be a no-op.

Applies to caches clustered with Terracotta only.

When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is NonstopConfiguration.getBulkOpsTimeoutMultiplyFactor() times the timeout value in the nonstop config.

Parameters:
enabledBulkLoad - true enables bulk-load, false disables it if not already disabled
Throws:
UnsupportedOperationException - if the cache is not clustered with Terracotta
TerracottaNotRunningException

waitUntilClusterBulkLoadComplete

void waitUntilClusterBulkLoadComplete()
                                      throws UnsupportedOperationException,
                                             TerracottaNotRunningException
This method waits until all the connected nodes have disabled bulk-load. Or in other words, calling this method will block until all connected nodes in the cluster disables bulk-load. If none of the nodes did not enable bulk-load this method will return immediately

Applies to caches clustered with Terracotta only.

Throws:
UnsupportedOperationException - if the cache is not clustered with Terracotta
TerracottaNotRunningException

ehcache

Copyright © 2003-2012 Terracotta, Inc.. All Rights Reserved.