Package ucar.nc2.dataset

Class NetcdfDatasets

  • public class NetcdfDatasets
extends Object
    Static helper methods for NetcdfDataset
    Since:
    10/3/2019.

    • Constructor Detail

      • NetcdfDatasets

        public NetcdfDatasets()

    • Method Detail

      • 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.

      • disableNetcdfFileCache

        public static void disableNetcdfFileCache()

      • 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.

      • getNetcdfFileCache

        public static FileCacheIF getNetcdfFileCache()
        Get the File Cache
        Returns:
        File Cache or null if not enabled.

      • 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

      • 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

      • 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 relative 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

      • 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,
                                           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,
                                           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​(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

      • 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

      • 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​(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