Package net.sf.basedb.util
Class StaticCache
java.lang.Object
net.sf.basedb.util.StaticCache
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) $
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A timer task that clean up the cache when it is executed.(package private) static class
Keeps track of a locked cached entry.(package private) static class
A lock-safe input stream that releases the associated read lock when the stream is closed.(package private) static class
A lock-safe output stream that releases the associated write lock when the stream is closed.(package private) static class
Inner class for performing the actual release of locks and closing of streams (in/out). -
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprivate 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.cleanUpTask
(FileFilter filter) Creates a task that cleans up this cache when it is executed.boolean
Deletes an object from the cache.boolean
Checks if a cache entry exists or not.private File
fileFromKey
(String key) 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
Check if the cache has been disabled.static boolean
isValidKey
(String key) Checks if the given key is a vilid cache entry key.<T> T
Read a serializable object from the cache.<T> T
load
(String key, ClassLoader loader, int timeout) 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.olderThan
(long age) Creates a file filter that matches all files that are older than the specified age.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
Checks the size (in bytes) of a cache entry.boolean
Store a serializable object in the cache.private void
validateKey
(String key) Get an output stream that can be used to write binary information to the cache.long
write
(String key, InputStream in, int timeout) Store binary information in the cache.
-
Field Details
-
validKey
-
log
Log static cache events. -
root
-
rootPath
-
locks
-
disabled
private boolean disabled
-
-
Constructor Details
-
StaticCache
Creates a new static cache.- Parameters:
root
- A directory were the cache stores it's files
-
-
Method Details
-
isValidKey
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
Convert a possible invalid cache key to a valid one by replacing invalid characters with the replacement string.- Parameters:
key
- The (possible invalid) cache keyreplacement
- 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
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
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:
-
cleanUpTask
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:
-
exists
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
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
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 keyin
- An input stream to read fromtimeout
- A timeout in milliseconds to wait for a write lock on the requested cache entry- Returns:
- The number of bytes written
- Throws:
IOException
-
write
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 keytimeout
- 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
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 keyout
- An output stream to write the cache contents totimeout
- A timeout in milliseconds to wait for a read lock on the requested cache entry- Returns:
- The number of bytes copied
- Throws:
IOException
-
read
Get an input stream for reading binary information from the cache.- Parameters:
key
- The cache keytimeout
- 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
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 keyobject
- The object to store in the cache, it must be aSerializable
objecttimeout
- 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
Read a serializable object from the cache.- Parameters:
key
- The cache keytimeout
- 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
-
delete
Deletes an object from the cache.- Parameters:
key
- The cache keytimeout
- 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
-
fileFromKey
-
getInputStream
Get a lock-safe input stream.- Throws:
IOException
-
getOutputStream
Get a lock-safe output stream.- Throws:
IOException
-
aquireLock
Aquire a read or write lock on a given cache entry.- Returns:
- A lock manager or null if the lock could not be aquired
-