ucar.nc2.internal.util

Class DiskCache2

java.lang.Object

ucar.nc2.internal.util.DiskCache2

public class DiskCache2
extends Object

Manages a place on disk to persistently cache files, which are deleted when the last modified date exceeds a certain time. This starts up a thread to periodically scour itself; be sure to call exit() to terminate the thread.

Each DiskCache has a "root directory", which may be set as an absolute path, or reletive to the DiskCache "home directory". The root directory must be writeable. The DiskCache home directory is set in the following order:

1. through the system property "nj22.cache" if it exists
2. through the system property "user.home" if it exists
3. through the system property "user.dir" if it exists
4. to the current working directory

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DiskCache2.CachePathPolicy

Constructor Summary

Constructors

Constructor and Description
DiskCache2(String root, boolean reletiveToHome, int persistMinutes, int scourEveryMinutes) Create a cache on disk.

Method Summary

Modifier and Type	Method and Description
static boolean	canWrite(File f) Returns true if we can write to the file.
void	cleanCache(File dir, Formatter sbuff, boolean isRoot) Remove any files or directories whose last modified time greater than persistMinutes
File	createUniqueFile(String prefix, String suffix) Reserve a new, uniquely named file in the root directory.
static void	exit() Be sure to call this when your application exits, otherwise your process may not exit without being killed.
File	getCacheFile(String fileLocation) Get a File in the cache, corresponding to the fileLocation.
static DiskCache2	getDefault() Default DiskCache2 strategy: use $user_home/.unidata/cache/, no scouring, alwaysUseCache = false Mimics default DiskCache static class
File	getExistingFileOrCache(String fileLocation) Looking for an existing file, in cache or no
File	getFile(String fileLocation) Get the named File.
static DiskCache2	getNoop()
String	getRootDirectory() Get the cache root directory.
void	setAlwaysUseCache(boolean alwaysUseCache) If true, always put the file in the cache.
void	setCachePathPolicy(DiskCache2.CachePathPolicy cachePathPolicy, String cachePathPolicyParam) Set the cache path policy
void	setNeverUseCache(boolean neverUseCache) If true, never put the file in the cache.
void	setPolicy(DiskCache2.CachePathPolicy cachePathPolicy) Set the cache path policy
void	setPolicy(String policy)
void	setRootDirectory(String cacheDir)
void	showCache(Formatter f) Show cache contents, for debugging.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

DiskCache2

public DiskCache2(String root,
                  boolean reletiveToHome,
                  int persistMinutes,
                  int scourEveryMinutes)

Create a cache on disk. Use default policy (CachePathPolicy.NestedDirectory)

Parameters:

root - the root directory of the cache. Must be writeable.

reletiveToHome - if the root directory is relative to the cache home directory.

persistMinutes - a file is deleted if its last modified time is greater than persistMinutes

scourEveryMinutes - how often to run the scour process. If <= 0, don't scour.

Method Detail

exit

public static void exit()

Be sure to call this when your application exits, otherwise your process may not exit without being killed.

getDefault

public static DiskCache2 getDefault()

Default DiskCache2 strategy: use $user_home/.unidata/cache/, no scouring, alwaysUseCache = false Mimics default DiskCache static class

getNoop

public static DiskCache2 getNoop()

setRootDirectory

public void setRootDirectory(String cacheDir)

getRootDirectory

public String getRootDirectory()

Get the cache root directory.

Returns:

the cache root directory.

getCacheFile

public File getCacheFile(String fileLocation)

Get a File in the cache, corresponding to the fileLocation. File may or may not exist. If fileLocation has "/" in it, and cachePathPolicy == NestedDirectory, the nested directories will be created.

Parameters:

fileLocation - logical file location

Returns:

physical File in the cache.

getFile

public File getFile(String fileLocation)

Get the named File. If exists or isWritable, return it. Otherwise get corresponding file in the cache directory. If fileLocation has "/" in it, and cachePathPolicy == NestedDirectory, the nested directories will be created.

Parameters:

fileLocation - logical file location

Returns:

physical File as named, or in the cache.

canWrite

public static boolean canWrite(File f)

Returns true if we can write to the file.

Parameters:

f - a file. It may be a regular file or a directory. It may even be non-existent, in which case the writability of the file's parent dir is tested.

Returns:

true if we can write to the file.

getExistingFileOrCache

public File getExistingFileOrCache(String fileLocation)

Looking for an existing file, in cache or no

Parameters:

fileLocation - the original name

Returns:

existing file if you can find it

createUniqueFile

public File createUniqueFile(String prefix,
                             String suffix)

Reserve a new, uniquely named file in the root directory. Mimics File.createTempFile(), but does not actually create the file. Instead, a 0 byte file of the same name with the extension lock is created, thus "reserving" the name until it is used. The filename must be used before persistMinutes, or the lock will be scoured and the reservation will be lost.

Parameters:

prefix - The prefix string to be used in generating the file's name; must be at least three characters long

suffix - The suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used

Returns:

unique, reserved file name

setPolicy

public void setPolicy(DiskCache2.CachePathPolicy cachePathPolicy)

Set the cache path policy

Parameters:

cachePathPolicy - one of: OneDirectory (default) : replace "/" with "-", so all files are in one directory. NestedDirectory: cache files are in nested directories under the root. NestedTruncate: eliminate leading directories

setCachePathPolicy

public void setCachePathPolicy(DiskCache2.CachePathPolicy cachePathPolicy,
                               String cachePathPolicyParam)

Set the cache path policy

Parameters:

cachePathPolicy - one of: OneDirectory (default) : replace "/" with "-", so all files are in one directory. NestedDirectory: cache files are in nested directories under the root. NestedTruncate: eliminate leading directories

cachePathPolicyParam - for NestedTruncate, eliminate this string

setPolicy

public void setPolicy(String policy)

setAlwaysUseCache

public void setAlwaysUseCache(boolean alwaysUseCache)

If true, always put the file in the cache. default false.

Parameters:

alwaysUseCache - If true, always put the file in the cache

setNeverUseCache

public void setNeverUseCache(boolean neverUseCache)

If true, never put the file in the cache. default false.

Parameters:

neverUseCache - If true, never put the file in the cache

showCache

public void showCache(Formatter f)

Show cache contents, for debugging.

cleanCache

public void cleanCache(File dir,
                       Formatter sbuff,
                       boolean isRoot)

Remove any files or directories whose last modified time greater than persistMinutes

Parameters:

dir - clean starting here

sbuff - status messages here, may be null

isRoot - delete empty directories, bit not root directory

toString

public String toString()

Overrides:

toString in class Object