ucar.nc2

Class NetcdfFile

java.lang.Object

ucar.nc2.NetcdfFile

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, ucar.nc2.util.cache.FileCacheable

Direct Known Subclasses:

NetcdfDataset

public class NetcdfFile
extends java.lang.Object
implements ucar.nc2.util.cache.FileCacheable, java.io.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>> A builder of NetcdfFile objects.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	IOSP_MESSAGE_ADD_RECORD_STRUCTURE Deprecated.
static java.lang.String	IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE Deprecated.
static java.lang.String	IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT
static java.lang.String	IOSP_MESSAGE_RANDOM_ACCESS_FILE
static java.lang.String	IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE Deprecated.

Method Summary

Modifier and Type	Method and Description
static NetcdfFile.Builder<?>	builder() Get Builder for this class.
void	close() Close all resources (files, sockets, etc) associated with this file.
Attribute	findAttribute(java.lang.String fullNameEscaped) Find an attribute, with the specified (escaped full) name.
Dimension	findDimension(java.lang.String fullName) Finds a Dimension with the specified full name.
Attribute	findGlobalAttribute(java.lang.String attName) Look up an Attribute by (short) name in the root Group or nested Groups, exact match.
Attribute	findGlobalAttributeIgnoreCase(java.lang.String name) Look up an Attribute by (short) name in the root Group or nested Groups, ignore case.
Group	findGroup(java.lang.String fullName) Find a Group, with the specified (full) name.
Variable	findVariable(java.lang.String fullNameEscaped) Find a Variable, with the specified (escaped full) name.
java.lang.String	getDetailInfo() Show debug / underlying implementation details
void	getDetailInfo(java.util.Formatter f)
java.lang.String	getFileTypeDescription() Get a human-readable description for this file type.
java.lang.String	getFileTypeId() Get the file type id for the underlying data source.
java.lang.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.
java.lang.String	getId() Get the globally unique dataset identifier, if it exists.
java.lang.String	getLocation() Get the NetcdfFile location.
Group	getRootGroup() Get the root group.
java.lang.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.
Array	readSection(java.lang.String variableSection) Read a variable using the given section specification.
java.lang.Object	sendIospMessage(java.lang.Object message) Generic way to send a "message" to the underlying IOSP.
NetcdfFile.Builder<?>	toBuilder() Turn into a mutable Builder.
java.lang.String	toNcml(java.lang.String url) NcML representation of Netcdf header info, non strict
java.lang.String	toString() CDL representation of Netcdf header info, non strict
void	writeNcml(java.io.OutputStream os, java.lang.String uri) Write the NcML representation: dont show coordinate values
void	writeNcml(java.io.Writer writer, java.lang.String uri) Write the NcML representation: dont show coordinate values

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ucar.nc2.util.cache.FileCacheable

getLastModified, reacquire, release, setFileCache

Field Detail

IOSP_MESSAGE_ADD_RECORD_STRUCTURE

@Deprecated
public static final java.lang.String IOSP_MESSAGE_ADD_RECORD_STRUCTURE

Deprecated.

See Also:

Constant Field Values

IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE

@Deprecated
public static final java.lang.String IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE

Deprecated.

See Also:

Constant Field Values

IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT

public static final java.lang.String IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT

See Also:

Constant Field Values

IOSP_MESSAGE_RANDOM_ACCESS_FILE

public static final java.lang.String IOSP_MESSAGE_RANDOM_ACCESS_FILE

See Also:

Constant Field Values

IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

@Deprecated
public static final java.lang.String IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

Deprecated.

See Also:

Constant Field Values

Method Detail

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"

close

public void close()
           throws java.io.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 java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface ucar.nc2.util.cache.FileCacheable

Throws:

java.io.IOException - if error when closing

findAttribute

@Nullable
public Attribute findAttribute(java.lang.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(java.lang.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(java.lang.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(java.lang.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
                                 java.lang.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(java.lang.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.

getDetailInfo

public java.lang.String getDetailInfo()

Show debug / underlying implementation details

getDetailInfo

public void getDetailInfo(java.util.Formatter f)

getFileTypeDescription

public java.lang.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"

getFileTypeId

public java.lang.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"

getFileTypeVersion

public java.lang.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.

getId

@Nullable
public java.lang.String getId()

Get the globally unique dataset identifier, if it exists.

Returns:

id, or null if none.

getLocation

public java.lang.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.

getRootGroup

public Group getRootGroup()

Get the root group.

Returns:

root group

getTitle

@Nullable
public java.lang.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.

getVariables

public com.google.common.collect.ImmutableList<Variable> getVariables()

Get all of the variables in the file, in all groups. Alternatively, use groups.

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)

readSection

public Array readSection(java.lang.String variableSection)
                  throws java.io.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:

java.io.IOException - if error

InvalidRangeException - if variableSection is invalid

See Also:

SectionSpecification

sendIospMessage

public java.lang.Object sendIospMessage(java.lang.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

toBuilder

public NetcdfFile.Builder<?> toBuilder()

Turn into a mutable Builder. Can use toBuilder().build() to copy.

toNcml

public java.lang.String toNcml(java.lang.String url)

NcML representation of Netcdf header info, non strict

toString

public java.lang.String toString()

CDL representation of Netcdf header info, non strict

Overrides:

toString in class java.lang.Object

writeNcml

public void writeNcml(java.io.OutputStream os,
                      java.lang.String uri)
               throws java.io.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:

java.io.IOException - if error

writeNcml

public void writeNcml(java.io.Writer writer,
                      java.lang.String uri)
               throws java.io.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:

java.io.IOException - if error