net.sf.ehcache
Class Cache

java.lang.Object
  net.sf.ehcache.Cache

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class Cache

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

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

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

Cache is threadsafe.

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

Version:

$Id: Cache.java,v 1.18 2003/12/25 00:43:09 gregluck Exp $

Author:

Greg Luck

See Also:

Serialized Form

Field Summary

static java.lang.String	DEFAULT_CACHE_NAME A reserved word for cache names.
static int	STATUS_ALIVE The cache is alive.
static int	STATUS_DISPOSED The cache is uninitialised.
static int	STATUS_UNINITIALISED The cache is uninitialised.

Constructor Summary

Cache(java.lang.String name, int maximumSize, boolean overflowToDisk, boolean eternal, long timeToLive, long timeToIdle)
Full Constructor.

Method Summary

java.lang.Object	clone() Clones a cache.
(package private) void	dispose() Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
Element	get(java.io.Serializable key) Gets an element from the cache.
(package private) DiskStore	getDiskStore() Gets the internal DiskStore.
int	getDiskStoreHitCount() Number of times a requested item was found in the Disk Store
int	getDiskStoreSize() Returns the number of elements in the disk store.
int	getHitCount() Number of times a requested item was found in the cache
java.util.List	getKeys() Returns the keys of all elements in the cache The List returned is not live.
int	getMaxElementsInMemory() Gets the maximum number of elements to hold in memory
(package private) MemoryStore	getMemoryStore() Gets the internal MemoryStore.
int	getMemoryStoreHitCount() Number of times a requested item was found in the Memory Store
int	getMemoryStoreSize() Returns the number of elements in the memory store.
int	getMissCountExpired() Number of times a requested element was found but was expired
int	getMissCountNotFound() Number of times a requested element was not found in the cache.
java.lang.String	getName() Gets the cache name
int	getSize() Gets the size of the cache.
int	getStatus() Gets the status attribute of the Store object
long	getTimeToIdleSeconds() Gets timeToIdleSeconds
long	getTimeToLiveSeconds() Gets timeToLiveSeconds
(package private) void	initialise(Configuration configuration) Newly created caches do not have a MemoryStore or a DiskStore.
boolean	isEternal() Are elements eternal
boolean	isExpired(Element element) Checks whether this cache element has expired.
boolean	isOverflowToDisk() Does the overflow go to disk
void	put(Element element) Put an element in the cache.
boolean	remove(java.io.Serializable key) Removes an Element from the Cache.
void	removeAll() Removes all cached items.
(package private) void	setName(java.lang.String name) Sets the name
java.lang.String	toString() Returns a String representation of Cache

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_CACHE_NAME

public static final java.lang.String DEFAULT_CACHE_NAME

A reserved word for cache names. It denotes a default configuration which is applied to caches created without configuration.

See Also:

Constant Field Values

STATUS_UNINITIALISED

public static final int STATUS_UNINITIALISED

The cache is uninitialised. It cannot be used.

See Also:

Constant Field Values

STATUS_ALIVE

public static final int STATUS_ALIVE

The cache is alive. It can be used.

See Also:

Constant Field Values

STATUS_DISPOSED

public static final int STATUS_DISPOSED

The cache is uninitialised. It cannot be used.

See Also:

Constant Field Values

Constructor Detail

Cache

public Cache(java.lang.String name,
             int maximumSize,
             boolean overflowToDisk,
             boolean eternal,
             long timeToLive,
             long timeToIdle)

Full Constructor.

The Configurator and clients can create these.

A client can specify their own settings here and pass the Cache object into CacheManager.addCache(java.lang.String) to specify parameters other than the defaults.

Only the CacheManager can initialise them.

Method Detail

initialise

void initialise(Configuration configuration)

Newly created caches do not have a MemoryStore or a DiskStore.

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

put

public void put(Element element)
         throws java.lang.IllegalArgumentException,
                java.lang.IllegalStateException

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.

Parameters:

element -

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

java.lang.IllegalArgumentException - if the element is null

get

public Element get(java.io.Serializable key)
            throws java.lang.IllegalStateException,
                   CacheException

Gets an element from the cache.

Parameters:

key - a serializable value

Returns:

the element, or null, if it does not exist.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

CacheException

See Also:

isExpired(net.sf.ehcache.Element)

getKeys

public java.util.List getKeys()

Returns the keys of all elements in the cache The List returned is not live. It is a copy.

remove

public boolean remove(java.io.Serializable key)
               throws java.lang.IllegalStateException

Removes an Element from the Cache. 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:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

removeAll

public void removeAll()
               throws java.lang.IllegalStateException,
                      java.io.IOException

Removes all cached items.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

java.io.IOException

dispose

void dispose()
       throws java.lang.IllegalStateException

Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.

Should be invoked only by CacheManager.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getSize

public int getSize()
            throws java.lang.IllegalStateException

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 a more accurate number, force expiry by iterating through the getKeys() list and calling get on each key, before calling this method.

Returns:

The size value

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getMemoryStoreSize

public int getMemoryStoreSize()
                       throws java.lang.IllegalStateException

Returns the number of elements in the memory store.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getDiskStoreSize

public int getDiskStoreSize()
                     throws java.lang.IllegalStateException

Returns the number of elements in the disk store.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getStatus

public int getStatus()

Gets the status attribute of the Store object

Returns:

The status value

getHitCount

public int getHitCount()
                throws java.lang.IllegalStateException

Number of times a requested item was found in the cache

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getMemoryStoreHitCount

public int getMemoryStoreHitCount()
                           throws java.lang.IllegalStateException

Number of times a requested item was found in the Memory Store

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getDiskStoreHitCount

public int getDiskStoreHitCount()
                         throws java.lang.IllegalStateException

Number of times a requested item was found in the Disk Store

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getMissCountNotFound

public int getMissCountNotFound()
                         throws java.lang.IllegalStateException

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 getMissCountExpired(), or because it was simply not there.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getMissCountExpired

public int getMissCountExpired()
                        throws java.lang.IllegalStateException

Number of times a requested element was found but was expired

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getName

public java.lang.String getName()

Gets the cache name

setName

void setName(java.lang.String name)

Sets the name

getTimeToIdleSeconds

public long getTimeToIdleSeconds()

Gets timeToIdleSeconds

getTimeToLiveSeconds

public long getTimeToLiveSeconds()

Gets timeToLiveSeconds

isEternal

public boolean isEternal()

Are elements eternal

isOverflowToDisk

public boolean isOverflowToDisk()

Does the overflow go to disk

getMaxElementsInMemory

public int getMaxElementsInMemory()

Gets the maximum number of elements to hold in memory

toString

public java.lang.String toString()

Returns a String representation of Cache

isExpired

public boolean isExpired(Element element)
                  throws java.lang.IllegalStateException,
                         java.lang.NullPointerException

Checks whether this cache element has expired.

The element is expired if the :

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

Returns:

true if it has

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

java.lang.NullPointerException - if the element is null

clone

public java.lang.Object clone()
                       throws java.lang.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.

Returns:

an object of type Cache

Throws:

java.lang.CloneNotSupportedException

getDiskStore

DiskStore getDiskStore()
                 throws java.lang.IllegalStateException

Gets the internal DiskStore.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE

getMemoryStore

MemoryStore getMemoryStore()
                     throws java.lang.IllegalStateException

Gets the internal MemoryStore.

Throws:

java.lang.IllegalStateException - if the cache is not STATUS_ALIVE