Package ucar.nc2
Class NetcdfFile
- java.lang.Object
-
- ucar.nc2.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 ofRandomAccessFile
.Using this class's
Builder
scheme to create aNetcdfFile
object could, for example, be accomplished as follows, using a try/finally block to ensure that theNetcdfFile
is closed when done.NetcdfFile ncfile = null; try { ncfile = NetcdfFile.builder().setLocation(fileName).build(); // do stuff } finally { if (ncfile != null) { ncfile.close(); } }
More conveniently, aNetcdfFile
object may be created using one of the static methods inNetcdfFiles
: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.- Variable: group1/group2/varname
- Structure member Variable: group1/group2/varname.s1.s2
- Group Attribute: group1/group2@attName
- Variable Attribute: group1/group2/varName@attName
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
NetcdfFile.Builder<T extends NetcdfFile.Builder<T>>
-
Field Summary
Fields Modifier and Type Field Description static String
IOSP_MESSAGE_GET_IOSP
static String
IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT
static String
IOSP_MESSAGE_RANDOM_ACCESS_FILE
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description 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.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 detailsvoid
getDetailInfo(Formatter f)
Show debug / underlying implementation detailscom.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.String
getId()
Get the globally unique dataset identifier, if it exists.String
getLocation()
Get the NetcdfFile location.Group
getRootGroup()
Get the root group.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<?>
readSectionArray(String variableSection)
Read a variable using the given section specification.Object
sendIospMessage(Object message)
Generic way to send a "message" to the underlying IOSP.NetcdfFile.Builder<?>
toBuilder()
Turn into a mutable Builder.String
toNcml(String url)
NcML representation of Netcdf header info, non strictString
toString()
CDL representation of Netcdf header info, non strictvoid
writeNcml(OutputStream os, String uri)
Write the NcML representation: dont show coordinate valuesvoid
writeNcml(Writer writer, String uri)
Write the NcML representation: dont show coordinate values
-
-
-
Field Detail
-
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
-
-
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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceucar.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)). LOOK Any other chars may also be escaped, as they are removed before testing. LOOK- 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 thefullName
will be treated as if it were there. In other words, the first name token infullName
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.
-
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"
-
getLocation
public String getLocation()
Get the NetcdfFile location. This is a URL, or a file pathname.- Specified by:
getLocation
in interfaceucar.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.
-
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)
-
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
-
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
-
toString
public String toString()
CDL 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
-
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"
-
-