ucar.nc2.dataset
Class NetcdfDatasetCache

java.lang.Object
  ucar.nc2.dataset.NetcdfDatasetCache

public class NetcdfDatasetCache
extends java.lang.Object

Keep cache of open NetcdfDataset, for performance. Call NetcdfDatasetCache.acquire instead of NetcdfDataset.open.

1. The NetcdfDataset object must not be modified.
2. The location must uniquely define the NetcdfDataset object.
3. The location must be usable in NetcdfDataset.openDataset(). We actually use an equivilent package private method, NetcdfDataset.acquireDataset() which acquires the underlying NetcdfFile.
4. When the NetcdfDataset is closed, the underlying file is also closed.
5. If the NetcdfDataset is acquired from the cache, ncfile.synch() the underlying file is acquired again.

  NetcdfDataset ncd = null;
  try {
    ncd = NetcdfDatsetCache.acquire(location, enhance, cancelTask);
    ...
  } finally {
    ncd.close( ncfile)
  }
 

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.slf4j.Logger for error messages.

Version:

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

Author:

john caron

Constructor Summary

NetcdfDatasetCache()

Method Summary

static NetcdfDataset	acquire(java.lang.String location, CancelTask cancelTask) Acquire a NetcdfDataset, and lock it so no one else can use it.
static NetcdfDataset	acquire(java.lang.String cacheName, CancelTask cancelTask, NetcdfDatasetFactory factory) Same as acquire(), but use a factory to open the dataset.
static NetcdfDataset	acquire(java.lang.String cacheName, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject, NetcdfDatasetFactory factory) Same as acquire(), but use a factory to open the dataset.
static NetcdfDataset	acquireCacheOnly(java.lang.String cacheName, CancelTask cancelTask) 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(NetcdfDataset ncd) Release the file.

Methods inherited from class java.lang.Object

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

Constructor Detail

NetcdfDatasetCache

public NetcdfDatasetCache()

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. If you dont, default values will be used. Call disable if you dont want caching.

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 NetcdfDataset acquireCacheOnly(java.lang.String cacheName,
                                             CancelTask cancelTask)
                                      throws java.io.IOException

Try to find a file in the cache. If found, call sync() on it and return it.

Parameters:

cacheName - used as the key.

Returns:

file if its in the cache, null otherwise.

Throws:

java.io.IOException

acquire

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

Acquire a NetcdfDataset, and lock it so no one else can use it. If not already in cache, open it with NetcdfDataset.openDataset() with enhance=true, and put in cache.

You should call NetcdfDataset.close() when done, (rather than NetcdfDatasetCache.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 the task, ok to be null.

Returns:

NetcdfDataset corresponding to location.

Throws:

java.io.IOException - on error

See Also:

NetcdfFile.open(java.lang.String)

acquire

public static NetcdfDataset acquire(java.lang.String cacheName,
                                    CancelTask cancelTask,
                                    NetcdfDatasetFactory factory)
                             throws java.io.IOException

Same as acquire(), but use a factory to open the dataset.

Parameters:

cacheName - : use this as the cache name, may or may not be the same as the location. This is also passed to the factory object.

cancelTask - user can cancel the task, ok to be null.

factory - use this to open; if null use NetcdfDataset.openDataset(). factory should not use NetcdfFileCache.

Returns:

NetcdfFile corresponding to location.

Throws:

java.io.IOException - on error

acquire

public static NetcdfDataset acquire(java.lang.String cacheName,
                                    int buffer_size,
                                    CancelTask cancelTask,
                                    java.lang.Object spiObject,
                                    NetcdfDatasetFactory factory)
                             throws java.io.IOException

Same as acquire(), but use a factory to open the dataset.

Parameters:

cacheName - : use this as the cache name, may or may not be the same as the location. This is also passed to the factory object.

cancelTask - user can cancel the task, ok to be null.

factory - use this to open; if null use NetcdfDataset.openDataset(). factory should not use NetcdfFileCache.

Returns:

NetcdfFile corresponding to location.

Throws:

java.io.IOException - on error

release

public static void release(NetcdfDataset ncd)
                    throws java.io.IOException

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

Parameters:

ncd - 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 NetcdfDatasetCache.CacheElement

clearCache

public static void clearCache(boolean force)

Remove all cache entries.

Parameters:

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