NetcdfFile (cdm-core 6.0.0-beta1 API)

java.lang.Object
- ucar.nc2.NetcdfFile

All Implemented Interfaces:

Closeable, AutoCloseable, FileCacheable

Direct Known Subclasses:

CdmRemote, NetcdfDataset
```
@Immutable
public class NetcdfFile
extends Object
implements 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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NetcdfFile.Builder<T extends NetcdfFile.Builder<T>>

Nested Classes
Modifier and Type	Class and Description
`static class`	`NetcdfFile.Builder<T extends NetcdfFile.Builder<T>>`

Field Summary

Fields
Modifier and Type	Field and Description
`protected FileCacheIF`	`cache`
`static String`	`IOSP_MESSAGE_ADD_RECORD_STRUCTURE` Deprecated.
`static String`	`IOSP_MESSAGE_GET_IOSP`
`static String`	`IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT`
`static String`	`IOSP_MESSAGE_RANDOM_ACCESS_FILE`

Constructor Summary

Constructors
Modifier Constructor and Description

protected NetcdfFile(NetcdfFile.Builder<?> builder)

Constructors
Modifier	Constructor and Description
`protected`	`NetcdfFile(NetcdfFile.Builder<?> builder)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected NetcdfFile.Builder<?>`	`addLocalFieldsToBuilder(NetcdfFile.Builder<? extends NetcdfFile.Builder<?>> b)`
`static NetcdfFile.Builder<?>`	`builder()` Get Builder for this class.
`void`	`close()` Close all resources (files, sockets, etc) associated with this file.
`Attribute`	`findAttribute(String fullNameEscaped)` Find an attribute, with the specified (escaped full) name.
`Dimension`	`findDimension(String fullName)` Finds a Dimension with the specified full name.
`Attribute`	`findGlobalAttribute(String attName)` Look up an Attribute by (short) name in the root Group or nested Groups, exact match.
`Attribute`	`findGlobalAttributeIgnoreCase(String name)` Look up an Attribute by (short) name in the root Group or nested Groups, ignore case.
`Group`	`findGroup(String fullName)` Find a Group, with the specified (full) name.
`Variable`	`findVariable(String fullNameEscaped)` Find a Variable, with the specified (escaped full) name.
`String`	`getDetailInfo()` Show debug / underlying implementation details
`void`	`getDetailInfo(Formatter f)` Show debug / underlying implementation details
`com.google.common.collect.ImmutableList<Dimension>`	`getDimensions()` Get all shared Dimensions used in this file.
`String`	`getFileTypeDescription()` Get a human-readable description for this file type.
`String`	`getFileTypeId()` Get the file type id for the underlying data source.
`String`	`getFileTypeVersion()` Get the version of this file type.
`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.
`String`	`getId()` Get the globally unique dataset identifier, if it exists.
`long`	`getLastModified()` Deprecated.
`String`	`getLocation()` Get the NetcdfFile location.
`Group`	`getRootGroup()` Get the root group.
`protected Iterator<StructureData>`	`getStructureDataArrayIterator(Sequence s, int bufferSize)`
`protected StructureDataIterator`	`getStructureIterator(Structure s, int bufferSize)` Deprecated. use getStructureDataArrayIterator()
`String`	`getTitle()` Get the human-readable title, if it exists.
`Dimension`	`getUnlimitedDimension()` Return the unlimited (record) dimension, or null if not exist.
`com.google.common.collect.ImmutableList<Variable>`	`getVariables()` Get all of the variables in the file, in all groups.
`boolean`	`hasUnlimitedDimension()` Return true if this file has one or more unlimited (record) dimension.
`void`	`reacquire()` Deprecated. do not use
`protected Array<?>`	`readArrayData(Variable v, Section ranges)` Do not call this directly, use Variable.readArray() !! Ranges must be filled (no nulls)
`protected Array`	`readData(Variable v, Section ranges)` Deprecated. use readArrayData()
`Array`	`readSection(String variableSection)` Deprecated. use readSectionArray()
`Array<?>`	`readSectionArray(String variableSection)` Read a variable using the given section specification.
`protected long`	`readToOutputStream(Variable v, Section section, OutputStream out)`
`void`	`release()` Deprecated. do not use
`Object`	`sendIospMessage(Object message)` Generic way to send a "message" to the underlying IOSP.
`protected void`	`setCachedData(Variable v, Array<?> cacheData)`
`static void`	`setDebugFlags(DebugFlags debugFlag)` Deprecated. do not use
`void`	`setFileCache(FileCacheIF cache)` Deprecated. do not use
`protected void`	`showCached(Formatter f)` Deprecated. do not use
`protected void`	`showProxies(Formatter f)` Deprecated. do not use
`NetcdfFile.Builder<?>`	`toBuilder()` Turn into a mutable Builder.
`String`	`toNcml(String url)` NcML representation of Netcdf header info, non strict
`String`	`toString()` CDL representation of Netcdf header info, non strict
`protected String`	`toStringDebug(Object o)` Deprecated. do not use
`void`	`writeNcml(OutputStream os, String uri)` Write the NcML representation: dont show coordinate values
`void`	`writeNcml(Writer writer, String uri)` Write the NcML representation: dont show coordinate values

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - IOSP_MESSAGE_ADD_RECORD_STRUCTURE
```
@Deprecated
public static final String IOSP_MESSAGE_ADD_RECORD_STRUCTURE
```
    Deprecated.
    
    See Also:
    
    Constant Field Values
  - IOSP_MESSAGE_RANDOM_ACCESS_FILE
```
public static final String IOSP_MESSAGE_RANDOM_ACCESS_FILE
```
    See Also:
    
    Constant Field Values
  - IOSP_MESSAGE_GET_IOSP
```
public static final String IOSP_MESSAGE_GET_IOSP
```
    See Also:
    
    Constant Field Values
  - IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT
```
public static final String IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT
```
    See Also:
    
    Constant Field Values
  - cache
```
protected FileCacheIF cache
```
- Constructor Detail
  - NetcdfFile
```
protected NetcdfFile(NetcdfFile.Builder<?> builder)
```
- Method Detail
  - setDebugFlags
```
@Deprecated
public static void setDebugFlags(DebugFlags debugFlag)
```
    Deprecated. do not use
  - 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 Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface 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 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.
  - 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.
  - 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
  - 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.
  - getDimensions
```
public com.google.common.collect.ImmutableList<Dimension> getDimensions()
```
    Get all shared Dimensions used in this file.
  - 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"
  - 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.
  - getLocation
```
public String getLocation()
```
    Get the NetcdfFile location. This is a URL, or a file pathname.
    
    Specified by:
    
    getLocation in interface 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.
  - getVariables
```
public com.google.common.collect.ImmutableList<Variable> getVariables()
```
    Get all of the variables in the file, in all groups. Alternatively, use groups.
  - 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)
  - getStructureIterator
```
@Deprecated
protected StructureDataIterator getStructureIterator(Structure s,
                                                                  int bufferSize)
                                                           throws IOException
```
    Deprecated. use getStructureDataArrayIterator()
    
    Throws:
    
    IOException
  - getStructureDataArrayIterator
```
protected Iterator<StructureData> getStructureDataArrayIterator(Sequence s,
                                                                int bufferSize)
                                                         throws IOException
```
    Throws:
    
    IOException
  - readData
```
@Deprecated
protected Array readData(Variable v,
                                      Section ranges)
                               throws IOException,
                                      InvalidRangeException
```
    Deprecated. use readArrayData()
    
    Do not call this directly, use Variable.read() !! Ranges must be filled (no nulls)
    
    Throws:
    
    IOException
    
    InvalidRangeException
  - readArrayData
```
@Nullable
protected Array<?> readArrayData(Variable v,
                                            Section ranges)
                                     throws IOException,
                                            InvalidRangeException
```
    Do not call this directly, use Variable.readArray() !! Ranges must be filled (no nulls)
    
    Throws:
    
    IOException
    
    InvalidRangeException
  - readSection
```
@Deprecated
public Array readSection(String variableSection)
                               throws IOException,
                                      InvalidRangeException
```
    Deprecated. use readSectionArray()
    
    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:
    
    SectionSpecification
  - readSectionArray
```
public Array<?> readSectionArray(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.
    
    Throws:
    
    IOException
    
    InvalidRangeException
    
    See Also:
    
    SectionSpecification
  - readToOutputStream
```
protected long readToOutputStream(Variable v,
                                  Section section,
                                  OutputStream out)
                           throws IOException,
                                  InvalidRangeException
```
    Throws:
    
    IOException
    
    InvalidRangeException
  - 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
  - setCachedData
```
protected void setCachedData(Variable v,
                             Array<?> cacheData)
```
  - 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
```
@Deprecated
public long getLastModified()
```
    Deprecated.
    
    Description copied from interface: FileCacheable
    
    Returns the time that the underlying file(s) were last modified. If they've changed since they were stored in the cache, they will be closed and reopened with FileFactory.
    
    Specified by:
    
    getLastModified in interface FileCacheable
    
    Returns:
    
    a long value representing the time the file(s) were last modified or 0L if the last-modified time couldn't be determined for any reason.
  - toStringDebug
```
@Deprecated
protected String toStringDebug(Object o)
```
    Deprecated. do not use
    
    Access to iosp debugging info.
    
    Parameters:
    
    o - must be a Variable, Dimension, Attribute, or Group
    
    Returns:
    
    debug info for this object.
  - release
```
@Deprecated
public void release()
                          throws IOException
```
    Deprecated. do not use
    
    Public by accident. Release any resources like file handles
    
    Specified by:
    
    release in interface FileCacheable
    
    Throws:
    
    IOException
  - reacquire
```
@Deprecated
public void reacquire()
                            throws IOException
```
    Deprecated. do not use
    
    Public by accident. Reacquire any resources like file handles
    
    Specified by:
    
    reacquire in interface FileCacheable
    
    Throws:
    
    IOException
  - setFileCache
```
@Deprecated
public void setFileCache(FileCacheIF cache)
```
    Deprecated. do not use
    
    Public by accident. Optional file caching.
    
    Specified by:
    
    setFileCache in interface FileCacheable
    
    Parameters:
    
    cache - must store this, use it on close as above.
  - getDetailInfo
```
public String getDetailInfo()
```
    Show debug / underlying implementation details
  - getDetailInfo
```
public void getDetailInfo(Formatter f)
```
    Show debug / underlying implementation details
  - showCached
```
@Deprecated
protected void showCached(Formatter f)
```
    Deprecated. do not use
  - showProxies
```
@Deprecated
protected void showProxies(Formatter f)
```
    Deprecated. do not use
  - toBuilder
```
public NetcdfFile.Builder<?> toBuilder()
```
    Turn into a mutable Builder. Can use toBuilder().build() to copy.
  - addLocalFieldsToBuilder
```
protected NetcdfFile.Builder<?> addLocalFieldsToBuilder(NetcdfFile.Builder<? extends NetcdfFile.Builder<?>> b)
```
  - 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"

Class NetcdfFile

Naming

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

IOSP_MESSAGE_ADD_RECORD_STRUCTURE

IOSP_MESSAGE_RANDOM_ACCESS_FILE

IOSP_MESSAGE_GET_IOSP

IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT

cache

Constructor Detail

NetcdfFile

Method Detail

setDebugFlags

close

findAttribute

findDimension

findGlobalAttribute

findGlobalAttributeIgnoreCase

findGroup

findVariable

getDimensions

getFileTypeId

getFileTypeDescription

getFileTypeVersion

getGlobalAttributes

getLocation

getId

getRootGroup

getTitle

getVariables

getUnlimitedDimension

hasUnlimitedDimension

getStructureIterator

getStructureDataArrayIterator

readData

readArrayData

readSection

readSectionArray

readToOutputStream

sendIospMessage

setCachedData

toString

toNcml

writeNcml

writeNcml

getLastModified

toStringDebug

release

reacquire

setFileCache

getDetailInfo

getDetailInfo

showCached

showProxies

toBuilder

addLocalFieldsToBuilder

builder