Package org.apache.commons.jcs3.auxiliary.disk

Class AbstractDiskCache<K,V>

java.lang.Object
org.apache.commons.jcs3.auxiliary.AbstractAuxiliaryCache<K,V>
org.apache.commons.jcs3.auxiliary.AbstractAuxiliaryCacheEventLogging<K,V>
org.apache.commons.jcs3.auxiliary.disk.AbstractDiskCache<K,V>
All Implemented Interfaces:
AuxiliaryCache<K,V>, ICache<K,V>, ICacheType
Direct Known Subclasses:
BlockDiskCache, IndexedDiskCache, JDBCDiskCache
public abstract class AbstractDiskCache<K,V> extends AbstractAuxiliaryCacheEventLogging<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?

  • Constructor Details

    • AbstractDiskCache

      protected 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 -

  • Method Details

    • isAlive

      public boolean isAlive()
      Returns:
      true if the cache is alive

    • setAlive

      public void setAlive(boolean alive)
      Parameters:
      alive - set the alive status

    • 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,V>
      Overrides:
      update in class AbstractAuxiliaryCacheEventLogging<K,V>
      Parameters:
      cacheElement -
      Throws:
      IOException
      See Also:

    • 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,V>
      Overrides:
      get in class AbstractAuxiliaryCacheEventLogging<K,V>
      Parameters:
      key -
      Returns:
      ICacheElement<K, V> or null
      See Also:

    • 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,V>
      Overrides:
      getMatching in class AbstractAuxiliaryCacheEventLogging<K,V>
      Parameters:
      pattern -
      Returns:
      a map of K key to ICacheElement<K, V> element, or an empty map if there is no data matching the pattern.
      Throws:
      IOException

    • getKeySet

      public abstract Set<K> getKeySet() throws IOException
      The keys in the cache.
      Returns:
      a set of the key type TODO This should probably be done in chunks with a range passed in. This will be a problem if someone puts a 1,000,000 or so items in a region.
      Throws:
      IOException - if access to the auxiliary cache fails
      See Also:

    • 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,V>
      Overrides:
      remove in class AbstractAuxiliaryCacheEventLogging<K,V>
      Parameters:
      key -
      Returns:
      whether the item was present to be removed.
      Throws:
      IOException
      See Also:

    • 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,V>
      Overrides:
      removeAll in class AbstractAuxiliaryCacheEventLogging<K,V>
      Throws:
      IOException
      See Also:

    • 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,V>
      Overrides:
      dispose in class AbstractAuxiliaryCacheEventLogging<K,V>
      Throws:
      IOException

    • getCacheName

      public String getCacheName()
      Description copied from interface: ICache
      Returns the cache name.
      Returns:
      the region name.
      See Also:

    • getStats

      public String getStats()
      Gets basic stats for the abstract disk cache.
      Returns:
      String

    • getStatistics

      public IStats getStatistics()
      Returns semi-structured data.
      Returns:
      the historical and statistical data for a region's auxiliary cache.
      See Also:

    • getStatus

      public CacheStatus getStatus()
      Description copied from interface: ICache
      Returns the cache status.
      Returns:
      the status -- alive or disposed from CacheConstants
      See Also:

    • getSize

      public abstract int getSize()
      Size cannot be determined without knowledge of the cache implementation, so subclasses will need to implement this method.
      Returns:
      the number of items.
      See Also:

    • getCacheType

      public ICacheType.CacheType getCacheType()
      Description copied from interface: ICacheType
      Returns the cache type.

      Returns:
      Always returns DISK_CACHE since subclasses should all be of that type.
      See Also:

    • 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,V>
      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.