org.wandora.modules.cache

Class DiskCacheModule

java.lang.Object

org.wandora.modules.AbstractModule

org.wandora.modules.cache.DiskCacheModule

All Implemented Interfaces:

CacheService, Module

public class DiskCacheModule
extends AbstractModule
implements CacheService

Stores cached content on a file system. The file names are MD5 hashes of the provided cache key. To avoid hash collisions, the key is stored at the start of each cache file and is checked when the cached input stream is returned. The returned input and output streams are at the position where the actual cached contents are read/written, that is, this class handles internally everything about the keys. Note that hash collisions should be extremely rare.

Use parameter name cacheDir in init options to set the directory where files are cached. maxCacheTime parameter can be used to set the maximum age of cached content. Any page that is older than that will not be returned from the cache. The time is given in milliseconds. Use 0 for no cache expiry, this is the default setting.

The cached files can optionally be organised into a directory tree based on the first few characters of the MD5 hash. This avoids having directories with massive amounts of files which may in some situations be problematic. To configure this in the module parameters, use parameter names numSubdirs and subdirPrefixLength. subdirPrefixLength is the number of characters to use for each subdir, it defaults to 2. numSubdirs is the number of subdirectories to use, it defaults to 0, i.e. put everything directly under the cache directory instead of using any subdirectories.

It is essential that the streams returned by getPage and storePage be closed properly. Failing to do so will cause the cache to remain locked. Even if an IOException is thrown by one of the read methods, close should still be called.

Author:

olli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	DiskCacheModule.LockedInputStream
private class	DiskCacheModule.LockedOutputStream

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	cacheDir
protected java.util.concurrent.locks.ReadWriteLock	cacheLock
protected java.lang.String	COLLISION_SUFFIX
protected long	maxCacheTime
protected int	numSubdirs
protected int	subdirPrefixLength

Fields inherited from class org.wandora.modules.AbstractModule

autoStart, isInitialized, isRunning, logging, loggingModule, moduleManager

Constructor Summary

Constructors

Constructor and Description
DiskCacheModule()

Method Summary

Modifier and Type	Method and Description
java.util.Collection<Module>	getDependencies(ModuleManager manager) Returns all the modules this module depends on.
protected java.io.InputStream	getInputStream(java.lang.String originalKey, long modifyTime)
protected java.io.OutputStream	getOutputStream(java.lang.String originalKey)
java.io.InputStream	getPage(java.lang.String key, long modifyTime) Gets a cached version of a page if one exists in the cache.
protected java.lang.String	getSubdirs(java.lang.String hash)
void	init(ModuleManager manager, java.util.HashMap<java.lang.String,java.lang.Object> settings) Initialises the module.
protected java.lang.String	makeHash(java.lang.String key)
protected java.lang.String	readCacheFileKey(java.io.InputStream in)
void	start(ModuleManager manager) Starts the module.
void	stop(ModuleManager manager) Stops the module.
java.io.OutputStream	storePage(java.lang.String key, long modifyTime) Stores a cached version of a page with the given time stamp.
protected void	writeCacheFileKey(java.io.OutputStream out, java.lang.String key)

Methods inherited from class org.wandora.modules.AbstractModule

isInitialized, isRunning, requireLogging, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.wandora.modules.Module

isInitialized, isRunning

Field Detail

COLLISION_SUFFIX

protected final java.lang.String COLLISION_SUFFIX

See Also:

Constant Field Values

numSubdirs

protected int numSubdirs

subdirPrefixLength

protected int subdirPrefixLength

maxCacheTime

protected long maxCacheTime

cacheLock

protected java.util.concurrent.locks.ReadWriteLock cacheLock

cacheDir

protected java.lang.String cacheDir

Constructor Detail

DiskCacheModule

public DiskCacheModule()

Method Detail

getDependencies

public java.util.Collection<Module> getDependencies(ModuleManager manager)
                                             throws ModuleException

Description copied from interface: Module

Returns all the modules this module depends on. This method will be called after init and the dependencies are allowed to depend on the parameters passed to init. The modules that this module depends on must be returned as a collection. In addition, if any required module is not present, a MissingDependencyException should be thrown. Typically you will use the requireModule and optionalModule methods of the manager to make sure that the modules exist and add them to the collection. requireModule will automatically throw the exception too if the module is not found whereas optionalModule does not.

Specified by:

getDependencies in interface Module

Overrides:

getDependencies in class AbstractModule

Parameters:

manager - The module manager handling this module.

Returns:

A collection of modules this module depends on.

Throws:

ModuleException

init

public void init(ModuleManager manager,
                 java.util.HashMap<java.lang.String,java.lang.Object> settings)
          throws ModuleException

Description copied from interface: Module

Initialises the module. After constructor, this is the first method called in the life cycle of a module. It should not perform anything time consuming or anything with notable outside side effects. It should only read the parameters and initialise the module so that it can later be started. Note that a module being initialised doesn't mean that it necessarily will ever be started.

A ModuleException may be thrown if something vital is missing from the parameters or they are not sensible. In some cases you may not want to throw an exception even if vital initialisation information is missing. If, for example, it is possible that the module is initialised in some other way between the init and the start method calls. A ModuleException may also be thrown at the start method if the module is still not initialised.

Specified by:

init in interface Module

Overrides:

init in class AbstractModule

Parameters:

manager - The module manager handling this module. You may keep a reference to it if needed.

Throws:

ModuleException

start

public void start(ModuleManager manager)
           throws ModuleException

Description copied from interface: Module

Starts the module. This will be called after init and getDependencies and signals that the module should now begin to perform whatever it was designed to do. This method call however should not block for long, so any time consuming tasks should be started in their own threads. You will typically get references to the required modules again in start using the findModule method of the manager and then store those references to instance variables for later use. You may throw a ModuleException if the module is not in a state where it can be started or it immediately becomes obvious that it cannot be started with the provided settings.

Specified by:

start in interface Module

Overrides:

start in class AbstractModule

Parameters:

manager - The module manager handling this module.

Throws:

ModuleException

stop

public void stop(ModuleManager manager)

Description copied from interface: Module

Stops the module. Should stop all threads used by the module, free any large data structures and perform other cleanup. It is possible that the module will be started again later with a start method call (and foregoing init and getDependencies calls). The module should be left in a state where this is possible.

Specified by:

stop in interface Module

Overrides:

stop in class AbstractModule

Parameters:

manager - The module manager handling this module.

makeHash

protected java.lang.String makeHash(java.lang.String key)

readCacheFileKey

protected java.lang.String readCacheFileKey(java.io.InputStream in)
                                     throws java.io.IOException

Throws:

java.io.IOException

getSubdirs

protected java.lang.String getSubdirs(java.lang.String hash)

getInputStream

protected java.io.InputStream getInputStream(java.lang.String originalKey,
                                             long modifyTime)

writeCacheFileKey

protected void writeCacheFileKey(java.io.OutputStream out,
                                 java.lang.String key)
                          throws java.io.IOException

Throws:

java.io.IOException

getOutputStream

protected java.io.OutputStream getOutputStream(java.lang.String originalKey)
                                        throws java.io.IOException

Throws:

java.io.IOException

getPage

public java.io.InputStream getPage(java.lang.String key,
                                   long modifyTime)

Description copied from interface: CacheService

Gets a cached version of a page if one exists in the cache. If modifyTime parameter is greater than 0, the page must be never than the time indicated by the parameter. If a cached version doesn't exist, or it is too old, returns null.

Specified by:

getPage in interface CacheService

Parameters:

key - The key of the cached page.

modifyTime - The minimum caching time of the page, or 0 if no such limit is used.

Returns:

An input stream from which the stored page can be read. The stream must be properly closed afterwards.

storePage

public java.io.OutputStream storePage(java.lang.String key,
                                      long modifyTime)

Description copied from interface: CacheService

Stores a cached version of a page with the given time stamp.

Specified by:

storePage in interface CacheService

Parameters:

key - The key of the cached page.

modifyTime - A timestamp for the cached version.

Returns:

An output stream into which the cached version is written. The stream must be properly closed afterwards.