Package ucar.nc2

Class NetcdfFile

java.lang.Object
ucar.nc2.NetcdfFile
All Implemented Interfaces:
Closeable, AutoCloseable, ucar.nc2.util.cache.FileCacheable
Direct Known Subclasses:
NetcdfDataset
public class NetcdfFile extends Object implements ucar.nc2.util.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

  • Field Details

  • Method Details

    • 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.util.cache.FileCacheable
      Throws:
      IOException - if error when closing

    • getLocation

      public String getLocation()
      Get the NetcdfFile location. This is a URL, or a file pathname.
      Specified by:
      getLocation in interface ucar.nc2.util.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.

    • getTitle

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

    • getRootGroup

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

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

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

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

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

    • getVariables

      public com.google.common.collect.ImmutableList<Variable> getVariables()
      Get all of the variables in the file, in all groups. Alternatively, use groups.

    • getGlobalAttributes

      public com.google.common.collect.ImmutableList<Attribute> getGlobalAttributes()
      Returns the set of global attributes associated with this file, which are the attributes associated with the root group, or any subgroup. Alternatively, use groups.

    • findGlobalAttribute

      @Nullable public Attribute findGlobalAttribute(String attName)
      Look up an Attribute by (short) name in the root Group or nested Groups, exact match.
      Parameters:
      attName - the name of the attribute
      Returns:
      the first Group attribute with given name, or null if not found

    • findGlobalAttributeIgnoreCase

      @Nullable public Attribute findGlobalAttributeIgnoreCase(String name)
      Look up an Attribute by (short) name in the root Group or nested Groups, ignore case.
      Parameters:
      name - the name of the attribute
      Returns:
      the first group attribute with given Attribute name, ignoronmg case, or null if not found

    • findAttribute

      @Nullable public Attribute findAttribute(String fullNameEscaped)
      Find an attribute, 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/group or group/variable. An embedded "@" is interpreted as variable@attribute 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", "/group/subgroup/@attName" or "/group/subgroup/varname.name2.name@attName"
      Returns:
      Attribute or null if not found.

    • 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

    • 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(). In ver6, IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE will not work here.
      Parameters:
      message - iosp specific message
      Returns:
      iosp specific return, may be null

    • readSection

      public Array readSection(String variableSection) throws IOException, InvalidRangeException
      Read a variable using the given section specification. The result is always an array of the type of the innermost variable. Its shape is the accumulation of all the shapes of its parent structures.
      Parameters:
      variableSection - the constraint expression.
      Returns:
      data requested
      Throws:
      IOException - if error
      InvalidRangeException - if variableSection is invalid
      See Also:

    • getDetailInfo

      public String getDetailInfo()
      Show debug / underlying implementation details

    • getDetailInfo

      public void getDetailInfo(Formatter f)

    • getFileTypeId

      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"

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