dk.netarkivet.archive.indexserver
Class FileBasedCache<I>

java.lang.Object
  dk.netarkivet.archive.indexserver.FileBasedCache<I>

Type Parameters:

I - The type of cache.

Direct Known Subclasses:

MultiFileBasedCache, RawMetadataCache

public abstract class FileBasedCache<I>
extends java.lang.Object

A generic cache that stores items in files. This abstract superclass handles placement of the cache directory and adding/getting files using the subclasses' methods for generating filenames.

Field Summary

protected java.io.File

cacheDir Cache directory.

Constructor Summary

FileBasedCache(java.lang.String cacheName)
Creates a new FileBasedCache object.

Method Summary

I	cache(I id) Ensure that a file containing the appropriate content exists for the ID.
protected abstract I	cacheData(I id) Fill in actual data in the file in the cache.
java.util.Map<I,java.io.File>	get(java.util.Set<I> ids) Utility method to get a number of cache entries at a time.
java.io.File	getCacheDir() Get the directory that the files are cached in.
abstract java.io.File	getCacheFile(I id) Get the file that caches content for the given ID.
Index<I>	getIndex(I id) Forgiving index generating method, that returns a file with an index, of the greatest possible subset of a given id, and the subset.

Methods inherited from class java.lang.Object

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

Field Detail

cacheDir

protected java.io.File cacheDir

Cache directory.

Constructor Detail

FileBasedCache

public FileBasedCache(java.lang.String cacheName)

Creates a new FileBasedCache object. This creates a directory under the main cache directory holding cached files.

Parameters:

cacheName - Name of this cache (enabling sharing among processes). The directoriy creating in the cachedir will have this name.

Method Detail

getCacheDir

public java.io.File getCacheDir()

Get the directory that the files are cached in. Subclasses should override this to create their own directory with this directory. The full directory structure will be created if required in the constructor.

Returns:

A directory that cache files can reside in.

getCacheFile

public abstract java.io.File getCacheFile(I id)

Get the file that caches content for the given ID.

Parameters:

id - Some sort of id that uniquely identifies the item within the cache.

Returns:

A file (possibly nonexistant or empty) that can cache the data for the id.

cacheData

protected abstract I cacheData(I id)

Fill in actual data in the file in the cache. This is the workhorse method that is allowed to modify the cache. When this method is called, the cache can assume that getCacheFile(id) does not exist.

Parameters:

id - Some identifier for the item to be cached.

Returns:

An id of content actually available. In most cases, this will be the same as id, but for complex I it could be a subset (or null if the type argument I is a simple type). If the return value is not the same as id, the file will not contain cached data, and may not even exist.

cache

public I cache(I id)

Ensure that a file containing the appropriate content exists for the ID. If the content cannot be found, this method may return null (if I is a simple type) or an appropriate subset (if I is, say, a Set) indicating the data that is actually available. In the latter case, calling cache on the returned set should always fill the file for that subset (barring catastrophic failure). Locking: If the file is not immediately found, we enter a file-creation state. To avoid corrupted data, we must ensure that only one cache instance, and only one thread within any instance, creates the file. Thus as long as somebody else seems to be creating the file, we wait and see if they finish. This is checked by having an exclusive lock on a ".working" file (we cannot use the result file, as it has to be created to be locked, and we may end up with a different cached file than we thought, see above). The .working file itself is irrelevant, only the lock on it matters.

Parameters:

id - Some sort of id that uniquely identifies the item within the cache.

Returns:

The id given if it was successfully fetched, otherwise null if the type parameter I does not allow subsets, or a subset of id if it does. This subset should be immediately cacheable.

get

public java.util.Map<I,java.io.File> get(java.util.Set<I> ids)

Utility method to get a number of cache entries at a time. Implementations of FileBasedCache may override this to perform the caching more efficiently, if caching overhead per file is large.

Parameters:

ids - List of IDs that uniquely identify a set of items within the cache.

Returns:

A map from ID to the files containing cached data for those IDs. If caching failed, even partially, for an ID, the entry for the ID doesn't exist.

getIndex

public Index<I> getIndex(I id)

Forgiving index generating method, that returns a file with an index, of the greatest possible subset of a given id, and the subset. If the type I for instance is a Set, you may get an index of only a subset. If I is a File, null may be seen as a subset.

Parameters:

id - The requested index.

Returns:

An index over the greatest possible subset, and the subset.

See Also:

for more information.