net.sf.ehcache.Ehcache Maven / Gradle / Ivy
Show all versions of ehcache-core Show documentation
/**
* Copyright Terracotta, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.sf.ehcache;
import java.beans.PropertyChangeListener;
import java.io.Serializable;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
import net.sf.ehcache.config.CacheConfiguration;
import net.sf.ehcache.config.NonstopConfiguration;
import net.sf.ehcache.event.RegisteredEventListeners;
import net.sf.ehcache.exceptionhandler.CacheExceptionHandler;
import net.sf.ehcache.extension.CacheExtension;
import net.sf.ehcache.loader.CacheLoader;
import net.sf.ehcache.search.Attribute;
import net.sf.ehcache.search.Query;
import net.sf.ehcache.search.attribute.DynamicAttributesExtractor;
import net.sf.ehcache.statistics.CacheUsageListener;
import net.sf.ehcache.statistics.StatisticsGateway;
import net.sf.ehcache.terracotta.TerracottaNotRunningException;
import net.sf.ehcache.transaction.manager.TransactionManagerLookup;
import net.sf.ehcache.writer.CacheWriter;
import net.sf.ehcache.writer.CacheWriterManager;
/**
* An interface for Ehcache.
*
* Ehcache is the central interface. Caches have {@link Element}s and are managed
* by the {@link CacheManager}. The Cache performs logical actions. It delegates physical
* implementations to its {@link net.sf.ehcache.store.Store}s.
*
* A reference to an EhCache can be obtained through the {@link CacheManager}. An Ehcache thus obtained
* is guaranteed to have status {@link Status#STATUS_ALIVE}. This status is checked for any method which
* throws {@link IllegalStateException} and the same thrown if it is not alive. This would normally
* happen if a call is made after {@link CacheManager#shutdown} is invoked.
*
* Statistics on cache usage are collected and made available through public methods.
*
* @author Greg Luck
* @version $Id: Ehcache.java 10567 2017-02-10 17:41:41Z ljacomet $
*/
public interface Ehcache extends Cloneable {
/**
* 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
*
*
* @param element An object. If Serializable it can fully participate in replication and the DiskStore.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws IllegalArgumentException if the element is null
* @throws CacheException
*/
void put(Element element) throws IllegalArgumentException, IllegalStateException,
CacheException;
/**
* Puts a collection of elements in to the cache.
*
* This method will throw a {@code NullPointerException} if a null element or null key is encountered
* in the collection, and a partial completion may result (as only some of the elements may have been put).
*
* For each element that is put the registered {@code CacheEventListener}s are notified of a newly put item
* ({@link net.sf.ehcache.event.CacheEventListener#notifyElementPut(net.sf.ehcache.Ehcache, net.sf.ehcache.Element) notifyElementPut(...)})
* regardless of whether the individual put is a new put or an update.
*
* @param elements the collection of elements to be put in the cache.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws CacheException
*/
void putAll(Collection elements) 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:
*
* - 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
*
*
* @param element An object. If Serializable it can fully participate in replication and the DiskStore.
* @param 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 {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws IllegalArgumentException if the element is null
*/
void put(Element element, boolean doNotNotifyCacheReplicators) 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 {@link #getQuiet}
*
* @param element An object. If Serializable it can fully participate in replication and the DiskStore.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws IllegalArgumentException if the element is null
*/
void putQuiet(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:
*
* - 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
*
*
* @param element An object. If Serializable it can fully participate in replication and the DiskStore.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws IllegalArgumentException if the element is null
* @throws CacheException if no CacheWriter was registered
*/
void putWithWriter(Element element) throws IllegalArgumentException, IllegalStateException, CacheException;
/**
* Put an element in the cache if no element is currently mapped to the elements key.
*
* @param element element to be added
* @return the element previously cached for this key, or null if none.
*
* @throws NullPointerException if the element is null, or has a null key
*/
Element putIfAbsent(Element element) throws NullPointerException;
/**
* Put an element in the cache if no element is currently mapped to the elements key.
*
* @param element element to be added
* @param 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
* @return the element previously cached for this key, or null if none.
*
* @throws NullPointerException if the element is null, or has a null key
*/
Element putIfAbsent(Element element, boolean doNotNotifyCacheReplicators) throws NullPointerException;
/**
* Remove the Element mapped to the key for the supplied element if the value of the supplied Element
* compares equal to the value of the cached Element.
*
* This is equivalent to
*
* if (elementValueComparator.equals(cache.get(element.getObjectKey()), element)) {
* return cache.remove(element.getObjectKey());
* } else return false;
*
* except that the action is performed atomically.
*
* @param element Element to be removed
* @return {@code true} if the value was removed
*
* @throws NullPointerException if the element is null, or has a null key
*
* @see net.sf.ehcache.config.CacheConfiguration#addElementValueComparator(net.sf.ehcache.config.ElementValueComparatorConfiguration)
*/
boolean removeElement(Element element) throws NullPointerException;
/**
* Replace the cached element only if the current Element is equal to the supplied old Element.
*
* @param old Element to be test against
* @param element Element to be cached
* @return true if the Element was replaced
* @throws NullPointerException if the either Element is null or has a null key
* @throws IllegalArgumentException if the two Element keys are non-null but not equal
*/
boolean replace(Element old, Element element) throws NullPointerException, IllegalArgumentException;
/**
* Replace the cached element only if an Element is currently cached for this key
* @param element Element to be cached
* @return 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
*/
Element replace(Element element) throws NullPointerException;
/**
* Gets an element from the cache. Updates Element Statistics
*
* Note that the Element's lastAccessTime is always the time of this get.
* Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
*
* @param key a serializable value
* @return the element, or null, if it does not exist.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @see #isExpired
*/
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 {@link #getQuiet(Object)} to peek into the Element to see its last access time with get
*
* @param key an Object value
* @return the element, or null, if it does not exist.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @see #isExpired
* @since 1.2
*/
Element get(Object key) throws IllegalStateException, CacheException;
/**
* 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 {@link #getQuiet(Object)} to peek into the Element to see its last access time with get
*
* @param keys a collection of keys for which value is to be fetched
* @return 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 {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws NullPointerException if any key is null in the collection
* @see #isExpired
*/
Map getAll(Collection keys) throws IllegalStateException, CacheException, NullPointerException;
/**
* Gets an element from the cache, without updating Element statistics. Cache statistics are
* still updated.
*
*
* @param key a serializable value
* @return the element, or null, if it does not exist.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @see #isExpired
* @since 2.5
*/
Element getQuiet(Serializable key) throws IllegalStateException, CacheException;
/**
* Gets an element from the cache, without updating Element statistics. Cache statistics are
* also not updated.
*
*
* @param key a serializable value
* @return the element, or null, if it does not exist.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @see #isExpired
* @since 1.2
*/
Element getQuiet(Object key) 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). For large caches - or caches with high-latency storage this method can take a very long time to complete,
* may cause timeouts if using features such NonStopCache or transactions, and is not guaranteed to give a consistent view of the
* cache entry set. Usage is highly discouraged.
*
* @return a list of {@link Object} keys
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
List getKeys() 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.
*
* For large caches - or caches with high-latency storage this method can take
* a very long time to complete. You should seriously consider whether
* your usage requires checking for expired keys before choosing to call this method.
* As this method can take a long time the results may also be significantly out of
* date by the time the method returns.
*
* @return a list of {@link Object} keys
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
List getKeysWithExpiryCheck() throws IllegalStateException, CacheException;
/**
* 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
*
* @return a list of {@link Object} keys
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @deprecated versions since 2.1 do not return duplicates
*/
@Deprecated
List getKeysNoDuplicateCheck() throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
* stores it may be in.
*
* Also notifies the CacheEventListener after the element was removed.
*
* @param key
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
boolean remove(Serializable key) throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.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.
*
* @param key
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @since 1.2
*/
boolean remove(Object key) throws IllegalStateException;
/**
* Removes given set of {@link net.sf.ehcache.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
* @param keys a collection of keys to operate on
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws NullPointerException if any key is null in the collection
*/
void removeAll(Collection keys) throws IllegalStateException, NullPointerException;
/**
* Removes all cached items.
*
* When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
* {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
*
* @param 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 {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
void removeAll(Collection keys, boolean doNotNotifyCacheReplicators) throws IllegalStateException, NullPointerException;
/**
* Removes an {@link net.sf.ehcache.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.
*
* @param key
* @param 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
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
boolean remove(Serializable key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.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.
*
* @param key
* @param 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
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
boolean remove(Object key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
* stores it may be in.
*
*
* @param key
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
boolean removeQuiet(Serializable key) throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
* stores it may be in.
*
*
* @param key
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @since 1.2
*/
boolean removeQuiet(Object key) throws IllegalStateException;
/**
* Removes an {@link net.sf.ehcache.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.
*
* @param key
* @return true if the element was removed, false if it was not found in the cache
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws CacheException if no CacheWriter was registered
* @since 2.0
*/
boolean removeWithWriter(Object key) throws IllegalStateException, CacheException;
/**
* Removes all cached items.
*
* When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
* {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
*
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
void removeAll() throws IllegalStateException, CacheException;
/**
* Removes all cached items.
*
* When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
* {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
*
* @param 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 {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
void removeAll(boolean doNotNotifyCacheReplicators) 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 {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
void flush() throws IllegalStateException, CacheException;
/**
* Gets the size of the cache. This is a subtle concept. See below.
*
* The size is the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
* the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.disk.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 {@link #getKeysWithExpiryCheck()}.size(),
* although see that method for the approximate time that would take.
*
* To get a very fast result, use {@link #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.
*
* @return The size value
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
int getSize() 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
*
*
* @return the approximate size of the memory store in bytes
* @throws IllegalStateException
*/
@Deprecated long calculateInMemorySize() throws IllegalStateException, CacheException;
/**
* Gets the size of the off-heap store for this cache
*
* @return the size of the off-heap store in bytes
* @throws IllegalStateException
*/
@Deprecated long calculateOffHeapSize() throws IllegalStateException, CacheException;
/**
* Gets the size of the on-disk store for this cache
*
* @return the size of the on-disk store in bytes
* @throws IllegalStateException
*/
@Deprecated long calculateOnDiskSize() throws IllegalStateException, CacheException;
/**
* Check if the cache may contain elements which the SizeOf engine could not fully size.
*
* @return true if the cache may contain partially sized objects
*/
boolean hasAbortedSizeOf();
/**
* Returns the number of elements in the memory store.
*
* @return the number of elements in the memory store
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
@Deprecated long getMemoryStoreSize() throws IllegalStateException;
/**
* Returns the number of elements in the off-heap store.
*
* @return the number of elements in the off-heap store
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
@Deprecated long getOffHeapStoreSize() throws IllegalStateException;
/**
* Returns the number of elements in the disk store.
*
* @return the number of elements in the disk store.
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
@Deprecated int getDiskStoreSize() throws IllegalStateException;
/**
* Gets the status attribute of the Cache.
*
* @return The status value from the Status enum class
*/
Status getStatus();
/**
* Gets the cache name.
*/
String getName();
/**
* Sets the cache name which will name.
*
* @param name the name of the cache. Should not be null.
*/
void setName(String name);
/**
* Returns a {@link String} representation of {@link net.sf.ehcache.Cache}.
*/
String toString();
/**
* Checks whether this cache element has expired.
*
* The element is expired if:
*
* - the idle time is non-zero and has elapsed, unless the cache is eternal; or
*
- the time to live is non-zero and has elapsed, unless the cache is eternal; or
*
- the value of the element is null.
*
*
* @param element the element to check
* @return true if it has expired
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
* @throws NullPointerException if the element is null
*/
boolean isExpired(Element element) throws IllegalStateException, NullPointerException;
/**
* Clones a cache. This is only legal if the cache has not been
* initialized. At that point only primitives have been set and no
* {@link net.sf.ehcache.store.MemoryStore} or {@link net.sf.ehcache.store.disk.DiskStore} has been created.
*
* A new, empty, RegisteredEventListeners is created on clone.
*
*
* @return an object of type {@link net.sf.ehcache.Cache}
* @throws CloneNotSupportedException
*/
Object clone() throws CloneNotSupportedException;
/**
* Use this to access the service in order to register and unregister listeners
*
* @return the RegisteredEventListeners instance for this cache.
*/
RegisteredEventListeners getCacheEventNotificationService();
/**
* 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.
*
* @return true if an element matching the key is found in memory
*/
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.
*
* @return true if an element matching the key is found in memory
* @since 1.2
*/
boolean isElementInMemory(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.
*
* @return true if an element matching the key is found in the diskStore
*/
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.
*
* @return true if an element matching the key is found in the diskStore
* @since 1.2
*/
boolean isElementOnDisk(Object key);
/**
* The GUID for this cache instance can be used to determine whether two cache instance references
* are pointing to the same cache.
*
* @return the globally unique identifier for this cache instance. This is guaranteed to be unique.
* @since 1.2
*/
String getGuid();
/**
* Gets the CacheManager managing this cache. For a newly created cache this will be null until
* it has been added to a CacheManager.
*
* @return the manager or null if there is none
*/
CacheManager getCacheManager();
/**
* Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
*
* For large caches - or caches with high-latency storage this method can take
* a very long time to complete. You should seriously consider relying on
* some form of capacity eviction to control cache capacity over calling this method.
* As this method can take a long time the cache may not be fully purged of expired
* elements on return, since more elements may have expired during the call.
*/
void evictExpiredElements();
/**
* 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.
*
* @param key the key to check for
* @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
*/
boolean isKeyInCache(Object key);
/**
* An extremely expensive check to see if the value exists in the cache.
*
* @param value to check for
* @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
*/
boolean isValueInCache(Object value);
/**
* 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 {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
*
* The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
* the number of {@link Element}s in the {@link net.sf.ehcache.store.disk.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 {@link 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 {@link 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.
* @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
* @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
*/
StatisticsGateway getStatistics() throws IllegalStateException;
/**
* Sets the CacheManager
*
* @param cacheManager the CacheManager for this cache to use.
*/
void setCacheManager(CacheManager cacheManager);
/**
* Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
*
* @return the BootstrapCacheLoader to use
*/
BootstrapCacheLoader getBootstrapCacheLoader();
/**
* Sets the bootstrap cache loader.
*
* @param bootstrapCacheLoader the loader to be used
* @throws CacheException if this method is called after the cache is initialized
*/
void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) throws CacheException;
/**
* Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or
* a {@link net.sf.ehcache.store.disk.DiskStore}.
*
* This method creates those and makes the cache ready to accept elements
*
* This method is not intended to be called explicitly, but rather is called implicitly
* by the cache's {@link net.sf.ehcache.CacheManager} instance during the cache
* initialization. Invoking this method directly will likely lead to breaking.
*/
void initialise();
/**
* 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.
*
* This method is not intended to be called explicitly, but rather is called implicitly
* by the cache's {@link net.sf.ehcache.CacheManager} instance during the cache
* initialization. Invoking this method directly will likely lead to breaking.
*/
void bootstrap();
/**
* 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 {@link Status#STATUS_ALIVE}
*/
public void dispose() throws IllegalStateException;
/**
* Gets the cache configuration this cache was created with.
*
* Things like listeners that are added dynamically are excluded.
*/
CacheConfiguration getCacheConfiguration();
/**
* Register a {@link CacheExtension} with the cache. It will then be tied into the cache lifecycle.
*
* If the CacheExtension is not initialised, initialise it.
*/
public void registerCacheExtension(CacheExtension cacheExtension);
/**
* Unregister a {@link CacheExtension} with the cache. It will then be detached from the cache lifecycle.
*/
public void unregisterCacheExtension(CacheExtension cacheExtension);
/**
*
* @return the cache extensions as a live list
*/
public List getRegisteredCacheExtensions();
/**
* Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
*/
public void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler);
/**
* Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
*/
public CacheExceptionHandler getCacheExceptionHandler();
/**
* Register a {@link 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, {@link net.sf.ehcache.loader.CacheLoader#init 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
*
* @param cacheLoader A Cache Loader to register
* @since While the javadoc has changed in 2.5.2, the behavior has not.
*/
public void registerCacheLoader(CacheLoader cacheLoader);
/**
* Unregister a {@link CacheLoader} with the cache. It will then be detached from the cache lifecycle.
*
* @param cacheLoader A Cache Loader to unregister
*/
public void unregisterCacheLoader(CacheLoader cacheLoader);
/**
*
* @return the cache loaders as a live list
*/
public List getRegisteredCacheLoaders();
/**
* Allows user to register a dynamic attribute extractor with a searchable cache that is dynamically indexable,
* as indicated by its configuration. Calling this method on such a cache is optional, but doing so more than once
* replaces previously registered extractor with the given one; i.e., there can be at most one extractor instance
* configured for each such cache. If the cache was not configured for dynamic indexing, an exception will be thrown
* @param extractor
*/
public void registerDynamicAttributesExtractor(DynamicAttributesExtractor extractor);
/**
* Register the {@link CacheWriter} for this cache. It will then be tied into the cache lifecycle.
*
* If the {@code CacheWriter} is not initialised, initialise it.
*
* @param cacheWriter A CacheWriter to register
*/
public void registerCacheWriter(CacheWriter cacheWriter);
/**
* Unregister the {@link CacheWriter} from the cache. It will then be detached from the cache lifecycle.
*
* If not {@code CacheWriter} was registered beforehand this operation has no effect.
*/
public void unregisterCacheWriter();
/**
* Retrieves the {@link CacheWriter} that was registered for this cache.
*
* @return the registered {@code CacheWriter}; or {@code null} if none was registered before
*/
public CacheWriter getRegisteredCacheWriter();
/**
* 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.
*
* @param key key whose associated value is to be returned.
* @param loader the override loader to use. If null, the cache's default loader will be used
* @param loaderArgument an argument to pass to the CacheLoader.
* @return an element if it existed or could be loaded, otherwise null
* @throws CacheException
*/
public Element getWithLoader(Object key, CacheLoader loader, 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 {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
* @param keys a collection of keys to be returned/loaded
* @param loaderArgument an argument to pass to the CacheLoader.
* @return a Map populated from the Cache. If there are no elements, an empty Map is returned.
* @throws CacheException
*/
public Map getAllWithLoader(Collection keys, Object loaderArgument) 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 {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
*
* @param key key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it.
* @throws CacheException
*/
public void load(final Object key) 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 {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
*/
public void loadAll(final Collection keys, final Object argument) throws CacheException;
/**
* Whether this cache is disabled. "Disabled" means:
*
* - bootstrap is disabled
*
- puts are discarded
*
- putQuites are discarded
*
* In all other respects the cache continues as it is.
*
* You can disable and enable a cache programmatically through the {@link #setDisabled(boolean)} method.
*
* @return true if the cache is disabled.
*/
public boolean isDisabled();
/**
* Disables or enables this cache. This call overrides the previous value of disabled.
*
* @param disabled true if you wish to disable, false to enable
* @see #isDisabled()
*/
public void setDisabled(boolean disabled);
/**
* This should not be used
* return some internal context (generally will be null)
*/
Object getInternalContext();
/**
* 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.
*/
public void disableDynamicFeatures();
/**
* Obtain the writer manager that's used by this cache instance.
*
* @return the writer manager that's set up for this cache
*/
public CacheWriterManager getWriterManager();
/**
* Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.
*
* It applies to coherent clustering mechanisms only e.g. Terracotta
*
* @return true if the cache is in coherent mode cluster-wide, false otherwise
* @deprecated Use {@link #isClusterBulkLoadEnabled()} instead
*/
@Deprecated
public boolean isClusterCoherent() throws TerracottaNotRunningException;
/**
* 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
*
* @return true if the cache is in coherent mode cluster-wide, false otherwise
* @deprecated Use {@link #isNodeBulkLoadEnabled()} instead
*/
@Deprecated
public boolean isNodeCoherent() throws TerracottaNotRunningException;
/**
* Sets the cache in coherent or incoherent mode depending on the parameter on this node.
* Calling {@code setNodeCoherent(true)} when the cache is already in coherent mode or
* calling {@code 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
* {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the config.
*
* @param coherent
* true transitions to coherent mode, false to incoherent mode
* @throws UnsupportedOperationException if this cache does not support coherence, like RMI replication
* @deprecated Use {@link #setNodeBulkLoadEnabled(boolean)} instead
*/
@Deprecated
public void setNodeCoherent(boolean coherent) throws UnsupportedOperationException, TerracottaNotRunningException;
/**
* 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
* @deprecated Use {@link #waitUntilClusterBulkLoadComplete()} instead
*/
@Deprecated
public void waitUntilClusterCoherent() throws UnsupportedOperationException, TerracottaNotRunningException;
/**
* This class is used to access the transaction manager used during XA.
* @param transactionManagerLookup
*/
public void setTransactionManagerLookup(TransactionManagerLookup transactionManagerLookup);
/**
* Add a PropertyChangeListener.
*
* @param listener
*/
public void addPropertyChangeListener(PropertyChangeListener listener);
/**
* Remove a PropertyChangeListener.
*
* @param listener
*/
public void removePropertyChangeListener(PropertyChangeListener listener);
/**
* Retrieve the given named search attribute
*
* @param
* type of the attribute
* @param attributeName
* the name of the attribute to retrieve
* @throws CacheException
* if no such attribute is defined for the given name
* @return the search attribute
*/
public Attribute getSearchAttribute(String attributeName) throws CacheException;
/**
* @return set of all search attributes in effect at the time of calling this method
* @throws CacheException
*/
public Set getSearchAttributes() throws CacheException;
/**
* Create a new query builder for this cache
*
* @return a new query builder
*/
public Query createQuery();
/**
* Is this cache searchable?
*
* @return true if this cache is searchable
*/
public boolean isSearchable();
/**
* Acquires the proper read lock for a given cache key
*
* @param key - The key that retrieves a value that you want to protect via locking
*/
public void acquireReadLockOnKey(Object key);
/**
* Acquires the proper write lock for a given cache key
*
* @param key - The key that retrieves a value that you want to protect via locking
*/
public void acquireWriteLockOnKey(Object key);
/**
* 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
*
* @param key - The key that retrieves a value that you want to protect via locking
* @param timeout - millis until giveup on getting the lock
* @return whether the lock was awarded
* @throws InterruptedException
*/
public boolean tryReadLockOnKey(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
*
* @param key - The key that retrieves a value that you want to protect via locking
* @param timeout - millis until giveup on getting the lock
* @return whether the lock was awarded
* @throws InterruptedException
*/
public boolean tryWriteLockOnKey(Object key, long timeout) throws InterruptedException;
/**
* Release a held read lock for the passed in key
*
* @param key - The key that retrieves a value that you want to protect via locking
*/
public void releaseReadLockOnKey(Object key);
/**
* Release a held write lock for the passed in key
*
* @param key - The key that retrieves a value that you want to protect via locking
*/
public void releaseWriteLockOnKey(Object key);
/**
* Returns true if a read lock for the key is held by the current thread
*
* @param key
* @return 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
*/
boolean isReadLockedByCurrentThread(Object key) throws UnsupportedOperationException;
/**
* Returns true if a write lock for the key is held by the current thread
*
* @param key
* @return 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
*/
boolean isWriteLockedByCurrentThread(Object key) throws UnsupportedOperationException;
/**
* Returns true if at least one node in the cluster is in bulk-load mode. Returns false otherwise.
*
* NOTE: if {@link #isNodeBulkLoadEnabled()} returns true, this method will always return true.
* Applies to caches clustered with Terracotta only.
*
* @throws UnsupportedOperationException if the cache is not clustered with Terracotta
* @return true if the cache is in bulk-load mode cluster-wide, false otherwise
*/
public boolean isClusterBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException;
/**
* Returns true if the current node is in bulk-load mode. Returns false otherwise.
*
* NOTE: if this method returns true, {@link #isClusterBulkLoadEnabled()} method will always return true.
* Applies to caches clustered with Terracotta only.
*
* @throws UnsupportedOperationException if the cache is not clustered with Terracotta
* @return true if the cache is in coherent mode cluster-wide, false otherwise
*/
public boolean isNodeBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException;
/**
* Enable/disable bulk-load mode in this node for this cache.
* Calling {@code setBulkLoadEnabled(true)} when the cache is already in bulk-load mode or
* calling {@code 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
* {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
*
* @param enabledBulkLoad
* true enables bulk-load, false disables it if not already disabled
* @throws UnsupportedOperationException if the cache is not clustered with Terracotta
*/
public void setNodeBulkLoadEnabled(boolean enabledBulkLoad) 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
*/
public void waitUntilClusterBulkLoadComplete() throws UnsupportedOperationException, TerracottaNotRunningException;
}