Package ucar.nc2.dataset

Class NetcdfDatasets

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

    • 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 ucar.nc2.internal.cache.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,
                                        @Nullable
                                        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,
                                        @Nullable
                                        Set<NetcdfDataset.Enhance> enhanceMode,
                                        @Nullable
                                        CancelTask cancelTask)
                                 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
        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,
                                        @Nullable
                                        CancelTask cancelTask,
                                        @Nullable
                                        Object iospMessage)
                                 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.
        iospMessage - send to iosp.sendIospMessage() if not null
        Returns:
        NetcdfDataset object
        Throws:
        IOException - on read error

      • openDataset

        public static NetcdfDataset openDataset​(DatasetUrl location,
                                        @Nullable
                                        Set<NetcdfDataset.Enhance> enhanceMode,
                                        int buffer_size,
                                        @Nullable
                                        CancelTask cancelTask,
                                        @Nullable
                                        Object iospMessage)
                                 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.
        iospMessage - send to iosp.sendIospMessage() if not null
        Returns:
        NetcdfDataset object
        Throws:
        IOException - on read error

      • openNcmlDataset

        public static NetcdfDataset openNcmlDataset​(Reader reader,
                                            String ncmlLocation,
                                            @Nullable
                                            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

      • enhance

        public static NetcdfDataset enhance​(NetcdfFile ncfile,
                                    @Nullable
                                    Set<NetcdfDataset.Enhance> mode,
                                    @Nullable
                                    CancelTask cancelTask)
                             throws IOException
        Make NetcdfFile into NetcdfDataset and enhance if needed
        Parameters:
        ncfile - wrap this NetcdfFile or NetcdfDataset.
        mode - using this enhance mode (may be null, meaning no enhance)
        Returns:
        a new NetcdfDataset that wraps the given NetcdfFile or NetcdfDataset.
        Throws:
        IOException - on io error

      • acquireDataset

        public static NetcdfDataset acquireDataset​(DatasetUrl location,
                                           @Nullable
                                           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
        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,
                                           @Nullable
                                           CancelTask cancelTask)
                                    throws IOException
        Same as openDataset, but file is acquired through the File Cache, with optional enhancement. 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 - whether to enhance.
        cancelTask - allow task to be cancelled; may be null.
        Returns:
        NetcdfDataset object
        Throws:
        IOException - on read error

      • acquireDataset

        public static NetcdfDataset acquireDataset​(DatasetUrl location,
                                           @Nullable
                                           Set<NetcdfDataset.Enhance> enhanceMode,
                                           @Nullable
                                           CancelTask cancelTask,
                                           @Nullable
                                           Object iospMessage)
                                    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.
        iospMessage - send to iosp.sendIospMessage() if not null
        Returns:
        NetcdfDataset object
        Throws:
        IOException - on read error

      • acquireDataset

        public static NetcdfDataset acquireDataset​(@Nullable
                                           ucar.nc2.internal.cache.FileFactory fac,
                                           DatasetUrl durl,
                                           @Nullable
                                           Set<NetcdfDataset.Enhance> enhanceMode,
                                           int buffer_size,
                                           @Nullable
                                           CancelTask cancelTask,
                                           @Nullable
                                           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 - send to iosp.sendIospMessage() if not null
        Returns:
        NetcdfDataset or throw Exception
        Throws:
        IOException

      • openFile

        public static NetcdfFile openFile​(DatasetUrl location,
                                  int buffer_size,
                                  CancelTask cancelTask,
                                  Object iospMessage)
                           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: 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.
        iospMessage - send to iosp.sendIospMessage() if not null
        Returns:
        NetcdfFile object
        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

      • acquireFile

        public static NetcdfFile acquireFile​(@Nullable
                                     ucar.nc2.internal.cache.FileFactory factory,
                                     @Nullable
                                     Object hashKey,
                                     DatasetUrl location,
                                     int buffer_size,
                                     @Nullable
                                     CancelTask cancelTask,
                                     @Nullable
                                     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 - send to iosp.sendIospMessage(); may be null
        Returns:
        NetcdfFile object
        Throws:
        IOException - on read error