org.apache.jcs.auxiliary.disk
Class AbstractDiskCache

java.lang.Object
  org.apache.jcs.auxiliary.disk.AbstractDiskCache

All Implemented Interfaces:

java.io.Serializable, AuxiliaryCache, ICache, ICacheType

Direct Known Subclasses:

BlockDiskCache, IndexedDiskCache, JDBCDiskCache

public abstract class AbstractDiskCache
extends java.lang.Object
implements AuxiliaryCache, java.io.Serializable

Abstract class providing a base implementation of a disk cache, which can be easily extended to implement a disk cache for a specific perstistence mechanism.

When implementing the abstract methods note that while this base class handles most things, it does not acquire or release any locks. Implementations should do so as neccesary. This is mainly done to minimize the time speant in critical sections.

Error handling in this class needs to be addressed. Currently if an exception is thrown by the persistence mechanism, this class destroys the event queue. Should it also destory purgatory? Should it dispose itself?

See Also:

Serialized Form

Field Summary

protected boolean	alive Indicates whether the cache is 'alive', defined as having been initialized, but not yet disposed.
protected ICacheEventQueue	cacheEventQueue The CacheEventQueue where changes will be queued for asynchronous updating of the persistent storage.
protected java.lang.String	cacheName Every cache will have a name, subclasses must set this when they are initialized.
protected java.util.Map	purgatory Map where elements are stored between being added to this cache and actually spooled to disk.
protected int	purgHits DEBUG: Keeps a count of the number of purgatory hits for debug messages

Fields inherited from interface org.apache.jcs.engine.behavior.ICacheType

CACHE_HUB, DISK_CACHE, LATERAL_CACHE, REMOTE_CACHE

Constructor Summary

AbstractDiskCache(IDiskCacheAttributes attr)
Construc the abstract disk cache, create event queues and purgatory.

Method Summary

void	dispose() Adds a dispose request to the disk cache.
protected abstract void	doDispose() Dispose of the persistent store.
protected abstract ICacheElement	doGet(java.io.Serializable key) Get a value from the persistent store.
protected abstract boolean	doRemove(java.io.Serializable key) Remove an object from the persistent store if found.
protected abstract void	doRemoveAll() Remove all objects from the persistent store.
protected abstract void	doUpdate(ICacheElement element) Add a cache element to the persistent store.
ICacheElement	get(java.io.Serializable key) Check to see if the item is in purgatory.
java.lang.String	getCacheName() Returns the cache name.
int	getCacheType() Returns the cache type.
abstract java.util.Set	getGroupKeys(java.lang.String groupName) The keys in a group.
abstract int	getSize() Size cannot be determined without knowledge of the cache implementation, so subclasses will need to implement this method.
IStats	getStatistics() Returns semi-structured data.
java.lang.String	getStats() Gets basic stats for the abstract disk cache.
int	getStatus() Returns the cache status.
boolean	remove(java.io.Serializable key) Removes are not queued.
void	removeAll() Removes all cached items from the cache.
void	update(ICacheElement cacheElement) Adds the provided element to the cache.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.jcs.auxiliary.AuxiliaryCache

getAuxiliaryCacheAttributes

Field Detail

purgatory

protected java.util.Map purgatory

Map where elements are stored between being added to this cache and actually spooled to disk. This allows puts to the disk cache to return quickly, and the more expensive operation of serializing the elements to persistent storage queued for later.

If the elements are pulled into the memory cache while the are still in purgatory, writing to disk can be cancelled.

cacheEventQueue

protected ICacheEventQueue cacheEventQueue

The CacheEventQueue where changes will be queued for asynchronous updating of the persistent storage.

alive

protected boolean alive

Indicates whether the cache is 'alive', defined as having been initialized, but not yet disposed.

cacheName

protected java.lang.String cacheName

Every cache will have a name, subclasses must set this when they are initialized.

purgHits

protected int purgHits

DEBUG: Keeps a count of the number of purgatory hits for debug messages

Constructor Detail

AbstractDiskCache

public AbstractDiskCache(IDiskCacheAttributes attr)

Construc the abstract disk cache, create event queues and purgatory.

Parameters:

attr -

Method Detail

update

public final void update(ICacheElement cacheElement)
                  throws java.io.IOException

Adds the provided element to the cache. Element will be added to purgatory, and then queued for later writing to the serialized storage mechanism.

An update results in a put event being created. The put event will call the handlePut method defined here. The handlePut method calls the implemented doPut on the child.

Specified by:

update in interface AuxiliaryCache

Specified by:

update in interface ICache

Parameters:

cacheElement -

Throws:

java.io.IOException

See Also:

ICache.update(org.apache.jcs.engine.behavior.ICacheElement)

get

public final ICacheElement get(java.io.Serializable key)

Check to see if the item is in purgatory. If so, return it. If not, check to see if we have it on disk.

Specified by:

get in interface AuxiliaryCache

Specified by:

get in interface ICache

Parameters:

key -

Returns:

ICacheElement or null

See Also:

AuxiliaryCache.get(java.io.Serializable)

getGroupKeys

public abstract java.util.Set getGroupKeys(java.lang.String groupName)

The keys in a group.

(non-Javadoc)

Specified by:

getGroupKeys in interface AuxiliaryCache

Returns:

a set of group keys

See Also:

AuxiliaryCache.getGroupKeys(java.lang.String)

remove

public final boolean remove(java.io.Serializable key)

Removes are not queued. A call to remove is immediate.

Specified by:

remove in interface AuxiliaryCache

Specified by:

remove in interface ICache

Parameters:

key -

Returns:

whether the item was present to be removed.

See Also:

ICache.remove(java.io.Serializable)

removeAll

public final void removeAll()

Description copied from interface: AuxiliaryCache

Removes all cached items from the cache.

Specified by:

removeAll in interface AuxiliaryCache

Specified by:

removeAll in interface ICache

See Also:

ICache.removeAll()

dispose

public final void dispose()

Adds a dispose request to the disk cache.

Disposal proceeds in several steps.

1. Prior to this call the Composite cache dumped the memory into the disk cache. If it is large then we need to wait for the event queue to finish.
2. Wait until the event queue is empty of until the configured ShutdownSpoolTimeLimit is reached.
3. Call doDispose on the concrete impl.

Specified by:

dispose in interface AuxiliaryCache

Specified by:

dispose in interface ICache

getCacheName

public java.lang.String getCacheName()

Description copied from interface: AuxiliaryCache

Returns the cache name.

Specified by:

getCacheName in interface AuxiliaryCache

Specified by:

getCacheName in interface ICache

Returns:

the region name.

See Also:

ICache.getCacheName()

getStats

public java.lang.String getStats()

Gets basic stats for the abstract disk cache.

Specified by:

getStats in interface ICache

Returns:

String

getStatistics

public IStats getStatistics()

Returns semi-structured data.

Specified by:

getStatistics in interface AuxiliaryCache

Returns:

See Also:

AuxiliaryCache.getStatistics()

getStatus

public int getStatus()

Description copied from interface: AuxiliaryCache

Returns the cache status.

Specified by:

getStatus in interface AuxiliaryCache

Specified by:

getStatus in interface ICache

Returns:

the status -- alive or disposed from CacheConstants

See Also:

ICache.getStatus()

getSize

public abstract int getSize()

Size cannot be determined without knowledge of the cache implementation, so subclasses will need to implement this method.

Specified by:

getSize in interface AuxiliaryCache

Specified by:

getSize in interface ICache

Returns:

the number of items.

See Also:

ICache.getSize()

getCacheType

public int getCacheType()

Description copied from interface: ICacheType

Returns the cache type.

Specified by:

getCacheType in interface ICacheType

Returns:

Always returns DISK_CACHE since subclasses should all be of that type.

See Also:

ICacheType.getCacheType()

doGet

protected abstract ICacheElement doGet(java.io.Serializable key)

Get a value from the persistent store.

Parameters:

key - Key to locate value for.

Returns:

An object matching key, or null.

doUpdate

protected abstract void doUpdate(ICacheElement element)

Add a cache element to the persistent store.

Parameters:

element -

doRemove

protected abstract boolean doRemove(java.io.Serializable key)

Remove an object from the persistent store if found.

Parameters:

key - Key of object to remove.

Returns:

whether or no the item was present when removed

doRemoveAll

protected abstract void doRemoveAll()

Remove all objects from the persistent store.

doDispose

protected abstract void doDispose()

Dispose of the persistent store. Note that disposal of purgatory and setting alive to false does NOT need to be done by this method.