ucar.nc2.dataset

Class NetcdfDatasets

java.lang.Object

ucar.nc2.dataset.NetcdfDatasets

public class NetcdfDatasets
extends Object

Static helper methods for NetcdfDataset

Since:

10/3/2019.

Constructor Summary

Constructors

Constructor and Description
NetcdfDatasets()

Method Summary

Modifier and Type	Method and Description
static NetcdfDataset	acquireDataset(DatasetUrl location, boolean enhanceMode, CancelTask cancelTask) Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode.
static NetcdfDataset	acquireDataset(DatasetUrl location, CancelTask cancelTask) Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode, without the need of setting the enhanceMode via the signature.
static NetcdfDataset	acquireDataset(DatasetUrl location, Set<NetcdfDataset.Enhance> enhanceMode, CancelTask cancelTask) Same as openDataset, but file is acquired through the File Cache, with specified enhancements.
static NetcdfDataset	acquireDataset(ucar.nc2.util.cache.FileFactory fac, DatasetUrl durl, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object iospMessage) Same as openDataset, but file is acquired through the File Cache.
static NetcdfFile	acquireFile(DatasetUrl location, CancelTask cancelTask) Same as openFile, but file is acquired through the File Cache.
static NetcdfFile	acquireFile(ucar.nc2.util.cache.FileFactory factory, Object hashKey, DatasetUrl location, int buffer_size, CancelTask cancelTask, Object spiObject) Same as openFile, but file is acquired through the File Cache.
static void	disableNetcdfFileCache()
static NetcdfDataset	enhance(NetcdfFile ncfile, Set<NetcdfDataset.Enhance> mode, CancelTask cancelTask) Make NetcdfFile into NetcdfDataset and enhance if needed
static ucar.nc2.util.cache.FileCacheIF	getNetcdfFileCache() Get the File Cache
static void	initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int period) Enable file caching.
static void	initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int hardLimit, int period) Enable file caching.
static NetcdfDataset	openDataset(DatasetUrl location, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object spiObject) Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
static NetcdfDataset	openDataset(String location) Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
static NetcdfDataset	openDataset(String location, boolean enhance, CancelTask cancelTask) Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
static NetcdfDataset	openDataset(String location, boolean enhance, int buffer_size, CancelTask cancelTask, Object spiObject) Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
static NetcdfFile	openFile(DatasetUrl location, int buffer_size, CancelTask cancelTask, Object spiObject) Factory method for opening a NetcdfFile through the netCDF API.
static NetcdfFile	openFile(String location, CancelTask cancelTask)
static NetcdfDataset	openNcmlDataset(Reader reader, String ncmlLocation, CancelTask cancelTask) Read NcML doc from a Reader, and construct a NetcdfDataset.Builder.
static void	shutdown() Call when application exits, if you have previously called initNetcdfFileCache.

Methods inherited from class java.lang.Object

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

Constructor Detail

NetcdfDatasets

public NetcdfDatasets()

Method Detail

acquireDataset

public static NetcdfDataset acquireDataset(DatasetUrl location,
                                           boolean enhanceMode,
                                           CancelTask cancelTask)
                                    throws IOException

Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

public static NetcdfDataset acquireDataset(DatasetUrl location,
                                           CancelTask cancelTask)
                                    throws IOException

Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode, without the need of setting the enhanceMode via the signature. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

public static NetcdfDataset acquireDataset(DatasetUrl location,
                                           Set<NetcdfDataset.Enhance> enhanceMode,
                                           CancelTask cancelTask)
                                    throws IOException

Same as openDataset, but file is acquired through the File Cache, with specified enhancements. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

public static NetcdfDataset acquireDataset(ucar.nc2.util.cache.FileFactory fac,
                                           DatasetUrl durl,
                                           Set<NetcdfDataset.Enhance> enhanceMode,
                                           int buffer_size,
                                           CancelTask cancelTask,
                                           Object iospMessage)
                                    throws IOException

Same as openDataset, but file is acquired through the File Cache. You must first call initNetcdfFileCache() for caching to actually take place. You still close with NetcdfDataset.close(), the release is handled automatically.

Parameters:

fac - if not null, use this factory if the file is not in the cache. If null, use the default factory.

durl - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

iospMessage - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset or throw Exception

Throws:

IOException

acquireFile

public static NetcdfFile acquireFile(DatasetUrl location,
                                     CancelTask cancelTask)
                              throws IOException

Same as openFile, but file is acquired through the File Cache. You still close with NetcdfFile.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfFile object

Throws:

IOException - on read error

acquireFile

public static NetcdfFile acquireFile(ucar.nc2.util.cache.FileFactory factory,
                                     Object hashKey,
                                     DatasetUrl location,
                                     int buffer_size,
                                     CancelTask cancelTask,
                                     Object spiObject)
                              throws IOException

Same as openFile, but file is acquired through the File Cache. You still close with NetcdfFile.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

factory - if not null, use this factory to read the file. If null, use the default factory.

hashKey - if not null, use as the cache key, else use the location

location - location of file, passed to FileFactory

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial(); may be null

Returns:

NetcdfFile object

Throws:

IOException - on read error

disableNetcdfFileCache

public static void disableNetcdfFileCache()

enhance

public static NetcdfDataset enhance(NetcdfFile ncfile,
                                    Set<NetcdfDataset.Enhance> mode,
                                    CancelTask cancelTask)
                             throws IOException

Make NetcdfFile into NetcdfDataset and enhance if needed

Parameters:

ncfile - wrap this

mode - using this enhance mode (may be null, meaning no enhance)

Returns:

NetcdfDataset.Builder wrapping the given ncfile

Throws:

IOException - on io error

getNetcdfFileCache

public static ucar.nc2.util.cache.FileCacheIF getNetcdfFileCache()

Get the File Cache

Returns:

File Cache or null if not enabled.

initNetcdfFileCache

public static void initNetcdfFileCache(int minElementsInMemory,
                                       int maxElementsInMemory,
                                       int period)

Enable file caching. call this before calling acquireFile(). When application terminates, call NetcdfDataset.shutdown().

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. set to < 0 to not cleanup

initNetcdfFileCache

public static void initNetcdfFileCache(int minElementsInMemory,
                                       int maxElementsInMemory,
                                       int hardLimit,
                                       int period)

Enable file caching. call this before calling acquireFile(). When application terminates, call NetcdfDataset.shutdown().

Parameters:

minElementsInMemory - keep this number in the cache

maxElementsInMemory - 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 - (secs) do periodic cleanups every this number of seconds.

openDataset

public static NetcdfDataset openDataset(DatasetUrl location,
                                        Set<NetcdfDataset.Enhance> enhanceMode,
                                        int buffer_size,
                                        CancelTask cancelTask,
                                        Object spiObject)
                                 throws IOException

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhanceMode - set of enhancements. If null, then none

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

public static NetcdfDataset openDataset(String location)
                                 throws IOException

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

public static NetcdfDataset openDataset(String location,
                                        boolean enhance,
                                        CancelTask cancelTask)
                                 throws IOException

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhance - if true, use defaultEnhanceMode, else no enhancements

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

public static NetcdfDataset openDataset(String location,
                                        boolean enhance,
                                        int buffer_size,
                                        CancelTask cancelTask,
                                        Object spiObject)
                                 throws IOException

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhance - if true, use defaultEnhanceMode, else no enhancements

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openFile

public static NetcdfFile openFile(DatasetUrl location,
                                  int buffer_size,
                                  CancelTask cancelTask,
                                  Object spiObject)
                           throws IOException

Factory method for opening a NetcdfFile through the netCDF API. May be any kind of file that can be read through the netCDF API, including OpenDAP and NcML.

1. local filename (with a file: prefix or no prefix) for netCDF (version 3), hdf5 files, or any file type registered with NetcdfFile.registerIOProvider().
2. OpenDAP dataset URL (with a dods:, dap4:, or http: prefix).
3. NcML file or URL if the location ends with ".xml" or ".ncml"
4. NetCDF file through an HTTP server (http: prefix)
5. thredds dataset (thredds: prefix), see DataFactory.openDataset(String location, ...));

This does not necessarily return a NetcdfDataset, or enhance the dataset; use NetcdfDatasets.openDataset() method for that.

Parameters:

location - location of dataset.

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfFile object

Throws:

IOException - on read error

openFile

public static NetcdfFile openFile(String location,
                                  CancelTask cancelTask)
                           throws IOException

Throws:

IOException

openNcmlDataset

public static NetcdfDataset openNcmlDataset(Reader reader,
                                            String ncmlLocation,
                                            CancelTask cancelTask)
                                     throws IOException

Read NcML doc from a Reader, and construct a NetcdfDataset.Builder. eg: NcmlReader.readNcml(new StringReader(ncml), location, null);

Parameters:

reader - the Reader containing the NcML document

ncmlLocation - the URL location string of the NcML document, used to resolve reletive path of the referenced dataset, or may be just a unique name for caching purposes.

cancelTask - allow user to cancel the task; may be null

Returns:

the resulting NetcdfDataset.Builder

Throws:

IOException - on read error, or bad referencedDatasetUri URI

shutdown

public static void shutdown()

Call when application exits, if you have previously called initNetcdfFileCache. This shuts down any background threads in order to get a clean process shutdown.