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: 2010-08-13 10:50:27 +0200 (Fri, 13 Aug 2010) $

Nested Class Summary

static class	StaticCache.CleanupTask A timer task that clean up the cache when it is executed.
(package private) static class	StaticCache.LockEntry Keeps track of a locked cached entry.
(package private) static class	StaticCache.LockSafeInputStream A lock-safe input stream that releases the associated read lock when the stream is closed.
(package private) static class	StaticCache.LockSafeOutputStream A lock-safe output stream that releases the associated write lock when the stream is closed.

Field Summary

private boolean	disabled
private Map<String,StaticCache.LockEntry>	locks
private static Logger	log Log static cache events.
private File	root
static Pattern	validKey

Constructor Summary

StaticCache(File root)
Creates a new static cache.

Method Summary

private StaticCache.LockEntry	aquireLock(String key, boolean writeLock, int timeout) Aquire a read or write lock on a given cache entry.
void	cleanUp(FileFilter filter) Remove all files that matches the specified filter from the cache.
TimerTask	cleanUpTask(FileFilter filter) Creates a task that cleans up this cache when it is executed.
boolean	delete(String key, int timeout) Deletes an object from the cache.
boolean	exists(String key) Checks if a cache entry exists or not.
private InputStream	getInputStream(String key, int timeout) Get a lock-safe input stream.
private OutputStream	getOutputStream(String key, int timeout) Get a lock-safe output stream.
boolean	isDisabled() Check if the cache has been disabled.
static boolean	isValidKey(String key) Checks if the given key is a vilid cache entry key.
Object	load(String key, int timeout) Read a serializable object from the cache.
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.
FileFilter	olderThan(long age) Creates a file filter that matches all files that are older than the specified age.
InputStream	read(String key, int timeout) Get an input stream for reading binary information from the cache.
long	read(String key, OutputStream out, int timeout) Read binary information from the cache.
void	setDisabled(boolean disabled) Disable or enable the cache.
long	size(String key) Checks the size (in bytes) of a cache entry.
boolean	store(String key, Object object, int timeout) Store a serializable object in the cache.
private void	validateKey(String key)
long	write(String key, InputStream in, int timeout) Store binary information in the cache.
OutputStream	write(String key, int timeout) Get an output stream that can be used to write binary information to the cache.

Methods inherited from class java.lang.Object

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

Field Detail

validKey

public static final Pattern validKey

log

private static final Logger log

Log static cache events.

root

private final File root

locks

private final Map<String,StaticCache.LockEntry> locks

disabled

private boolean disabled

Constructor Detail

StaticCache

public StaticCache(File root)

Creates a new static cache.

Parameters:

root - A directory were the cache stores it's files

Method Detail

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

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)

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