uk.ac.starlink.ttools.plot2.data

Class DiskCache

java.lang.Object

uk.ac.starlink.ttools.plot2.data.DiskCache

public class DiskCache
extends Object

Represents a persistent cache based on named files in a given directory of a filesystem. This class does not provide all the required facilities for cache management, but it provides some methods which will be useful during such management.

Since:

16 Jan 2020

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static String	CACHE_DIRNAME
static String	README_NAME

Constructor Summary

Constructors

Constructor and Description
DiskCache(File dir, long limit) Constructor.

Method Summary

Modifier and Type	Method and Description
void	fileAdded(File f) Records that a file has been added to the cache.
static String	formatByteSize(long nbyte) Formats a string representing a number of bytes for human consumption.
static long	getDefaultCacheLimit(File dir) Returns a cacheLimit value that is suitable for general usage.
File	getDir() Returns the directory associated with this cache.
static File	getSystemTmpDir() Returns the default system scratch directory.
String	getWriteSummary() Returns a string summarising total cache files written to date.
static String	hashText(String txt) Returns a default-length hash string corresponding to a given string.
static String	hashText(String txt, int nchar) Returns a configurable-length hash string corresponding to a given string.
void	log(String txt) Logging utility function.
static boolean	mkdirs(File dir, boolean ownerOnly) Creates a scratch directory and any missing parents, assigning write privileges for all or owner-only.
void	ready() Ensures that this cache's directory is ready for use.
void	tidy() Removes files from this cache's directory if it contains more data than the configured cache limit.
static File	toCacheDir(File baseDir, String label) Constructs a cache directory path given a base directory and a purpose-specific label.
void	touch(File file) Updates the lastModified timestamp for a given file.
static File	toWorkFilename(File file) Produces a working filename to be used as temporary workspace when assembling a given destination filename.

Methods inherited from class java.lang.Object

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

Field Detail

CACHE_DIRNAME

public static final String CACHE_DIRNAME

See Also:

Constant Field Values

README_NAME

public static final String README_NAME

See Also:

Constant Field Values

Constructor Detail

DiskCache

public DiskCache(File dir,
                 long limit)

Constructor.

Parameters:

dir - directory into which cache files will be written

limit - cache size indicator; if positive, it's the maximum cache size in bytes; if negative, it's the amount of space on the disk that cache usage tries to keep free; if zero, it's something adaptive

Method Detail

getDir

public File getDir()

Returns the directory associated with this cache.

Returns:

cache directory

fileAdded

public void fileAdded(File f)

Records that a file has been added to the cache. This record is used to report persistently added files at shutdown. No check is made that the file in question actually was added.

Parameters:

f - file added

ready

public void ready()
           throws IOException

Ensures that this cache's directory is ready for use. Should be called before the cache is used.

Throws:

IOException

log

public void log(String txt)

Logging utility function. This just passes a message to the logging system, using the logging level associated with this instance.

Parameters:

txt - message to log

tidy

public void tidy()

Removes files from this cache's directory if it contains more data than the configured cache limit.

getWriteSummary

public String getWriteSummary()

Returns a string summarising total cache files written to date.

Returns:

summary text

touch

public void touch(File file)

Updates the lastModified timestamp for a given file.

Parameters:

file - file to touch

hashText

public static String hashText(String txt)

Returns a default-length hash string corresponding to a given string. This doesn't have to be cryptographically secure, but accidental collisions are to be avoided.

Parameters:

txt - text to hash

Returns:

fixed-length hash string

hashText

public static String hashText(String txt,
                              int nchar)

Returns a configurable-length hash string corresponding to a given string. This doesn't have to be cryptographically secure, but accidental collisions are to be avoided.

Parameters:

txt - text to hash

nchar - number of characters in output (currently up to 32)

Returns:

hash string

toWorkFilename

public static File toWorkFilename(File file)

Produces a working filename to be used as temporary workspace when assembling a given destination filename.

We could just use one of the File.createTempFile methods, but attempt to come up with a name that is (a) likely to be unique and (b) bears some resemlance to the requested destination file, for ease of debugging etc.

Parameters:

file - destination file

Returns:

workspace file

formatByteSize

public static String formatByteSize(long nbyte)

Formats a string representing a number of bytes for human consumption.

Parameters:

nbyte - byte count

Returns:

storage size string

getSystemTmpDir

public static File getSystemTmpDir()

Returns the default system scratch directory. This is supplied from the java.io.tmpdir system property.

Returns:

scratch directory

toCacheDir

public static File toCacheDir(File baseDir,
                              String label)

Constructs a cache directory path given a base directory and a purpose-specific label.

Parameters:

baseDir - base directory; if null, java.io.tmpdir is used

label - purpose-specific label (used for subdirectory name)

Returns:

directory to which cache files can be written

mkdirs

public static boolean mkdirs(File dir,
                             boolean ownerOnly)

Creates a scratch directory and any missing parents, assigning write privileges for all or owner-only. This is like File.mkdirs(), but it allows the option of assigning global write privileges to any created directories.

Parameters:

dir - target directory

ownerOnly - true to make created directories writable by ownwer only, false to make them writable by all

Returns:

true if creation succeeded

getDefaultCacheLimit

public static long getDefaultCacheLimit(File dir)

Returns a cacheLimit value that is suitable for general usage. The return value is negative, meaning that it corresponds to requiring a certain number of bytes free on the filesystem.

Parameters:

dir - cache directory