ucar.nc2.dataset

Class NetcdfDataset

java.lang.Object

ucar.nc2.NetcdfFile

ucar.nc2.dataset.NetcdfDataset

All Implemented Interfaces:

Closeable, AutoCloseable, FileCacheable

@Immutable
public class NetcdfDataset
extends NetcdfFile

An "enhanced" NetcdfFile, 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

Modifier and Type	Field and Description
static String	AGGREGATION
protected static boolean	fillValueIsMissing
protected static boolean	invalidDataIsMissing
protected static boolean	missingDataIsMissing

Fields inherited from class ucar.nc2.NetcdfFile

cache, IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_GET_IOSP, IOSP_MESSAGE_GET_NETCDF_FILE_FORMAT, IOSP_MESSAGE_RANDOM_ACCESS_FILE

Method Summary

Modifier and Type	Method and Description
static NetcdfDataset.Builder<?>	builder() Get Builder for NetcdfDataset.
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(String fullName) Retrieve the CoordinateAxis with the specified fullName.
CoordinateSystem	findCoordinateSystem(String name) Retrieve the CoordinateSystem with the specified name.
CoordinateTransform	findCoordinateTransform(String name) Deprecated. get transform from CoordinateSystem.
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() Deprecated. get transform from CoordinateSystem.
static Set<NetcdfDataset.Enhance>	getDefaultEnhanceMode() The set of default enhancements.
void	getDetailInfo(Formatter f) Show debug / underlying implementation details
static Set<NetcdfDataset.Enhance>	getEnhanceAll() The set of all enhancements.
Set<NetcdfDataset.Enhance>	getEnhanceMode() Get the current state of dataset enhancement.
static Set<NetcdfDataset.Enhance>	getEnhanceNone() The set of no enhancements.
String	getFileTypeDescription() Get a human-readable description for this file type.
String	getFileTypeId() Get the file type id for the underlying data source.
static boolean	getFillValueIsMissing() Deprecated. do not use
static boolean	getInvalidDataIsMissing() Deprecated. do not use
long	getLastModified() Deprecated.
static boolean	getMissingDataIsMissing() Deprecated. do not use
NetcdfFile	getReferencedFile() Deprecated. Do not use
boolean	isIndependentCoordinate(CoordinateAxis axis) Return true if axis is 1D with a unique dimension.
void	reacquire() Deprecated. do not use
void	release() Deprecated. do not use
Object	sendIospMessage(Object message) Generic way to send a "message" to the underlying IOSP.
static void	setDefaultEnhanceMode(Set<NetcdfDataset.Enhance> mode) Set the default set of Enhancements to do for all subsequent dataset opens and acquires.
static void	setFillValueIsMissing(boolean b) Deprecated. do not use
static void	setInvalidDataIsMissing(boolean b) Deprecated. do not use
static void	setMissingDataIsMissing(boolean b) Deprecated. do not use
NetcdfDataset.Builder<?>	toBuilder() Turn into a mutable Builder.

Methods inherited from class ucar.nc2.NetcdfFile

addLocalFieldsToBuilder, findAttribute, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findVariable, getDetailInfo, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getLocation, getRootGroup, getStructureDataArrayIterator, getStructureIterator, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, readArrayData, readData, readSection, readSectionArray, readToOutputStream, setCachedData, setDebugFlags, setFileCache, showCached, showProxies, toNcml, toString, toStringDebug, writeNcml, writeNcml

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AGGREGATION

public static final String AGGREGATION

See Also:

Constant Field Values

fillValueIsMissing

protected static boolean fillValueIsMissing

invalidDataIsMissing

protected static boolean invalidDataIsMissing

missingDataIsMissing

protected static boolean missingDataIsMissing

Method Detail

getEnhanceAll

public static Set<NetcdfDataset.Enhance> getEnhanceAll()

The set of all enhancements.

getEnhanceNone

public static Set<NetcdfDataset.Enhance> getEnhanceNone()

The set of no enhancements.

getDefaultEnhanceMode

public static Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()

The set of default enhancements.

setDefaultEnhanceMode

public static void setDefaultEnhanceMode(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

setFillValueIsMissing

@Deprecated
public static void setFillValueIsMissing(boolean b)

Deprecated. do not use

Set if _FillValue attribute is considered isMissing()

Parameters:

b - true if _FillValue are missing (default true)

getFillValueIsMissing

@Deprecated
public static boolean getFillValueIsMissing()

Deprecated. do not use

Get if _FillValue attribute is considered isMissing()

Returns:

if _FillValue attribute is considered isMissing()

setInvalidDataIsMissing

@Deprecated
public static void setInvalidDataIsMissing(boolean b)

Deprecated. do not use

Set if valid_range attribute is considered isMissing()

Parameters:

b - true if valid_range are missing (default true)

getInvalidDataIsMissing

@Deprecated
public static boolean getInvalidDataIsMissing()

Deprecated. do not use

Get if valid_range attribute is considered isMissing()

Returns:

if valid_range attribute is considered isMissing()

setMissingDataIsMissing

@Deprecated
public static void setMissingDataIsMissing(boolean b)

Deprecated. do not use

Set if missing_data attribute is considered isMissing()

Parameters:

b - true if missing_data are missing (default true)

getMissingDataIsMissing

@Deprecated
public static boolean getMissingDataIsMissing()

Deprecated. do not use

Get if missing_data attribute is considered isMissing()

Returns:

if missing_data attribute is considered isMissing()

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.

getConventionUsed

public String getConventionUsed()

Get conventions used to analyse coordinate systems.

Returns:

conventions used to analyse coordinate systems

getEnhanceMode

public Set<NetcdfDataset.Enhance> getEnhanceMode()

Get the current state of dataset enhancement.

Returns:

the current state of dataset enhancement.

getCoordinateTransforms

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

Deprecated. get transform from CoordinateSystem.

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

Returns:

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

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.

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

Retrieve the CoordinateAxis with the specified fullName.

Parameters:

fullName - full escaped name of the coordinate axis

Returns:

the CoordinateAxis, or null if not found

findCoordinateSystem

public CoordinateSystem findCoordinateSystem(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

@Deprecated
public CoordinateTransform findCoordinateTransform(String name)

Deprecated. get transform from CoordinateSystem.

Retrieve the CoordinateTransform with the specified name.

Parameters:

name - String which identifies the desired CoordinateSystem

Returns:

the CoordinateSystem, or null if not found

isIndependentCoordinate

public boolean isIndependentCoordinate(CoordinateAxis axis)

Return true if axis is 1D with a unique dimension.

sendIospMessage

public Object sendIospMessage(Object message)

Description copied from class: NetcdfFile

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.

Overrides:

sendIospMessage in class NetcdfFile

Parameters:

message - iosp specific message

Returns:

iosp specific return, may be null

close

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

Specified by:

close in interface AutoCloseable

Specified by:

close in interface FileCacheable

Overrides:

close in class NetcdfFile

Throws:

IOException - if error when closing

release

@Deprecated
public void release()
                          throws IOException

Deprecated. do not use

Description copied from class: NetcdfFile

Public by accident. Release any resources like file handles

Specified by:

release in interface FileCacheable

Overrides:

release in class NetcdfFile

Throws:

IOException

reacquire

@Deprecated
public void reacquire()
                            throws IOException

Deprecated. do not use

Description copied from class: NetcdfFile

Public by accident. Reacquire any resources like file handles

Specified by:

reacquire in interface FileCacheable

Overrides:

reacquire in class NetcdfFile

Throws:

IOException

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

Overrides:

getLastModified in class NetcdfFile

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.

getReferencedFile

@Deprecated
public NetcdfFile getReferencedFile()

Deprecated. Do not use

Returns:

underlying NetcdfFile, or null if none.

getDetailInfo

public void getDetailInfo(Formatter f)

Show debug / underlying implementation details

Overrides:

getDetailInfo in class NetcdfFile

getFileTypeId

@Nullable
public 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"

getFileTypeDescription

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

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

builder

public static NetcdfDataset.Builder<?> builder()

Get Builder for NetcdfDataset.