ucar.nc2.dataset

Class NetcdfDataset

java.lang.Object

ucar.nc2.NetcdfFile

ucar.nc2.dataset.NetcdfDataset

All Implemented Interfaces:

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

public class NetcdfDataset
extends NetcdfFile

NetcdfDataset extends the netCDF API, adding standard attribute parsing such as scale and offset, and explicit support for Coordinate Systems. A NetcdfDataset wraps a NetcdfFile, or is defined by an NcML document.

Be sure to close the dataset when done. Using statics in NetcdfDatets, best practice is to use try-with-resource:

 try (NetcdfDataset ncd = NetcdfDatasets.openDataset(fileName)) {
   ...
 }
 

By default @code NetcdfDataset} is opened with all enhancements turned on. The default "enhance mode" can be set through setDefaultEnhanceMode(). One can also explicitly set the enhancements you want in the dataset factory methods. The enhancements are:

• ConvertEnums: convert enum values to their corresponding Strings. If you want to do this manually, you can call Variable.lookupEnumString().
• ConvertUnsigned: reinterpret the bit patterns of any negative values as unsigned.
• ApplyScaleOffset: process scale/offset attributes, and automatically convert the data.
• ConvertMissing: replace missing data with NaNs, for efficiency.
• CoordSystems: extract CoordinateSystem using the CoordSysBuilder plug-in mechanism.

Automatic scale/offset processing has some overhead that you may not want to incur up-front. If so, open the NetcdfDataset without ApplyScaleOffset. The VariableDS data type is not promoted and the data is not converted on a read, but you can call the convertScaleOffset() routines to do the conversion later.

See Also:

NetcdfFile

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NetcdfDataset.Builder<T extends NetcdfDataset.Builder<T>>
static class	NetcdfDataset.Enhance Possible enhancements for a NetcdfDataset

Field Summary

Fields inherited from class ucar.nc2.NetcdfFile

IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE, IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT, IOSP_MESSAGE_RANDOM_ACCESS_FILE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

Method Summary

Modifier and Type	Method and Description
static NetcdfDataset.Builder<?>	builder() Get Builder for this class that allows subclassing.
static NetcdfDataset.Builder	builder(NetcdfFile from)
void	close() Close all resources (files, sockets, etc) associated with this dataset.
CoordinateAxis	findCoordinateAxis(AxisType type) Retrieve the CoordinateAxis with the specified Axis Type.
CoordinateAxis	findCoordinateAxis(java.lang.String fullName) Retrieve the CoordinateAxis with the specified type.
CoordinateSystem	findCoordinateSystem(java.lang.String name) Retrieve the CoordinateSystem with the specified name.
CoordinateTransform	findCoordinateTransform(java.lang.String name) Retrieve the CoordinateTransform with the specified name.
java.lang.String	getConventionUsed() Get conventions used to analyse coordinate systems.
com.google.common.collect.ImmutableList<CoordinateAxis>	getCoordinateAxes() Get the list of all CoordinateAxis objects used by this dataset.
com.google.common.collect.ImmutableList<CoordinateSystem>	getCoordinateSystems() Get the list of all CoordinateSystem objects used by this dataset.
com.google.common.collect.ImmutableList<CoordinateTransform>	getCoordinateTransforms() Get the list of all CoordinateTransform objects used by this dataset.
static java.util.Set<NetcdfDataset.Enhance>	getDefaultEnhanceMode()
void	getDetailInfo(java.util.Formatter f) Show debug / underlying implementation details
static java.util.Set<NetcdfDataset.Enhance>	getEnhanceAll()
java.util.Set<NetcdfDataset.Enhance>	getEnhanceMode() Get the current state of dataset enhancement.
static java.util.Set<NetcdfDataset.Enhance>	getEnhanceNone()
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.
long	getLastModified()
static void	setDefaultEnhanceMode(java.util.Set<NetcdfDataset.Enhance> mode) Set the default set of Enhancements to do for all subsequent dataset opens and acquires.
NetcdfDataset.Builder<?>	toBuilder() Turn into a mutable Builder.

Methods inherited from class ucar.nc2.NetcdfFile

findAttribute, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findVariable, getDetailInfo, getFileTypeVersion, getGlobalAttributes, getId, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, readSection, sendIospMessage, toNcml, toString, writeNcml, writeNcml

Methods inherited from class java.lang.Object

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

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

reacquire, release, setFileCache

Method Detail

builder

public static NetcdfDataset.Builder<?> builder()

Get Builder for this class that allows subclassing.

See Also:

"https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"

builder

public static NetcdfDataset.Builder builder(NetcdfFile from)

close

public void close()
           throws java.io.IOException

Close all resources (files, sockets, etc) associated with this dataset. If the underlying file was acquired, it will be released, otherwise closed.

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

Overrides:

close in class NetcdfFile

Throws:

java.io.IOException - if error when closing

findCoordinateAxis

public CoordinateAxis findCoordinateAxis(AxisType type)

Retrieve the CoordinateAxis with the specified Axis Type.

Parameters:

type - axis type

Returns:

the first CoordinateAxis that has that type, or null if not found

findCoordinateAxis

public CoordinateAxis findCoordinateAxis(java.lang.String fullName)

Retrieve the CoordinateAxis with the specified type.

Parameters:

fullName - full escaped name of the coordinate axis

Returns:

the CoordinateAxis, or null if not found

findCoordinateSystem

public CoordinateSystem findCoordinateSystem(java.lang.String name)

Retrieve the CoordinateSystem with the specified name.

Parameters:

name - String which identifies the desired CoordinateSystem

Returns:

the CoordinateSystem, or null if not found

findCoordinateTransform

public CoordinateTransform findCoordinateTransform(java.lang.String name)

Retrieve the CoordinateTransform with the specified name.

Parameters:

name - String which identifies the desired CoordinateSystem

Returns:

the CoordinateSystem, or null if not found

getConventionUsed

public java.lang.String getConventionUsed()

Get conventions used to analyse coordinate systems.

Returns:

conventions used to analyse coordinate systems

getCoordinateAxes

public com.google.common.collect.ImmutableList<CoordinateAxis> getCoordinateAxes()

Get the list of all CoordinateAxis objects used by this dataset.

Returns:

list of type CoordinateAxis; may be empty, not null.

getCoordinateSystems

public com.google.common.collect.ImmutableList<CoordinateSystem> getCoordinateSystems()

Get the list of all CoordinateSystem objects used by this dataset.

Returns:

list of type CoordinateSystem; may be empty, not null.

getCoordinateTransforms

public com.google.common.collect.ImmutableList<CoordinateTransform> getCoordinateTransforms()

Get the list of all CoordinateTransform objects used by this dataset.

Returns:

list of type CoordinateTransform; may be empty, not null.

getDefaultEnhanceMode

public static java.util.Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()

getDetailInfo

public void getDetailInfo(java.util.Formatter f)

Show debug / underlying implementation details

Overrides:

getDetailInfo in class NetcdfFile

getEnhanceAll

public static java.util.Set<NetcdfDataset.Enhance> getEnhanceAll()

getEnhanceMode

public java.util.Set<NetcdfDataset.Enhance> getEnhanceMode()

Get the current state of dataset enhancement.

Returns:

the current state of dataset enhancement.

getEnhanceNone

public static java.util.Set<NetcdfDataset.Enhance> getEnhanceNone()

getFileTypeDescription

public java.lang.String getFileTypeDescription()

Description copied from class: NetcdfFile

Get a human-readable description for this file type.

Overrides:

getFileTypeDescription in class NetcdfFile

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

Description copied from class: NetcdfFile

Get the file type id for the underlying data source.

Overrides:

getFileTypeId in class NetcdfFile

Returns:

registered id of the file type

See Also:

"https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getLastModified

public long getLastModified()

Specified by:

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

Overrides:

getLastModified in class NetcdfFile

setDefaultEnhanceMode

public static void setDefaultEnhanceMode(java.util.Set<NetcdfDataset.Enhance> mode)

Set the default set of Enhancements to do for all subsequent dataset opens and acquires.

Parameters:

mode - the default set of Enhancements for open and acquire factory methods

toBuilder

public NetcdfDataset.Builder<?> toBuilder()

Description copied from class: NetcdfFile

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

Overrides:

toBuilder in class NetcdfFile