Package ucar.nc2

Class NetcdfFile

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

    Read-only scientific datasets that are accessible through the netCDF API. Immutable after setImmutable() is called. Reading data is not thread-safe because of the use of RandomAccessFile.

    Using this class's Builder scheme to create a NetcdfFile object could, for example, be accomplished as follows, using a try/finally block to ensure that the NetcdfFile is closed when done. 

     NetcdfFile ncfile = null;
 try {
   ncfile = NetcdfFile.builder().setLocation(fileName).build();
   // do stuff
 } finally {
   if (ncfile != null) {
     ncfile.close();
   }
 }
    More conveniently, a NetcdfFile object may be created using one of the static methods in NetcdfFiles: 
     NetcdfFile ncfile = null;
 try {
   ncfile = NetcdfFiles.open(fileName);
   // do stuff
 } finally {
   if (ncfile != null) {
     ncfile.close();
   }
 }
    Or better yet, use try-with-resources: 
     try (NetcdfFile ncfile = NetcdfFiles.open(fileName)) {
   // do stuff
 }

    Naming

    Each object has a name (aka "full name") that is unique within the entire netcdf file, and a "short name" that is unique within the parent group. These coincide for objects in the root group, and so are backwards compatible with version 3 files.
    1. Variable: group1/group2/varname
    2. Structure member Variable: group1/group2/varname.s1.s2
    3. Group Attribute: group1/group2@attName
    4. Variable Attribute: group1/group2/varName@attName

    • Method Detail

      • close

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

      • findAttribute

        @Nullable
public Attribute findAttribute​(String fullNameEscaped)
        Find an attribute, with the specified (escaped full) name. It may be nested in multiple groups and/or structures. An embedded "." is interpreted as structure.member. An embedded "/" is interpreted as group/group or group/variable. An embedded "@" is interpreted as variable@attribute. A name without an "@" is interpreted as an attribute in the root group. If the name actually has a ".", you must escape it (call NetcdfFiles.makeValidPathName(varname)). Any other chars may also be escaped, as they are removed before testing.
        Parameters:
        fullNameEscaped - eg "attName", "@attName", "var@attname", "struct.member.@attName", "/group/subgroup/@attName", "/group/subgroup/var@attName", or "/group/subgroup/struct.member@attName"
        Returns:
        Attribute or null if not found.

      • findDimension

        @Nullable
public Dimension findDimension​(String fullName)
        Finds a Dimension with the specified full name. It may be nested in multiple groups. An embedded "/" is interpreted as a group separator. A leading slash indicates the root group. That slash may be omitted, but the fullName will be treated as if it were there. In other words, the first name token in fullName is treated as the short name of a Group or Dimension, relative to the root group.
        Parameters:
        fullName - Dimension full name, e.g. "/group/subgroup/dim".
        Returns:
        the Dimension or null if it wasn't found.

      • findGroup

        @Nullable
public Group findGroup​(@Nullable
                       String fullName)
        Find a Group, with the specified (full) name. A full name should start with a '/'. For backwards compatibility, we accept full names that omit the leading '/'. An embedded '/' separates subgroup names.
        Parameters:
        fullName - eg "/group/subgroup/wantGroup". Null or empty string returns the root group.
        Returns:
        Group or null if not found.

      • findVariable

        @Nullable
public Variable findVariable​(String fullNameEscaped)
        Find a Variable, with the specified (escaped full) name. It may possibly be nested in multiple groups and/or structures. An embedded "." is interpreted as structure.member. An embedded "/" is interpreted as group/variable. If the name actually has a ".", you must escape it (call NetcdfFiles.makeValidPathName(varname)) Any other chars may also be escaped, as they are removed before testing.
        Parameters:
        fullNameEscaped - eg "/group/subgroup/name1.name2.name".
        Returns:
        Variable or null if not found.

      • getGlobalAttributes

        public List<Attribute> getGlobalAttributes()
        Get all of the group attributes in the file, in all groups. Alternatively, use groups.

      • getDimensions

        public List<Dimension> getDimensions()
        Get all shared Dimensions used in this file, in all groups. Alternatively, use groups.

      • getVariables

        public List<Variable> getVariables()
        Get all of the variables in the file, in all groups. Alternatively, use groups.

      • getFileTypeId

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

      • getFileTypeDescription

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

      • getFileTypeVersion

        public String getFileTypeVersion()
        Get the version of this file type.
        Returns:
        version of the file type
        See Also:
        "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

      • getLocation

        public String getLocation()
        Get the NetcdfFile location. This is a URL, or a file pathname.
        Specified by:
        getLocation in interface ucar.nc2.internal.cache.FileCacheable
        Returns:
        location URL or file pathname.

      • getId

        @Nullable
public String getId()
        Get the globally unique dataset identifier, if it exists.
        Returns:
        id, or null if none.

      • getRootGroup

        public Group getRootGroup()
        Get the root group.
        Returns:
        root group

      • getTitle

        @Nullable
public String getTitle()
        Get the human-readable title, if it exists.
        Returns:
        title, or null if none.

      • getUnlimitedDimension

        @Nullable
public Dimension getUnlimitedDimension()
        Return the unlimited (record) dimension, or null if not exist. If there are multiple unlimited dimensions, it will return the first one.
        Returns:
        the unlimited Dimension, or null if none.

      • hasUnlimitedDimension

        public boolean hasUnlimitedDimension()
        Return true if this file has one or more unlimited (record) dimension.
        Returns:
        if this file has an unlimited Dimension(s)

      • sendIospMessage

        public Object sendIospMessage​(Object message)
        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().
        Parameters:
        message - iosp specific message
        Returns:
        iosp specific return, may be null

      • toString

        public String toString()
        CDL representation of Netcdf header info, non strict
        Overrides:
        toString in class Object

      • toNcml

        public String toNcml​(String url)
        NcML representation of Netcdf header info, non strict

      • writeNcml

        public void writeNcml​(OutputStream os,
                      String uri)
               throws IOException
        Write the NcML representation: dont show coordinate values
        Parameters:
        os - : write to this OutputStream. Will be closed at end of the method.
        uri - use this for the url attribute; if null use getLocation(). // ??
        Throws:
        IOException - if error

      • writeNcml

        public void writeNcml​(Writer writer,
                      String uri)
               throws IOException
        Write the NcML representation: dont show coordinate values
        Parameters:
        writer - : write to this Writer, should have encoding of UTF-8. Will be closed at end of the method.
        uri - use this for the url attribute; if null use getLocation().
        Throws:
        IOException - if error

      • getLastModified

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

      • release

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

      • reacquire

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

      • setFileCache

        public void setFileCache​(ucar.nc2.internal.cache.FileCacheIF cache)
        Public by accident. Optional file caching.
        Specified by:
        setFileCache in interface ucar.nc2.internal.cache.FileCacheable

      • getDetailInfo

        public String getDetailInfo()
        Show debug / underlying implementation details

      • getDetailInfo

        public void getDetailInfo​(Formatter f)
        Show debug / underlying implementation details

      • toBuilder

        public NetcdfFile.Builder<?> toBuilder()
        Turn into a mutable Builder. Can use toBuilder().build() to copy.

      • builder

        public static NetcdfFile.Builder<?> builder()
        Get Builder for this class. Allows subclassing.
        See Also:
        "https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"