DiskCache2 (NetCDF-Java CDM Public API v5.5.4-SNAPSHOT)

java.lang.Object
- ucar.nc2.util.DiskCache2

```
public class DiskCache2
extends java.lang.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 relative 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
TODO will move in ver 6

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DiskCache2.CachePathPolicy

Nested Classes
Modifier and Type	Class and Description
`static class`	`DiskCache2.CachePathPolicy`

Constructor Summary

Constructors
Constructor and Description
`DiskCache2(java.lang.String root, boolean relativeToHome, int persistMinutes, int scourEveryMinutes)` Create a cache on disk.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static boolean`	`canWrite(java.io.File f)` Returns `true` if we can write to the file.
`void`	`cleanCache(java.io.File dir, java.util.Formatter sbuff, boolean isRoot)` Remove any files or directories whose last modified time greater than persistMinutes
`java.io.File`	`createUniqueFile(java.lang.String prefix, java.lang.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.
`java.io.File`	`getCacheFile(java.lang.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
`java.io.File`	`getExistingFileOrCache(java.lang.String fileLocation)` Looking for an existing file, in cache or no
`java.io.File`	`getFile(java.lang.String fileLocation)` Get the named File.
`static DiskCache2`	`getNoop()`
`java.lang.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, java.lang.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(java.lang.String policy)`
`void`	`setRootDirectory(java.lang.String cacheDir)`
`void`	`showCache(java.io.PrintStream pw)` Show cache contents, for debugging.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - DiskCache2
```
public DiskCache2(java.lang.String root,
                  boolean relativeToHome,
                  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.
    
    relativeToHome - 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
  - canWrite
```
public static boolean canWrite(java.io.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.
  - cleanCache
```
public void cleanCache(java.io.File dir,
                       java.util.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
  - createUniqueFile
```
public java.io.File createUniqueFile(java.lang.String prefix,
                                     java.lang.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
  - exit
```
public static void exit()
```
    Be sure to call this when your application exits, otherwise your process may not exit without being killed.
  - getCacheFile
```
public java.io.File getCacheFile(java.lang.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.
  - getDefault
```
public static DiskCache2 getDefault()
```
    Default DiskCache2 strategy: use $user_home/.unidata/cache/, no scouring, alwaysUseCache = false Mimics default DiskCache static class
  - getExistingFileOrCache
```
public java.io.File getExistingFileOrCache(java.lang.String fileLocation)
```
    Looking for an existing file, in cache or no
    
    Parameters:
    
    fileLocation - the original name
    
    Returns:
    
    existing file if you can find it
  - getFile
```
public java.io.File getFile(java.lang.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.
  - getNoop
```
public static DiskCache2 getNoop()
```
  - getRootDirectory
```
public java.lang.String getRootDirectory()
```
    Get the cache root directory.
    
    Returns:
    
    the cache root directory.
  - 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
  - setCachePathPolicy
```
public void setCachePathPolicy(DiskCache2.CachePathPolicy cachePathPolicy,
                               java.lang.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
  - 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
  - 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
  - setPolicy
```
public void setPolicy(java.lang.String policy)
```
  - setRootDirectory
```
public void setRootDirectory(java.lang.String cacheDir)
```
  - showCache
```
public void showCache(java.io.PrintStream pw)
```
    Show cache contents, for debugging.
    
    Parameters:
    
    pw - write to this PrintStream.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class DiskCache2

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DiskCache2

Method Detail

canWrite

cleanCache

createUniqueFile

exit

getCacheFile

getDefault

getExistingFileOrCache

getFile

getNoop

getRootDirectory

setAlwaysUseCache

setCachePathPolicy

setNeverUseCache

setPolicy

setPolicy

setRootDirectory

showCache

toString