org.apache.jcs.auxiliary.disk
Class AbstractDiskCache<K extends Serializable,V extends Serializable>

java.lang.Object
  org.apache.jcs.auxiliary.AbstractAuxiliaryCache<K,V>
      org.apache.jcs.auxiliary.AbstractAuxiliaryCacheEventLogging<K,V>
          org.apache.jcs.auxiliary.disk.AbstractDiskCache<K,V>

All Implemented Interfaces:

AuxiliaryCache<K,V>, ICache<K,V>, ICacheType

Direct Known Subclasses:

BlockDiskCache, FileDiskCache, IndexedDiskCache, JDBCDiskCache

public abstract class AbstractDiskCache<K extends Serializable,V extends Serializable>
extends AbstractAuxiliaryCacheEventLogging<K,V>
implements AuxiliaryCache<K,V>

Abstract class providing a base implementation of a disk cache, which can be easily extended to implement a disk cache for a specific persistence 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 necessary. This is mainly done to minimize the time spent 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 destroy purgatory? Should it dispose itself?

log

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

The logger

purgatory

protected Map<K extends Serializable,PurgatoryElement<K extends Serializable,V extends Serializable>> 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 canceled.

cacheEventQueue

protected ICacheEventQueue<K extends Serializable,V extends Serializable> 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': initialized, but not yet disposed. Child classes must set this to true.

cacheName

protected 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

removeAllLock

protected final ReentrantReadWriteLock removeAllLock

We lock here, so that we cannot get an update after a remove all. an individual removal locks the item.

AbstractDiskCache

public AbstractDiskCache(IDiskCacheAttributes attr)

Construct the abstract disk cache, create event queues and purgatory. Child classes should set the alive flag to true after they are initialized.

Parameters:

attr -

update

public final void update(ICacheElement<K,V> cacheElement)
                  throws 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 ICache<K extends Serializable,V extends Serializable>

Overrides:

update in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

cacheElement -

Throws:

IOException

See Also:

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

get

public final ICacheElement<K,V> get(K 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 ICache<K extends Serializable,V extends Serializable>

Overrides:

get in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

key -

Returns:

ICacheElement or null

See Also:

ICache.get(K)

getMatching

public Map<K,ICacheElement<K,V>> getMatching(String pattern)
                                                                                                     throws IOException

Gets items from the cache matching the given pattern. Items from memory will replace those from remote sources.

This only works with string keys. It's too expensive to do a toString on every key.

Auxiliaries will do their best to handle simple expressions. For instance, the JDBC disk cache will convert * to % and . to _

Specified by:

getMatching in interface ICache<K extends Serializable,V extends Serializable>

Overrides:

getMatching in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

pattern -

Returns:

a map of K key to ICacheElement element, or an empty map if there is no data matching the pattern.

Throws:

IOException

processGetMultiple

public Map<K,ICacheElement<K,V>> processGetMultiple(Set<K> keys)

Gets multiple items from the cache based on the given set of keys.

Specified by:

processGetMultiple in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

keys -

Returns:

a map of K key to ICacheElement element, or an empty map if there is no data in cache for any of these keys

getGroupKeys

public abstract Set<K> getGroupKeys(String groupName)

The keys in a group.

Specified by:

getGroupKeys in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Returns:

a set of group keys

See Also:

AuxiliaryCache.getGroupKeys(java.lang.String)

getGroupNames

public abstract Set<String> getGroupNames()

The group names in the cache.

Specified by:

getGroupNames in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Returns:

a set of group names

See Also:

AuxiliaryCache.getGroupNames()

remove

public final boolean remove(K key)
                     throws IOException

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

Specified by:

remove in interface ICache<K extends Serializable,V extends Serializable>

Overrides:

remove in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Parameters:

key -

Returns:

whether the item was present to be removed.

Throws:

IOException

See Also:

ICache.remove(K)

removeAll

public final void removeAll()
                     throws IOException

Description copied from class: AbstractAuxiliaryCacheEventLogging

Removes all from the region. Wraps the removeAll in event logs.

Specified by:

removeAll in interface ICache<K extends Serializable,V extends Serializable>

Overrides:

removeAll in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Throws:

IOException

See Also:

ICache.removeAll()

dispose

public final void dispose()
                   throws IOException

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 ICache<K extends Serializable,V extends Serializable>

Overrides:

dispose in class AbstractAuxiliaryCacheEventLogging<K extends Serializable,V extends Serializable>

Throws:

IOException

getCacheName

public String getCacheName()

Description copied from interface: ICache

Returns the cache name.

Specified by:

getCacheName in interface ICache<K extends Serializable,V extends Serializable>

Returns:

the region name.

See Also:

ICache.getCacheName()

getStats

public String getStats()

Gets basic stats for the abstract disk cache.

Specified by:

getStats in interface ICache<K extends Serializable,V extends Serializable>

Returns:

String

getStatistics

public IStats getStatistics()

Returns semi-structured data.

Specified by:

getStatistics in interface AuxiliaryCache<K extends Serializable,V extends Serializable>

Returns:

the historical and statistical data for a region's auxiliary cache.

See Also:

AuxiliaryCache.getStatistics()

getStatus

public CacheStatus getStatus()

Description copied from interface: ICache

Returns the cache status.

Specified by:

getStatus in interface ICache<K extends Serializable,V extends Serializable>

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 ICache<K extends Serializable,V extends Serializable>

Returns:

the number of items.

See Also:

ICache.getSize()

getCacheType

public ICacheType.CacheType 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 final ICacheElement<K,V> doGet(K key)
                                                                            throws IOException

Get a value from the persistent store.

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Parameters:

key - Key to locate value for.

Returns:

An object matching key, or null.

Throws:

IOException

doGetMatching

protected final Map<K,ICacheElement<K,V>> doGetMatching(String pattern)
                                                                                                                throws IOException

Get a value from the persistent store.

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Parameters:

pattern - Used to match keys.

Returns:

A map of matches..

Throws:

IOException

doUpdate

protected final void doUpdate(ICacheElement<K,V> cacheElement)
                       throws IOException

Add a cache element to the persistent store.

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Parameters:

cacheElement -

Throws:

IOException

doRemove

protected final boolean doRemove(K key)
                          throws IOException

Remove an object from the persistent store if found.

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Parameters:

key - Key of object to remove.

Returns:

whether or no the item was present when removed

Throws:

IOException

doRemoveAll

protected final void doRemoveAll()
                          throws IOException

Remove all objects from the persistent store.

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Throws:

IOException

doDispose

protected final void doDispose()
                        throws IOException

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

Before the event logging layer, the subclasses implemented the do* methods. Now the do* methods call the *EventLogging method on the super. The *WithEventLogging methods call the abstract process* methods. The children implement the process methods.

Throws:

IOException

getEventLoggingExtraInfo

public String getEventLoggingExtraInfo()

Gets the extra info for the event log.

Specified by:

getEventLoggingExtraInfo in class AbstractAuxiliaryCache<K extends Serializable,V extends Serializable>

Returns:

disk location

getDiskLocation

protected abstract String getDiskLocation()

This is used by the event logging.

Returns:

the location of the disk, either path or ip.