Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/**
* Copyright 2003-2006 Greg Luck
*
* 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 net.sf.ehcache.event.RegisteredEventListeners;
import net.sf.ehcache.store.MemoryStoreEvictionPolicy;
import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
import java.io.Serializable;
import java.util.List;
/**
* 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 181 2006-08-27 22:42:39Z gregluck $
*/
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;
/**
* 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;
/**
* 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 peak 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 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
*/
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). On a single cpu 1.8Ghz P4, approximately 8ms is required
* for each 1000 entries.
*
* @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.
*
* 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 {@link #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.
*
* @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}
*/
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, 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}
*/
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 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}
* @noinspection SameParameterValue
*/
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 all cached items.
*
* @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
*/
void removeAll() throws IllegalStateException, CacheException;
/**
* Removes all cached items.
* @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.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.
*
* @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
*/
long calculateInMemorySize() throws IllegalStateException, CacheException;
/**
* 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}
*/
long getMemoryStoreSize() 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}
*/
int getDiskStoreSize() throws IllegalStateException;
/**
* Gets the status attribute of the Cache.
*
* @return The status value from the Status enum class
*/
Status getStatus();
/**
* The number of times a requested item was found in the cache.
*
* @return the number of times a requested item was found in the cache
*/
int getHitCount();
/**
* Number of times a requested item was found in the Memory Store.
*
* @return Number of times a requested item was found in the Memory Store.
*/
int getMemoryStoreHitCount();
/**
* Number of times a requested item was found in the Disk Store.
*/
int getDiskStoreHitCount();
/**
* Number of times a requested element was not found in the cache. This
* may be because it expired, in which case this will also be recorded in {@link #getMissCountExpired},
* or because it was simply not there.
*/
int getMissCountNotFound();
/**
* Number of times a requested element was found but was expired.
*/
int getMissCountExpired();
/**
* 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);
/**
* Gets timeToIdleSeconds.
*/
long getTimeToIdleSeconds();
/**
* Gets timeToLiveSeconds.
*/
long getTimeToLiveSeconds();
/**
* Are elements eternal.
*/
boolean isEternal();
/**
* Does the overflow go to disk.
*/
boolean isOverflowToDisk();
/**
* Gets the maximum number of elements to hold in memory.
*/
int getMaxElementsInMemory();
/**
* The policy used to evict elements from the {@link net.sf.ehcache.store.MemoryStore}.
* This can be one of:
*
*
LRU - least recently used
*
LFU - least frequently used
*
FIFO - first in first out, the oldest element by creation time
*
* The default value is LRU
*
* @since 1.2
*/
MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy();
/**
* 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.
*
*
* @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.LruMemoryStore} or {@link net.sf.ehcache.store.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;
/**
* @return true if the cache overflows to disk and the disk is persistent between restarts
*/
boolean isDiskPersistent();
/**
* @return the interval between runs
* of the expiry thread, where it checks the disk store for expired elements. It is not the
* the timeToLiveSeconds.
*/
long getDiskExpiryThreadIntervalSeconds();
/**
* 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.
*
* @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.
*
* @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.
*
* @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.
*
* @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();
/**
* Resets statistics counters back to 0.
*/
void clearStatistics();
/**
* Accurately measuring statistics can be expensive. Returns the current accuracy setting.
*
* @return one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
*/
public int getStatisticsAccuracy();
/**
* Sets the statistics accuracy.
*
* @param statisticsAccuracy one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
*/
public void setStatisticsAccuracy(int statisticsAccuracy);
/**
* Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
*/
void evictExpiredElements();
/**
* An inexpensive check to see if the key exists in the cache.
*
* @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.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}
*/
Statistics 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;
/**
* DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
*
* @param diskStorePath the new path to be used.
* @throws CacheException if this method is called after the cache is initialized
*/
void setDiskStorePath(String diskStorePath) throws CacheException;
/**
* Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or a {@link net.sf.ehcache.store.DiskStore}.
*
* This method creates those and makes the cache ready to accept elements
*/
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.
*/
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;
}
