DiskCache (NetCDF-Java CDM Public API v5.4.2)

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

```
public class DiskCache
extends Object
```
This is a general purpose utility for determining a place to write files and cache them, eg for uncompressing files. This class does not scour itself.
Note that when a file in the cache is accessed, its lastModified date is set, which is used for the LRU scouring.
The cdm library sometimes needs to write files, eg to uncompress them, or for grib index files, etc. The first choice is to write these files in the same directory that the original file lives in. However, that directory may not be writeable, so we need to find a place to write them to. We also want to use the file if it already exists.

A writeable cache "root directory" is set:
1. explicitly by setRootDirectory()
2. through the system property "nj22.cache" if it exists
3. by appending "/nj22/cache" to the system property "user.home" if it exists
4. by appending "/nj22/cache" to the system property "user.dir" if it exists
5. use "./nj22/cache" if none of the above
Scenario 1: want to uncompress a file; check to see if already have done so, otherwise get a File that can be written to.
```
 // see if already uncompressed
 File uncompressedFile = FileCache.getFile(uncompressedFilename, false);
 if (!uncompressedFile.exists()) {
   // nope, uncompress it
   UncompressInputStream.uncompress(uriString, uncompressedFile);
 }
 doSomething(uncompressedFile);
 
```
Scenario 2: want to write a derived file always in the cache.
```
 File derivedFile = FileCache.getCacheFile(derivedFilename);
 if (!derivedFile.exists()) {
   createDerivedFile(derivedFile);
 }
 doSomething(derivedFile);
 
```
Scenario 3: same as scenario 1, but use the default Cache policy:
```
 File wf = FileCache.getFileStandardPolicy(uncompressedFilename);
 if (!wf.exists()) {
   writeToFile(wf);
   wf.close();
 }
 doSomething(wf);
 
```
TODO will move in ver 6

Field Summary

Fields
Modifier and Type Field and Description

static boolean simulateUnwritableDir
debug only

Fields
Modifier and Type	Field and Description
`static boolean`	`simulateUnwritableDir` debug only

Constructor Summary

Constructors
Constructor and Description

DiskCache()

Constructors
Constructor and Description
`DiskCache()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`cleanCache(Date cutoff, StringBuilder sbuff)` Remove all files with date < cutoff.
`static void`	`cleanCache(long maxBytes, Comparator<File> fileComparator, StringBuilder sbuff)` Remove files if needed to make cache have less than maxBytes bytes file sizes.
`static void`	`cleanCache(long maxBytes, StringBuilder sbuff)` Remove files if needed to make cache have less than maxBytes bytes file sizes.
`static File`	`getCacheFile(String fileLocation)` Get a file in the cache.
`static File`	`getFile(String fileLocation, boolean alwaysInCache)` Get a File if it exists.
`static File`	`getFileStandardPolicy(String fileLocation)` Get a File if it exists.
`static String`	`getRootDirectory()` Get the name of the root directory
`static void`	`makeRootDirectory()` Make sure that the current root directory exists.
`static void`	`setCachePolicy(boolean alwaysInCache)` Set the standard policy used in getWriteableFileStandardPolicy().
`static void`	`setRootDirectory(String cacheDir)` Set the cache root directory.
`static void`	`showCache(PrintStream pw)`

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

- Field Detail
  - simulateUnwritableDir
```
public static boolean simulateUnwritableDir
```
    debug only
- Constructor Detail
  - DiskCache
```
public DiskCache()
```
- Method Detail
  - cleanCache
```
public static void cleanCache(Date cutoff,
                              StringBuilder sbuff)
```
    Remove all files with date < cutoff.
    
    Parameters:
    
    cutoff - earliest date to allow
    
    sbuff - write results here, null is ok.
  - cleanCache
```
public static void cleanCache(long maxBytes,
                              Comparator<File> fileComparator,
                              StringBuilder sbuff)
```
    Remove files if needed to make cache have less than maxBytes bytes file sizes. This will remove files in sort order defined by fileComparator. The first files in the sort order are kept, until the max bytes is exceeded, then they are deleted.
    
    Parameters:
    
    maxBytes - max number of bytes in cache.
    
    fileComparator - sort files first with this
    
    sbuff - write results here, null is ok.
  - cleanCache
```
public static void cleanCache(long maxBytes,
                              StringBuilder sbuff)
```
    Remove files if needed to make cache have less than maxBytes bytes file sizes. This will remove oldest files first.
    
    Parameters:
    
    maxBytes - max number of bytes in cache.
    
    sbuff - write results here, null is ok.
  - getCacheFile
```
public static File getCacheFile(String fileLocation)
```
    Get a file in the cache. File may or may not exist. We assume its always writeable. If it does exist, set its LastModifiedDate to current time.
    
    Parameters:
    
    fileLocation - normal file location
    
    Returns:
    
    equivalent File in the cache.
  - getFile
```
public static File getFile(String fileLocation,
                           boolean alwaysInCache)
```
    Get a File if it exists. If not, get a File that can be written to. If alwaysInCache, look only in the cache, otherwise, look in the "normal" location first, then in the cache.
    
    Parameters:
    
    fileLocation - normal file location
    
    alwaysInCache - true if you want to look only in the cache
    
    Returns:
    
    a File that either exists or is writeable.
  - getFileStandardPolicy
```
public static File getFileStandardPolicy(String fileLocation)
```
    Get a File if it exists. If not, get a File that can be written to. Use the standard policy to decide where to place it.
    Things are a bit complicated, because in order to guarantee a file in an arbitrary location can be written to, we have to try to open it as a FileOutputStream. If we do, we don't want to open it twice, so we return a WriteableFile that contains an opened FileOutputStream. If it already exists, or we get it from cache, we don't need to open it.
    In any case, you must call WriteableFile.close() to make sure its closed.
    
    Parameters:
    
    fileLocation - normal file location
    
    Returns:
    
    WriteableFile holding the writeable File and a possibly opened FileOutputStream (append false)
  - getRootDirectory
```
public static String getRootDirectory()
```
    Get the name of the root directory
    
    Returns:
    
    name of the root directory
  - makeRootDirectory
```
public static void makeRootDirectory()
```
    Make sure that the current root directory exists.
  - setCachePolicy
```
public static void setCachePolicy(boolean alwaysInCache)
```
    Set the standard policy used in getWriteableFileStandardPolicy(). Default is to try to create the file in the same directory as the original. Setting alwaysInCache to true means to always create it in the cache directory.
    
    Parameters:
    
    alwaysInCache - make this the default policy
  - setRootDirectory
```
public static void setRootDirectory(String cacheDir)
```
    Set the cache root directory. Create it if it doesnt exist.
    
    Parameters:
    
    cacheDir - the cache directory
  - showCache
```
public static void showCache(PrintStream pw)
```

Class DiskCache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

simulateUnwritableDir

Constructor Detail

DiskCache

Method Detail

cleanCache

cleanCache

cleanCache

getCacheFile

getFile

getFileStandardPolicy

getRootDirectory

makeRootDirectory

setCachePolicy

setRootDirectory

showCache