ucar.nc2.util.cache

Class FileCache

java.lang.Object

ucar.nc2.util.cache.FileCache

Direct Known Subclasses:

FileCacheNOP

@ThreadSafe
public class FileCache
extends java.lang.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

Constructors

Constructor and Description
FileCache(int minElementsInMemory, int maxElementsInMemory, int period) Constructor.
FileCache(int minElementsInMemory, int softLimit, int hardLimit, int period) Constructor.
FileCache(java.lang.String name, int minElementsInMemory, int softLimit, int hardLimit, int period) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
FileCacheable	acquire(FileFactory factory, java.lang.Object hashKey, java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject) Acquire a FileCacheable from the cache, and lock it so no one else can use it.
FileCacheable	acquire(FileFactory factory, java.lang.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.
java.lang.String	getInfo(FileCacheable ncfile)
void	release(FileCacheable ncfile) Release the file.
java.util.List<java.lang.String>	showCache()
void	showCache(java.util.Formatter format) Show individual cache entries, add to formatter.
void	showStats(java.util.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(java.lang.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,
                    java.lang.String location,
                    CancelTask cancelTask)
                      throws java.io.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:

java.io.IOException - on error

acquire

public FileCacheable acquire(FileFactory factory,
                    java.lang.Object hashKey,
                    java.lang.String location,
                    int buffer_size,
                    CancelTask cancelTask,
                    java.lang.Object spiObject)
                      throws java.io.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:

java.io.IOException - on error

release

public void release(FileCacheable ncfile)
             throws java.io.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:

java.io.IOException - if file not in cache.

getInfo

public java.lang.String getInfo(FileCacheable ncfile)
                         throws java.io.IOException

Throws:

java.io.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(java.util.Formatter format)

Show individual cache entries, add to formatter.

Parameters:

format - add to this

showCache

public java.util.List<java.lang.String> showCache()

showStats

public void showStats(java.util.Formatter format)

Add stat report (hits, misses, etc) to formatter.

Parameters:

format - add to this