Package net.sf.basedb.util

Class StaticCache

java.lang.Object
net.sf.basedb.util.StaticCache
public class StaticCache
extends Object
A cache for storing data to files on the file system. The typical use case is to store data this is expensive to get from the database in a file for later retrieval. The cache can be used in streaming mode with the any of the read(String, int) or write(String, InputStream, int) methods and their variants. It can also be used to store any Serializable object with store(String, Object, int) and load(String, int).

In all cases the cached entry is identified by a key which is more or less directly translated to directories on the file system.

This class is thread-safe and can be used by multiple threads at the same time. Write requests to the same entry in the cache are allowed to one thread at a time. Any number of threads may read from the same cache entry as long as no thread is writing to that entry.

Version:
2.11
Author:
Nicklas
Last modified
$Date: 2019-05-22 08:31:13 +0200 (ons, 22 maj 2019) $

  • Field Details

    • validKey

      public static final Pattern validKey

    • log

      private static final org.slf4j.Logger log
      Log static cache events.

    • root

      private final File root

    • rootPath

      private final String rootPath

    • locks

      private final Map<String,​StaticCache.LockEntry> locks

    • disabled

      private boolean disabled

  • Constructor Details

    • StaticCache

      public StaticCache​(File root)
      Creates a new static cache.
      Parameters:
      root - A directory were the cache stores it's files

  • Method Details

    • isValidKey

      public static boolean isValidKey​(String key)
      Checks if the given key is a vilid cache entry key. Allowed characters are: any alphanumerical character + ./-
      Parameters:
      key - The key to check
      Returns:
      TRUE if the key is valid

    • makeValidKey

      public static String makeValidKey​(String key, String replacement)
      Convert a possible invalid cache key to a valid one by replacing invalid characters with the replacement string.
      Parameters:
      key - The (possible invalid) cache key
      replacement - The replacement string
      Returns:
      A valid cache key
      Since:
      2.13

    • isDisabled

      public boolean isDisabled()
      Check if the cache has been disabled. A disabled cache ignores all calls to read or write data.
      Returns:
      A boolean that is TRUE if the cache is disabled

    • setDisabled

      public void setDisabled​(boolean disabled)
      Disable or enable the cache.
      Parameters:
      disabled - TRUE if the cache should be disabled

    • cleanUp

      public void cleanUp​(FileFilter filter)
      Remove all files that matches the specified filter from the cache. This method is synchronized and can only be executed by one thread at a time.
      Parameters:
      filter - A file filter that matches the files to remove

    • olderThan

      public FileFilter olderThan​(long age)
      Creates a file filter that matches all files that are older than the specified age.
      Parameters:
      age - The age in milliseconds
      Returns:
      A file filter
      See Also:
      OlderThanFileFilter

    • cleanUpTask

      public TimerTask cleanUpTask​(FileFilter filter)
      Creates a task that cleans up this cache when it is executed.
      Parameters:
      filter - The file filter that determines which file that should be deleted
      Returns:
      A TimerTask object
      See Also:
      cleanUp(FileFilter)

    • exists

      public boolean exists​(String key)
      Checks if a cache entry exists or not.
      Parameters:
      key - The cache key
      Returns:
      TRUE if an extry exists, FALSE otherwise
      Since:
      2.13

    • size

      public long size​(String key)
      Checks the size (in bytes) of a cache entry.
      Parameters:
      key - The cache key
      Returns:
      The size in bytes, or -1 if the cache entry doesn't exists
      Since:
      2.13

    • write

      public long write​(String key, InputStream in, int timeout) throws IOException
      Store binary information in the cache. If the entry already exists, it is overwritten. If the entry is locked by other threads, this thread waits the specified number of milliseconds before returning.
      Parameters:
      key - The cache key
      in - An input stream to read from
      timeout - A timeout in milliseconds to wait for a write lock on the requested cache entry
      Returns:
      The number of bytes written
      Throws:
      IOException

    • write

      public OutputStream write​(String key, int timeout) throws IOException
      Get an output stream that can be used to write binary information to the cache. If the entry already exists, it is overwritten. If the entry is locked by other threads, this thread waits the specified number of milliseconds before giving up.

      NOTE! It is very important that the caller closes the output stream as soon as all data has been written to it. Failure to do so may result in locking the cache entry from reading by other threads.

      Parameters:
      key - The cache key
      timeout - A timeout in milliseconds to wait for a write lock on the requested cache entry
      Returns:
      An output stream, or null if a write lock could not be aquired
      Throws:
      IOException

    • read

      public long read​(String key, OutputStream out, int timeout) throws IOException
      Read binary information from the cache. The contents of the specified cache entry will be copied to the specified output stream.
      Parameters:
      key - The cache key
      out - An output stream to write the cache contents to
      timeout - A timeout in milliseconds to wait for a read lock on the requested cache entry
      Returns:
      The number of bytes copied
      Throws:
      IOException

    • read

      public InputStream read​(String key, int timeout) throws IOException
      Get an input stream for reading binary information from the cache.
      Parameters:
      key - The cache key
      timeout - A timeout in milliseconds to wait for a read lock on the requested cache entry
      Returns:
      An input stream or null if the cache entry doesn't exists or if a read lock could not be aquired
      Throws:
      IOException

    • store

      public boolean store​(String key, Object object, int timeout)
      Store a serializable object in the cache. If the entry already exists, it is overwritten. If the entry is locked by other threads, this thread waits the specified number of milliseconds before returning.
      Parameters:
      key - The cache key
      object - The object to store in the cache, it must be a Serializable object
      timeout - A timeout in milliseconds to wait for a write lock on the requested cache entry
      Returns:
      TRUE if the object could be stored, FALSE otherwise

    • load

      public <T> T load​(String key, int timeout)
      Read a serializable object from the cache.
      Parameters:
      key - The cache key
      timeout - A timeout in milliseconds to wait for a read lock on the requested cache entry
      Returns:
      The materialized object, or null if the cache entry doesn't exists or if a read lock couldn't be aquired

    • load

      public <T> T load​(String key, ClassLoader loader, int timeout)

    • delete

      public boolean delete​(String key, int timeout)
      Deletes an object from the cache.
      Parameters:
      key - The cache key
      timeout - A timeout in milliseconds to wait for a write lock on the requested cache entry
      Returns:
      TRUE if the cached object was deleted or if it didn't exist to begin with or if the static cache is disabled, FALSE is only returned if it is certain that the cached object still exists after this call
      Since:
      2.14

    • validateKey

      private void validateKey​(String key)

    • fileFromKey

      private File fileFromKey​(String key)

    • getInputStream

      private InputStream getInputStream​(String key, int timeout) throws IOException
      Get a lock-safe input stream.
      Throws:
      IOException

    • getOutputStream

      private OutputStream getOutputStream​(String key, int timeout) throws IOException
      Get a lock-safe output stream.
      Throws:
      IOException

    • aquireLock

      private StaticCache.LockEntry aquireLock​(String key, boolean writeLock, int timeout)
      Aquire a read or write lock on a given cache entry.
      Returns:
      A lock manager or null if the lock could not be aquired