ucar.nc2.util.cache
Class FileCache

java.lang.Object
  extended by ucar.nc2.util.cache.FileCache
Direct Known Subclasses:
FileCacheNOP

@ThreadSafe
public class FileCache
extends Object

Keep cache of open FileCacheable objects, for example NetcdfFile. The FileCacheable object typically contains a RandomAccessFile object that wraps a system resource like a file handle. These are left open when the NetcdfFile is in the cache. The maximum number of these is bounded, though not strictly. A cleanup routine reduces cache size to a minimum number. This cleanup is called periodically in a background thread, and also when the maximum cache size is reached.

  1. The FileCacheable object must not be modified.
  2. The hashKey must uniquely define the FileCacheable object.
  3. The location must be usable in the FileCacheableFactory.
  4. If the FileCacheable is acquired from the cache (ie already open), ncfile.sync() is called on it.
  5. Make sure you call NetcdfDataset.shutdown() when exiting the program, in order to shut down the cleanup thread.
Normal usage is through the NetcdfDataset interface:
 NetcdfDataset.initNetcdfFileCache(...); // on application startup
 ...
 NetcdfFile ncfile = null;
 try {
   ncfile = NetcdfDataset.acquireFile(location, cancelTask);
   ...
 } finally {
   if (ncfile != null) ncfile.close();
 }
 ...
 NetcdfDataset.shutdown();  // when terminating the application
 
All methods are thread safe. Cleanup is done automatically in a background thread, using LRU algorithm.

Since:
May 30, 2008
Author:
caron

Constructor Summary
FileCache(int minElementsInMemory, int maxElementsInMemory, int period)
          Constructor.
FileCache(int minElementsInMemory, int softLimit, int hardLimit, int period)
          Constructor.
FileCache(String name, int minElementsInMemory, int softLimit, int hardLimit, int period)
          Constructor.
 
Method Summary
 FileCacheable acquire(FileFactory factory, Object hashKey, String location, int buffer_size, CancelTask cancelTask, Object spiObject)
          Acquire a FileCacheable from the cache, and lock it so no one else can use it.
 FileCacheable acquire(FileFactory factory, String location, CancelTask cancelTask)
          Acquire a FileCacheable, and lock it so no one else can use it.
 void clearCache(boolean force)
          Remove all cache entries.
 void disable()
          Disable the cache, and force release all files.
 void enable()
          Enable the cache, with the current set of parameters.
 String getInfo(FileCacheable ncfile)
           
 void release(FileCacheable ncfile)
          Release the file.
 List<String> showCache()
           
 void showCache(Formatter format)
          Show individual cache entries, add to formatter.
 void showStats(Formatter format)
          Add stat report (hits, misses, etc) to formatter.
static void shutdown()
          You must call shutdown() to shut down the background threads in order to get a clean process shutdown.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FileCache

public FileCache(int minElementsInMemory,
                 int maxElementsInMemory,
                 int period)
Constructor.

Parameters:
minElementsInMemory - keep this number in the cache
maxElementsInMemory - trigger a cleanup if it goes over this number.
period - (secs) do periodic cleanups every this number of seconds.

FileCache

public FileCache(int minElementsInMemory,
                 int softLimit,
                 int hardLimit,
                 int period)
Constructor.

Parameters:
minElementsInMemory - keep this number in the cache
softLimit - trigger a cleanup if it goes over this number.
hardLimit - if > 0, never allow more than this many elements. This causes a cleanup to be done in the calling thread.
period - if > 0, do periodic cleanups every this number of seconds.

FileCache

public FileCache(String name,
                 int minElementsInMemory,
                 int softLimit,
                 int hardLimit,
                 int period)
Constructor.

Parameters:
name - of file cache
minElementsInMemory - keep this number in the cache
softLimit - trigger a cleanup if it goes over this number.
hardLimit - if > 0, never allow more than this many elements. This causes a cleanup to be done in the calling thread.
period - if > 0, do periodic cleanups every this number of seconds.
Method Detail

shutdown

public static void shutdown()
You must call shutdown() to shut down the background threads in order to get a clean process shutdown.


disable

public void disable()
Disable the cache, and force release all files. You must still call shutdown() before exiting the application.


enable

public void enable()
Enable the cache, with the current set of parameters.


acquire

public FileCacheable acquire(FileFactory factory,
                             String location,
                             CancelTask cancelTask)
                      throws IOException
Acquire a FileCacheable, and lock it so no one else can use it. call FileCacheable.close() when done.

Parameters:
factory - use this factory to open the file; may not be null
location - file location, also used as the cache name, will be passed to the NetcdfFileFactory
cancelTask - user can cancel, ok to be null.
Returns:
NetcdfFile corresponding to location.
Throws:
IOException - on error

acquire

public FileCacheable acquire(FileFactory factory,
                             Object hashKey,
                             String location,
                             int buffer_size,
                             CancelTask cancelTask,
                             Object spiObject)
                      throws IOException
Acquire a FileCacheable from the cache, and lock it so no one else can use it. If not already in cache, open it the FileFactory, and put in cache.

Call FileCacheable.close() when done, (rather than FileCach.release() directly) and the file is then released instead of closed.

If cache size goes over maxElement, then immediately (actually in 100 msec) schedule a cleanup in a background thread. This means that the cache should never get much larger than maxElement, unless you have them all locked.

Parameters:
factory - use this factory to open the file if not in the cache; may not be null
hashKey - unique key for this file. If null, the location will be used
location - file location, may also used as the cache name, will be passed to the NetcdfFileFactory
buffer_size - RandomAccessFile buffer size, if <= 0, use default size
cancelTask - user can cancel, ok to be null.
spiObject - sent to iosp.setSpecial() if not null
Returns:
FileCacheable corresponding to location.
Throws:
IOException - on error

release

public void release(FileCacheable ncfile)
             throws IOException
Release the file. This unlocks it, updates its lastAccessed date. Normally applications need not call this, just close the file as usual.

Parameters:
ncfile - release this file.
Throws:
IOException - if file not in cache.

getInfo

public String getInfo(FileCacheable ncfile)
               throws IOException
Throws:
IOException

clearCache

public void clearCache(boolean force)
Remove all cache entries.

Parameters:
force - if true, remove them even if they are currently locked.

showCache

public void showCache(Formatter format)
Show individual cache entries, add to formatter.

Parameters:
format - add to this

showCache

public List<String> showCache()

showStats

public void showStats(Formatter format)
Add stat report (hits, misses, etc) to formatter.

Parameters:
format - add to this


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.