ucar.nc2
Class NetcdfFileCache

java.lang.Object
  ucar.nc2.NetcdfFileCache

public class NetcdfFileCache
extends java.lang.Object

Keep cache of open NetcdfFile objects, for performance. Call NetcdfFileCache.acquire instead of NetcdfFile.open. The NetcdfFile 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 and when the maximum cache size is reached.

1. The NetcdfFile object must not be modified.
2. The location must uniquely define the NetcdfFile object.
3. The location must be usable in NetcdfFile.open(), or in the NetcdfFileFactory object if you pass one in.
4. If the NetcdfFile is acquired from the cache (ie already open), ncfile.synch() is called on it.

  NetcdfFile ncfile = null;
  try {
    ncfile = NetcdfFileCache.acquire(location, cancelTask);
    ...
  } finally {
    ncfile.close();
  }
 

Library ships with cache disabled, call init() to use. Make sure you call exit() when exiting program. All methods are thread safe. Cleanup is done automatically in a background thread, using LRU. Uses org.apache.commons.logging for error messages.

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

See Also:

NetcdfDataset.acquireFile(java.lang.String, ucar.nc2.util.CancelTask)

Nested Class Summary

static class

NetcdfFileCache.CacheElement Public as an artifact.

Constructor Summary

NetcdfFileCache()

Method Summary

static NetcdfFile	acquire(java.lang.String location, CancelTask cancelTask) Acquire a NetcdfFile, and lock it so no one else can use it.
static NetcdfFile	acquire(java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject, NetcdfFileFactory factory)
static NetcdfFile	acquireCacheOnly(java.lang.String cacheName) Try to find a file in the cache.
static void	clearCache(boolean force) Remove all cache entries.
static void	disable() Disable use of the cache.
static void	exit() You must call exit() to shut down the background timer in order to get a clean process shutdown.
static java.util.List	getCache() Get the files in the cache.
static void	init() Default 10 minimum, 20 maximum files, cleanup every 20 minutes
static void	init(int minElementsInMemory, int maxElementsInMemory, long period) Initialize the cache.
static void	release(NetcdfFile ncfile) Release the file.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetcdfFileCache

public NetcdfFileCache()

Method Detail

init

public static void init()

Default 10 minimum, 20 maximum files, cleanup every 20 minutes

init

public static void init(int minElementsInMemory,
                        int maxElementsInMemory,
                        long period)

Initialize the cache.

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.

disable

public static void disable()

Disable use of the cache. Call init() to start again. Generally call this before any possible use.

exit

public static void exit()

You must call exit() to shut down the background timer in order to get a clean process shutdown.

acquireCacheOnly

public static NetcdfFile acquireCacheOnly(java.lang.String cacheName)

Try to find a file in the cache.

Parameters:

cacheName - used as the key.

Returns:

file if its in the cache, null otherwise.

acquire

public static NetcdfFile acquire(java.lang.String location,
                                 CancelTask cancelTask)
                          throws java.io.IOException

Acquire a NetcdfFile, and lock it so no one else can use it. If not already in cache, open it with NetcdfFile.open(), and put in cache.

You should call NetcdfFile.close() when done, (rather than NetcdfFileCache.release() directly) and the file is then released instead of closed.

If cache size goes over maxElement, then immediately (actually in 10 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:

location - file location, also used as the cache name

cancelTask - user can cancel, ok to be null.

Returns:

NetcdfFile corresponding to location.

Throws:

java.io.IOException - on error

See Also:

NetcdfFile.open(java.lang.String)

acquire

public static NetcdfFile acquire(java.lang.String location,
                                 int buffer_size,
                                 CancelTask cancelTask,
                                 java.lang.Object spiObject,
                                 NetcdfFileFactory factory)
                          throws java.io.IOException

Throws:

java.io.IOException

release

public static void release(NetcdfFile ncfile)
                    throws java.io.IOException

Release the file. This unlocks it, updates its lastAccessed date. Normally you need not call this, just close the file as usual.

Parameters:

ncfile - release this file.

Throws:

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

getCache

public static java.util.List getCache()

Get the files in the cache. For debugging/status only, do not change!

Returns:

List of NetcdfFileCache.CacheElement

clearCache

public static void clearCache(boolean force)

Remove all cache entries.

Parameters:

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