Package ucar.nc2.dataset

Class NetcdfDataset

  • All Implemented Interfaces:
    Closeable, AutoCloseable, ucar.nc2.internal.cache.FileCacheable
    @Immutable
public class NetcdfDataset
extends NetcdfFile

    An "enhanced" NetcdfFile, adding standard attribute parsing such as scale and offset, and explicit support for Coordinate Systems. A NetcdfDataset wraps a NetcdfFile, or is defined by an NcML document.

    Be sure to close the dataset when done. Using statics in NetcdfDatets, best practice is to use try-with-resource: 

     try (NetcdfDataset ncd = NetcdfDatasets.openDataset(fileName)) {
   ...
 }

    By default @code NetcdfDataset} is opened with all enhancements turned on. The default "enhance mode" can be set through setDefaultEnhanceMode(). One can also explicitly set the enhancements you want in the dataset factory methods. The enhancements are:

    • ConvertEnums: convert enum values to their corresponding Strings. If you want to do this manually, you can call Variable.lookupEnumString().
    • ConvertUnsigned: reinterpret the bit patterns of any negative values as unsigned.
    • ApplyScaleOffset: process scale/offset attributes, and automatically convert the data.
    • ConvertMissing: replace missing data with NaNs, for efficiency.
    • CoordSystems: extract CoordinateSystem using the CoordSysBuilder plug-in mechanism.

    Automatic scale/offset processing has some overhead that you may not want to incur up-front. If so, open the NetcdfDataset without ApplyScaleOffset. The VariableDS data type is not promoted and the data is not converted on a read, but you can call the convertScaleOffset() routines to do the conversion later.

    • Method Detail

      • getDefaultEnhanceMode

        public static Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()
        The set of default enhancements.

      • setDefaultEnhanceMode

        public static void setDefaultEnhanceMode​(Set<NetcdfDataset.Enhance> mode)
        Set the default set of Enhancements to do for all subsequent dataset opens and acquires.
        Parameters:
        mode - the default set of Enhancements for open and acquire factory methods

      • getCoordinateSystems

        public List<CoordinateSystem> getCoordinateSystems()
        Get the list of all CoordinateSystem objects used by this dataset.
        Returns:
        list of type CoordinateSystem; may be empty, not null.

      • getConventionUsed

        public String getConventionUsed()
        Get conventions used to analyse coordinate systems.
        Returns:
        conventions used to analyse coordinate systems

      • getEnhanceMode

        public Set<NetcdfDataset.Enhance> getEnhanceMode()
        Get the current state of dataset enhancement.
        Returns:
        the current state of dataset enhancement.

      • getCoordinateAxes

        public List<CoordinateAxis> getCoordinateAxes()
        Get the list of all CoordinateAxis used by this dataset.
        Returns:
        list of type CoordinateAxis; may be empty, not null.

      • findCoordinateAxis

        public CoordinateAxis findCoordinateAxis​(AxisType type)
        Retrieve the CoordinateAxis with the specified Axis Type.
        Parameters:
        type - axis type
        Returns:
        the first CoordinateAxis that has that type, or null if not found

      • findCoordinateAxis

        public CoordinateAxis findCoordinateAxis​(String fullName)
        Retrieve the CoordinateAxis with the specified fullName.
        Parameters:
        fullName - full escaped name of the coordinate axis
        Returns:
        the CoordinateAxis, or null if not found

      • findCoordinateSystem

        public CoordinateSystem findCoordinateSystem​(String name)
        Retrieve the CoordinateSystem with the specified name.
        Parameters:
        name - String which identifies the desired CoordinateSystem
        Returns:
        the CoordinateSystem, or null if not found

      • isIndependentCoordinate

        public boolean isIndependentCoordinate​(CoordinateAxis axis)
        Return true if axis is 1D with a unique dimension.

      • sendIospMessage

        public Object sendIospMessage​(Object message)
        Description copied from class: NetcdfFile
        Generic way to send a "message" to the underlying IOSP. This message is sent after the file is open. To affect the creation of the file, use a factory method like NetcdfFile.open().
        Overrides:
        sendIospMessage in class NetcdfFile
        Parameters:
        message - iosp specific message
        Returns:
        iosp specific return, may be null

      • close

        public void close()
           throws IOException
        Close all resources (files, sockets, etc) associated with this dataset. If the underlying file was acquired, it will be released, otherwise closed.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Specified by:
        close in interface ucar.nc2.internal.cache.FileCacheable
        Overrides:
        close in class NetcdfFile
        Throws:
        IOException - if error when closing

      • release

        public void release()
             throws IOException
        Description copied from class: NetcdfFile
        Public by accident. Release any resources like file handles
        Specified by:
        release in interface ucar.nc2.internal.cache.FileCacheable
        Overrides:
        release in class NetcdfFile
        Throws:
        IOException

      • reacquire

        public void reacquire()
               throws IOException
        Description copied from class: NetcdfFile
        Public by accident. Reacquire any resources like file handles
        Specified by:
        reacquire in interface ucar.nc2.internal.cache.FileCacheable
        Overrides:
        reacquire in class NetcdfFile
        Throws:
        IOException

      • getLastModified

        public long getLastModified()
        Specified by:
        getLastModified in interface ucar.nc2.internal.cache.FileCacheable
        Overrides:
        getLastModified in class NetcdfFile

      • getFileTypeId

        @Nullable
public String getFileTypeId()
        Description copied from class: NetcdfFile
        Get the file type id for the underlying data source.
        Overrides:
        getFileTypeId in class NetcdfFile
        Returns:
        registered id of the file type
        See Also:
        "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

      • getFileTypeDescription

        public String getFileTypeDescription()
        Description copied from class: NetcdfFile
        Get a human-readable description for this file type.
        Overrides:
        getFileTypeDescription in class NetcdfFile
        Returns:
        description of the file type
        See Also:
        "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"