org.apache.jcs.auxiliary.disk
Class AbstractDiskCache

java.lang.Object
  extended byorg.apache.jcs.auxiliary.disk.AbstractDiskCache
All Implemented Interfaces:
AuxiliaryCache, ICache, ICacheType, java.io.Serializable
Direct Known Subclasses:
HSQLCache, IndexedDiskCache, JISPCache

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?

Version:
$Id: AbstractDiskCache.java,v 1.17 2003/08/22 11:57:18 mpoeschl Exp $
Author:
Aaron Smuts, James Taylor
See Also:
Serialized Form

Nested Class Summary
private  class AbstractDiskCache.MyCacheListener
          Cache that implements the CacheListener interface, and calls appropriate methods in its parent class.
 
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  ReadWriteLock lock
          Each instance of a Disk cache should use this lock to synchronize reads and writes to the underlying storage mechansism.
protected  ReadWriteLockManager locker
          Manages locking for purgatory item manipulation.
private static org.apache.commons.logging.Log log
           
protected  java.util.Hashtable 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(java.lang.String cacheName)
           
 
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)
          Gets an item from the cache.
 java.lang.String getCacheName()
          Returns the cache name.
 int getCacheType()
          Returns the cache type.
abstract  java.util.Set getGroupKeys(java.lang.String groupName)
          Gets the set of keys of objects currently in the group
abstract  int getSize()
          Size cannot be determined without knowledge of the cache implementation, so subclasses will need to implement this method.
 int getStatus()
          Returns the cache status.
private  void releaseLock(java.lang.String id)
          Internally used write lock for purgatory item modification.
 boolean remove(java.io.Serializable key)
          Removes an item from the cache.
 void removeAll()
          Removes all cached items from the cache.
 void update(ICacheElement cacheElement)
          Adds the provided element to the cache.
private  void writeLock(java.lang.String id)
          Internally used write lock for purgatory item modification.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private static final org.apache.commons.logging.Log log

purgatory

protected java.util.Hashtable 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.


lock

protected ReadWriteLock lock
Each instance of a Disk cache should use this lock to synchronize reads and writes to the underlying storage mechansism.


locker

protected ReadWriteLockManager locker
Manages locking for purgatory item manipulation.


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(java.lang.String cacheName)
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.

Specified by:
update in interface AuxiliaryCache
Throws:
java.io.IOException
See Also:
ICache.update(org.apache.jcs.engine.behavior.ICacheElement)

get

public final ICacheElement get(java.io.Serializable key)
Description copied from interface: AuxiliaryCache
Gets an item from the cache.

Specified by:
get in interface AuxiliaryCache
See Also:
AuxiliaryCache.get(java.io.Serializable)

getGroupKeys

public abstract java.util.Set getGroupKeys(java.lang.String groupName)
Description copied from interface: AuxiliaryCache
Gets the set of keys of objects currently in the group

Specified by:
getGroupKeys in interface AuxiliaryCache

remove

public final boolean remove(java.io.Serializable key)
Description copied from interface: AuxiliaryCache
Removes an item from the cache.

Specified by:
remove in interface AuxiliaryCache
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
See Also:
ICache.removeAll()

dispose

public final void dispose()
Adds a dispose request to the disk cache.

Specified by:
dispose in interface AuxiliaryCache

getCacheName

public java.lang.String getCacheName()
Description copied from interface: AuxiliaryCache
Returns the cache name.

Specified by:
getCacheName in interface AuxiliaryCache
See Also:
ICache#getCacheName

getStatus

public int getStatus()
Description copied from interface: AuxiliaryCache
Returns the cache status.

Specified by:
getStatus in interface AuxiliaryCache
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
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()

writeLock

private void writeLock(java.lang.String id)
Internally used write lock for purgatory item modification.

Parameters:
id - What name to lock on.

releaseLock

private void releaseLock(java.lang.String id)
Internally used write lock for purgatory item modification.

Parameters:
id - What name to lock on.

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.


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.

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.