ucar.nc2.dataset

Class NetcdfDataset

java.lang.Object

ucar.nc2.NetcdfFile

ucar.nc2.dataset.NetcdfDataset

All Implemented Interfaces:

Closeable, 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_RANDOM_ACCESS_FILE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

Constructor Summary

Constructors

Constructor and Description
NetcdfDataset() Deprecated. Use NetcdfDataset.builder()
NetcdfDataset(NetcdfFile.Builder<?> builder)
NetcdfDataset(NetcdfFile ncfile) Deprecated. Use NetcdfDataset.builder()
NetcdfDataset(NetcdfFile ncfile, boolean enhance) Deprecated. Use NetcdfDataset.builder()
NetcdfDataset(NetcdfFile ncfile, Set<NetcdfDataset.Enhance> mode) Deprecated. Use NetcdfDataset.builder()

Method Summary

Modifier and Type	Method and Description
static NetcdfDataset	acquireDataset(DatasetUrl location, boolean enhanceMode, CancelTask cancelTask) Deprecated. use NetcdfDatasets.acquireDataset
static NetcdfDataset	acquireDataset(DatasetUrl location, CancelTask cancelTask) Deprecated. use NetcdfDatasets.acquireDataset
static NetcdfDataset	acquireDataset(DatasetUrl location, Set<NetcdfDataset.Enhance> enhanceMode, CancelTask cancelTask) Deprecated. use NetcdfDatasets.acquireDataset
static NetcdfDataset	acquireDataset(ucar.nc2.util.cache.FileFactory fac, DatasetUrl durl, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object iospMessage) Deprecated. use NetcdfDatasets.acquireDataset
static NetcdfFile	acquireFile(DatasetUrl location, CancelTask cancelTask) Deprecated. use NetcdfDatasets.acquireFile
static NetcdfFile	acquireFile(ucar.nc2.util.cache.FileFactory factory, Object hashKey, DatasetUrl location, int buffer_size, CancelTask cancelTask, Object spiObject) Deprecated. use NetcdfDatasets.acquireFile
CoordinateAxis	addCoordinateAxis(VariableDS v) Deprecated. Use NetcdfDataset.builder()
void	addCoordinateSystem(CoordinateSystem cs) Deprecated. Use NetcdfDataset.builder()
void	addCoordinateTransform(CoordinateTransform ct) Deprecated. Use NetcdfDataset.builder()
Variable	addVariable(Group g, Variable v) Deprecated. Use NetcdfDataset.builder()
static NetcdfDataset.Builder<?>	builder() Get Builder for this class that allows subclassing.
static NetcdfDataset.Builder	builder(NetcdfFile from)
void	check(Formatter f) Deprecated. do not use
void	clearCoordinateSystems() Deprecated. Use NetcdfDataset.builder()
void	close() Close all resources (files, sockets, etc) associated with this dataset.
static void	debugDump(PrintWriter out, NetcdfDataset ncd) Deprecated. do not use
static void	disableNetcdfFileCache() Deprecated. use NetcdfDatasets.disableNetcdfFileCache
void	empty() Deprecated. Use NetcdfDataset.builder()
CoordSysBuilderIF	enhance() Deprecated. Use NetcdfDataset.builder()
void	enhance(Set<NetcdfDataset.Enhance> mode) Deprecated. Use NetcdfDataset.builder()
boolean	enhanceNeeded(Set<NetcdfDataset.Enhance> want) Deprecated. Do not use.
CoordinateAxis	findCoordinateAxis(AxisType type) Retrieve the CoordinateAxis with the specified Axis Type.
CoordinateAxis	findCoordinateAxis(String fullName) Retrieve the CoordinateAxis with the specified type.
CoordinateSystem	findCoordinateSystem(String name) Retrieve the CoordinateSystem with the specified name.
CoordinateTransform	findCoordinateTransform(String name) Retrieve the CoordinateTransform with the specified name.
ucar.nc2.ncml.AggregationIF	getAggregation() Deprecated. Do not use.
String	getConventionUsed() Get conventions used to analyse coordinate systems.
List<CoordinateAxis>	getCoordinateAxes() Get the list of all CoordinateAxis objects used by this dataset.
List<CoordinateSystem>	getCoordinateSystems() Get the list of all CoordinateSystem objects used by this dataset.
List<CoordinateTransform>	getCoordinateTransforms() Get the list of all CoordinateTransform objects used by this dataset.
static Set<NetcdfDataset.Enhance>	getDefaultEnhanceMode()
void	getDetailInfo(Formatter f) Show debug / underlying implementation details
static Set<NetcdfDataset.Enhance>	getEnhanceAll()
Set<NetcdfDataset.Enhance>	getEnhanceMode() Get the current state of dataset enhancement.
static Set<NetcdfDataset.Enhance>	getEnhanceNone()
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
IOServiceProvider	getIosp() Deprecated. do not use
long	getLastModified()
static boolean	getMissingDataIsMissing() Deprecated. do not use
static ucar.nc2.util.cache.FileCacheIF	getNetcdfFileCache() Deprecated. use NetcdfDatasets.getNetcdfFileCache
NetcdfFile	getReferencedFile() Deprecated. Do not use
static void	initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int period) Deprecated. use NetcdfDatasets.initNetcdfFileCache
static void	initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int hardLimit, int period) Deprecated. use NetcdfDatasets.initNetcdfFileCache
static void	main(String[] arg) Main program - cover to ucar.nc2.FileWriter, for all files that can be read by NetcdfDataset.openFile()
static Array	makeArray(DataType dtype, List<String> stringValues) Deprecated. use Array#makeArray directly
static NetcdfDataset	openDataset(DatasetUrl location, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object spiObject) Deprecated. use NetcdfDatasets.openDataset
static NetcdfDataset	openDataset(String location) Deprecated. use NetcdfDatasets.openDataset
static NetcdfDataset	openDataset(String location, boolean enhance, CancelTask cancelTask) Deprecated. use NetcdfDatasets.openDataset
static NetcdfDataset	openDataset(String location, boolean enhance, int buffer_size, CancelTask cancelTask, Object spiObject) Deprecated. use NetcdfDatasets.openDataset
static NetcdfFile	openFile(DatasetUrl location, int buffer_size, CancelTask cancelTask, Object spiObject) Deprecated. use NetcdfDatasets.openFile
static NetcdfFile	openFile(String location, CancelTask cancelTask) Deprecated. use NetcdfDatasets.openFile
static Set<NetcdfDataset.Enhance>	parseEnhanceMode(String enhanceMode) Deprecated. this is moving to Ncml package
void	reacquire()
void	release()
void	setAggregation(ucar.nc2.ncml.AggregationIF agg) Deprecated. Use NetcdfDataset.builder()
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
void	setReferencedFile(NetcdfFile ncfile) Deprecated. Use NetcdfDataset.builder()
void	setValues(Variable v, int npts, double start, double incr) Deprecated. use Variable.setValues()
void	setValues(Variable v, List<String> values) Deprecated. use Variable.setValues()
static void	shutdown() Deprecated. use NetcdfDatasets.shutdown
void	sort() Deprecated. Use NetcdfDataset.builder()
boolean	syncExtend() Deprecated. do not use
NetcdfDataset.Builder<?>	toBuilder() Turn into a mutable Builder.
static NetcdfDataset	wrap(NetcdfFile ncfile, Set<NetcdfDataset.Enhance> mode) Deprecated. use NetcdfDatasets.wrap
void	writeNcML(OutputStream os, String uri) Deprecated. will move in ver 6

Methods inherited from class ucar.nc2.NetcdfFile

addAttribute, addAttribute, addDimension, addGroup, addStringVariable, addVariable, addVariableAttribute, canonicalizeUriString, canOpen, findAttribute, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findVariable, findVariable, findVariableByAttribute, finish, getCacheName, getDetailInfo, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, iospDeRegister, iospRegistered, makeNameUnescaped, makeValidCDLName, makeValidCdmObjectName, makeValidPathName, makeValidSectionSpecName, open, open, open, open, open, open, openInMemory, openInMemory, openInMemory, openInMemory, read, readArrays, readAttributeDouble, readAttributeInteger, readSection, registerIOProvider, registerIOProvider, registerIOProvider, registerIOProviderPreferred, removeDimension, removeVariable, sendIospMessage, setDebugFlags, setFileCache, setId, setImmutable, setLocation, setProperty, setRootGroup, setTitle, toNcML, toString, writeCDL, writeCDL, writeNcML

Methods inherited from class java.lang.Object

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

Constructor Detail

NetcdfDataset

@Deprecated
public NetcdfDataset(NetcdfFile ncfile)
                          throws IOException

Deprecated. Use NetcdfDataset.builder()

Transform a NetcdfFile into a NetcdfDataset, with default enhancement. You must not use the underlying NetcdfFile after this call, because it gets modified. Therefore you should not use this with a cached file.

Parameters:

ncfile - NetcdfFile to transform.

Throws:

IOException - on read error

NetcdfDataset

@Deprecated
public NetcdfDataset(NetcdfFile ncfile,
                                 boolean enhance)
                          throws IOException

Deprecated. Use NetcdfDataset.builder()

Transform a NetcdfFile into a NetcdfDataset, optionally enhance it. You must not use the original NetcdfFile after this call.

Parameters:

ncfile - NetcdfFile to transform, do not use independently after this.

enhance - if true, enhance with defaultEnhanceMode

Throws:

IOException - on read error

NetcdfDataset

@Deprecated
public NetcdfDataset(NetcdfFile ncfile,
                                 Set<NetcdfDataset.Enhance> mode)
                          throws IOException

Deprecated. Use NetcdfDataset.builder()

Transform a NetcdfFile into a NetcdfDataset, optionally enhance it. You must not use the original NetcdfFile after this call.

Parameters:

ncfile - NetcdfFile to transform, do not use independently after this.

mode - set of enhance modes. If null, then none

Throws:

IOException - on read error

NetcdfDataset

@Deprecated
public NetcdfDataset()

Deprecated. Use NetcdfDataset.builder()

No-arg Constructor

NetcdfDataset

public NetcdfDataset(NetcdfFile.Builder<?> builder)

Method Detail

getEnhanceAll

public static Set<NetcdfDataset.Enhance> getEnhanceAll()

getEnhanceNone

public static Set<NetcdfDataset.Enhance> getEnhanceNone()

getDefaultEnhanceMode

public static Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()

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

parseEnhanceMode

@Deprecated
public static Set<NetcdfDataset.Enhance> parseEnhanceMode(String enhanceMode)

Deprecated. this is moving to Ncml package

Retrieve the set of Enhancements that is associated with the given string.

String	Enhancements
All	ConvertEnums, ConvertUnsigned, ApplyScaleOffset, ConvertMissing, CoordSystems
None	<empty>
ConvertEnums	ConvertEnums
ConvertUnsigned	ConvertUnsigned
ApplyScaleOffset	ApplyScaleOffset
ConvertMissing	ConvertMissing
CoordSystems	CoordSystems
IncompleteCoordSystems	CoordSystems
true	Alias for "All"
ScaleMissingDefer	Alias for "None"
AllDefer	ConvertEnums, CoordSystems
ScaleMissing	ConvertUnsigned, ApplyScaleOffset, ConvertMissing

Parameters:

enhanceMode - a string from the above table.

Returns:

the set corresponding to enhanceMode, or null if there is no correspondence.

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

initNetcdfFileCache

@Deprecated
public static void initNetcdfFileCache(int minElementsInMemory,
                                                   int maxElementsInMemory,
                                                   int period)

Deprecated. use NetcdfDatasets.initNetcdfFileCache

Enable file caching. call this before calling acquireFile(). When application terminates, call NetcdfDataset.shutdown().

Parameters:

minElementsInMemory - keep this number in the cache

maxElementsInMemory - trigger a cleanup if it goes over this number.

period - (secs) do periodic cleanups every this number of seconds. set to < 0 to not cleanup

initNetcdfFileCache

@Deprecated
public static void initNetcdfFileCache(int minElementsInMemory,
                                                   int maxElementsInMemory,
                                                   int hardLimit,
                                                   int period)

Deprecated. use NetcdfDatasets.initNetcdfFileCache

Enable file caching. call this before calling acquireFile(). When application terminates, call NetcdfDataset.shutdown().

Parameters:

minElementsInMemory - keep this number in the cache

maxElementsInMemory - trigger a cleanup if it goes over this number.

hardLimit - if > 0, never allow more than this many elements. This causes a cleanup to be done in the calling thread.

period - (secs) do periodic cleanups every this number of seconds.

disableNetcdfFileCache

@Deprecated
public static void disableNetcdfFileCache()

Deprecated. use NetcdfDatasets.disableNetcdfFileCache

shutdown

@Deprecated
public static void shutdown()

Deprecated. use NetcdfDatasets.shutdown

Call when application exits, if you have previously called initNetcdfFileCache. This shuts down any background threads in order to get a clean process shutdown.

getNetcdfFileCache

@Deprecated
public static ucar.nc2.util.cache.FileCacheIF getNetcdfFileCache()

Deprecated. use NetcdfDatasets.getNetcdfFileCache

Get the File Cache

Returns:

File Cache or null if not enabled.

wrap

@Deprecated
public static NetcdfDataset wrap(NetcdfFile ncfile,
                                             Set<NetcdfDataset.Enhance> mode)
                                      throws IOException

Deprecated. use NetcdfDatasets.wrap

Make NetcdfFile into NetcdfDataset with given enhance mode

Parameters:

ncfile - wrap this

mode - using this enhance mode (may be null, meaning no enhance)

Returns:

NetcdfDataset wrapping the given ncfile

Throws:

IOException - on io error

openDataset

@Deprecated
public static NetcdfDataset openDataset(String location)
                                             throws IOException

Deprecated. use NetcdfDatasets.openDataset

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

@Deprecated
public static NetcdfDataset openDataset(String location,
                                                    boolean enhance,
                                                    CancelTask cancelTask)
                                             throws IOException

Deprecated. use NetcdfDatasets.openDataset

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhance - if true, use defaultEnhanceMode, else no enhancements

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

@Deprecated
public static NetcdfDataset openDataset(String location,
                                                    boolean enhance,
                                                    int buffer_size,
                                                    CancelTask cancelTask,
                                                    Object spiObject)
                                             throws IOException

Deprecated. use NetcdfDatasets.openDataset

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhance - if true, use defaultEnhanceMode, else no enhancements

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset object

Throws:

IOException - on read error

openDataset

@Deprecated
public static NetcdfDataset openDataset(DatasetUrl location,
                                                    Set<NetcdfDataset.Enhance> enhanceMode,
                                                    int buffer_size,
                                                    CancelTask cancelTask,
                                                    Object spiObject)
                                             throws IOException

Deprecated. use NetcdfDatasets.openDataset

Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.

Parameters:

location - location of file

enhanceMode - set of enhancements. If null, then none

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

@Deprecated
public static NetcdfDataset acquireDataset(DatasetUrl location,
                                                       CancelTask cancelTask)
                                                throws IOException

Deprecated. use NetcdfDatasets.acquireDataset

Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode, without the need of setting the enhanceMode via the signature. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

@Deprecated
public static NetcdfDataset acquireDataset(DatasetUrl location,
                                                       boolean enhanceMode,
                                                       CancelTask cancelTask)
                                                throws IOException

Deprecated. use NetcdfDatasets.acquireDataset

Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

@Deprecated
public static NetcdfDataset acquireDataset(DatasetUrl location,
                                                       Set<NetcdfDataset.Enhance> enhanceMode,
                                                       CancelTask cancelTask)
                                                throws IOException

Deprecated. use NetcdfDatasets.acquireDataset

Same as openDataset, but file is acquired through the File Cache, with specified enhancements. You still close with NetcdfDataset.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfDataset object

Throws:

IOException - on read error

acquireDataset

@Deprecated
public static NetcdfDataset acquireDataset(ucar.nc2.util.cache.FileFactory fac,
                                                       DatasetUrl durl,
                                                       Set<NetcdfDataset.Enhance> enhanceMode,
                                                       int buffer_size,
                                                       CancelTask cancelTask,
                                                       Object iospMessage)
                                                throws IOException

Deprecated. use NetcdfDatasets.acquireDataset

Same as openDataset, but file is acquired through the File Cache. You must first call initNetcdfFileCache() for caching to actually take place. You still close with NetcdfDataset.close(), the release is handled automatically.

Parameters:

fac - if not null, use this factory if the file is not in the cache. If null, use the default factory.

durl - location of file, passed to FileFactory

enhanceMode - how to enhance. if null, then no enhancement

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

iospMessage - sent to iosp.setSpecial() if not null

Returns:

NetcdfDataset or throw Exception

Throws:

IOException

openFile

@Deprecated
public static NetcdfFile openFile(String location,
                                              CancelTask cancelTask)
                                       throws IOException

Deprecated. use NetcdfDatasets.openFile

Factory method for opening a NetcdfFile through the netCDF API.

Parameters:

location - location of dataset.

cancelTask - use to allow task to be cancelled; may be null.

Returns:

NetcdfFile object

Throws:

IOException - on read error

openFile

@Deprecated
public static NetcdfFile openFile(DatasetUrl location,
                                              int buffer_size,
                                              CancelTask cancelTask,
                                              Object spiObject)
                                       throws IOException

Deprecated. use NetcdfDatasets.openFile

Factory method for opening a NetcdfFile through the netCDF API. May be any kind of file that can be read through the netCDF API, including OpenDAP and NcML.

This does not necessarily return a NetcdfDataset, or enhance the dataset; use NetcdfDataset.openDataset() method for that.

Parameters:

location - location of dataset. This may be a

1. local filename (with a file: prefix or no prefix) for netCDF (version 3), hdf5 files, or any file type registered with NetcdfFile.registerIOProvider().
2. OpenDAP dataset URL (with a dods:, dap4:, or http: prefix).
3. NcML file or URL if the location ends with ".xml" or ".ncml"
4. NetCDF file through an HTTP server (http: prefix)
5. thredds dataset (thredds: prefix), see DataFactory.openDataset(String location, ...));

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfFile object

Throws:

IOException - on read error

acquireFile

@Deprecated
public static NetcdfFile acquireFile(DatasetUrl location,
                                                 CancelTask cancelTask)
                                          throws IOException

Deprecated. use NetcdfDatasets.acquireFile

Same as openFile, but file is acquired through the File Cache. You still close with NetcdfFile.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

location - location of file, passed to FileFactory

cancelTask - allow task to be cancelled; may be null.

Returns:

NetcdfFile object

Throws:

IOException - on read error

acquireFile

@Deprecated
public static NetcdfFile acquireFile(ucar.nc2.util.cache.FileFactory factory,
                                                 Object hashKey,
                                                 DatasetUrl location,
                                                 int buffer_size,
                                                 CancelTask cancelTask,
                                                 Object spiObject)
                                          throws IOException

Deprecated. use NetcdfDatasets.acquireFile

Same as openFile, but file is acquired through the File Cache. You still close with NetcdfFile.close(), the release is handled automatically. You must first call initNetcdfFileCache() for caching to actually take place.

Parameters:

factory - if not null, use this factory to read the file. If null, use the default factory.

hashKey - if not null, use as the cache key, else use the location

location - location of file, passed to FileFactory

buffer_size - RandomAccessFile buffer size, if <= 0, use default size

cancelTask - allow task to be cancelled; may be null.

spiObject - sent to iosp.setSpecial(); may be null

Returns:

NetcdfFile object

Throws:

IOException - on read error

getAggregation

@Deprecated
public ucar.nc2.ncml.AggregationIF getAggregation()

Deprecated. Do not use.

If its an NcML aggregation, it has an Aggregation object associated. This is public for use by NcmlWriter.

Returns:

Aggregation or null

setAggregation

@Deprecated
public void setAggregation(ucar.nc2.ncml.AggregationIF agg)

Deprecated. Use NetcdfDataset.builder()

Set the Aggregation object associated with this NcML dataset

Parameters:

agg - the Aggregation object

getCoordinateSystems

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

public List<CoordinateTransform> getCoordinateTransforms()

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

Returns:

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

getCoordinateAxes

public List<CoordinateAxis> getCoordinateAxes()

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

Returns:

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

clearCoordinateSystems

@Deprecated
public void clearCoordinateSystems()

Deprecated. Use NetcdfDataset.builder()

Clear Coordinate System metadata, to allow them to be redone

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 type.

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

public CoordinateTransform findCoordinateTransform(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

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 ucar.nc2.util.cache.FileCacheable

Overrides:

close in class NetcdfFile

Throws:

IOException - if error when closing

release

public void release()
             throws IOException

Specified by:

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

Overrides:

release in class NetcdfFile

Throws:

IOException

reacquire

public void reacquire()
               throws IOException

Specified by:

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

Overrides:

reacquire in class NetcdfFile

Throws:

IOException

getLastModified

public long getLastModified()

Specified by:

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

Overrides:

getLastModified in class NetcdfFile

empty

@Deprecated
public void empty()

Deprecated. Use NetcdfDataset.builder()

Description copied from class: NetcdfFile

Completely empty the objects in the netcdf file. Used for rereading the file on a sync().

Overrides:

empty in class NetcdfFile

syncExtend

@Deprecated
public boolean syncExtend()
                               throws IOException

Deprecated. do not use

Description copied from class: NetcdfFile

Extend the file if needed, in a way that is compatible with the current metadata, that is, does not invalidate structural metadata held by the application. For example, ok if dimension lengths, data has changed. All previous object references (variables, dimensions, etc) remain valid.

Overrides:

syncExtend in class NetcdfFile

Returns:

true if file was extended.

Throws:

IOException - if error

writeNcML

@Deprecated
public void writeNcML(OutputStream os,
                                  String uri)
                           throws IOException

Deprecated. will move in ver 6

Write the NcML representation.

Overrides:

writeNcML in class NetcdfFile

Parameters:

os - write to this Output Stream.

uri - use this for the url attribute; if null use getLocation().

Throws:

IOException - if error

See Also:

NcMLWriter.writeToStream(org.jdom2.Element, java.io.OutputStream)

sort

@Deprecated
public void sort()

Deprecated. Use NetcdfDataset.builder()

Sort Variables, CoordAxes by name.

getReferencedFile

@Deprecated
public NetcdfFile getReferencedFile()

Deprecated. Do not use

A NetcdfDataset usually wraps a NetcdfFile, where the actual I/O happens. This is called the "referenced file". CAUTION : this may have been modified in ways that make it unsuitable for general use.

Returns:

underlying NetcdfFile, or null if none.

getIosp

@Deprecated
public IOServiceProvider getIosp()

Deprecated. do not use

Overrides:

getIosp in class NetcdfFile

setReferencedFile

@Deprecated
public void setReferencedFile(NetcdfFile ncfile)

Deprecated. Use NetcdfDataset.builder()

Set underlying file. CAUTION - normally only done through the constructor.

Parameters:

ncfile - underlying "referenced file"

addCoordinateSystem

@Deprecated
public void addCoordinateSystem(CoordinateSystem cs)

Deprecated. Use NetcdfDataset.builder()

Add a CoordinateSystem to the dataset.

Parameters:

cs - add this CoordinateSystem to the dataset

addCoordinateTransform

@Deprecated
public void addCoordinateTransform(CoordinateTransform ct)

Deprecated. Use NetcdfDataset.builder()

Add a CoordinateTransform to the dataset.

Parameters:

ct - add this CoordinateTransform to the dataset

addCoordinateAxis

@Deprecated
public CoordinateAxis addCoordinateAxis(VariableDS v)

Deprecated. Use NetcdfDataset.builder()

Add a CoordinateAxis to the dataset, by turning the VariableDS into a CoordinateAxis (if needed). Also adds it to the list of variables. Replaces any existing Variable and CoordinateAxis with the same name.

Parameters:

v - make this VariableDS into a CoordinateAxis

Returns:

the CoordinateAxis

addVariable

@Deprecated
public Variable addVariable(Group g,
                                        Variable v)

Deprecated. Use NetcdfDataset.builder()

Description copied from class: NetcdfFile

Add a Variable to the given group.

Overrides:

addVariable in class NetcdfFile

Parameters:

g - add to this group. If group is null, use root group

v - add this Variable

Returns:

the variable that was added

enhance

@Deprecated
public CoordSysBuilderIF enhance()
                                      throws IOException

Deprecated. Use NetcdfDataset.builder()

recalc enhancement info - use default enhance mode

Returns:

the CoordSysBuilder used, for debugging. do not modify or retain a reference

Throws:

IOException - on error

enhance

@Deprecated
public void enhance(Set<NetcdfDataset.Enhance> mode)
                         throws IOException

Deprecated. Use NetcdfDataset.builder()

recalc enhancement info

Parameters:

mode - how to enhance

Throws:

IOException - on error

enhanceNeeded

@Deprecated
public boolean enhanceNeeded(Set<NetcdfDataset.Enhance> want)

Deprecated. Do not use.

is this enhancement already done ?

Parameters:

want - enhancements wanted

Returns:

true if wanted enhancement is not done

setValues

@Deprecated
public void setValues(Variable v,
                                  int npts,
                                  double start,
                                  double incr)

Deprecated. use Variable.setValues()

Generate the list of values from a starting value and an increment. Will reshape to variable if needed.

Parameters:

v - for this variable

npts - number of values, must = v.getSize()

start - starting value

incr - increment

setValues

@Deprecated
public void setValues(Variable v,
                                  List<String> values)
                           throws IllegalArgumentException

Deprecated. use Variable.setValues()

Set the data values from a list of Strings.

Parameters:

v - for this variable

values - list of Strings

Throws:

IllegalArgumentException - if values array not correct size, or values wont parse to the correct type

makeArray

@Deprecated
public static Array makeArray(DataType dtype,
                                          List<String> stringValues)
                                   throws NumberFormatException

Deprecated. use Array#makeArray directly

Make a 1D array from a list of strings.

Parameters:

dtype - data type of the array.

stringValues - list of strings.

Returns:

resulting 1D array.

Throws:

NumberFormatException - if string values not parssable to specified data type

getDetailInfo

public void getDetailInfo(Formatter f)

Show debug / underlying implementation details

Overrides:

getDetailInfo in class NetcdfFile

debugDump

@Deprecated
public static void debugDump(PrintWriter out,
                                         NetcdfDataset ncd)

Deprecated. do not use

Debugging

Parameters:

out - write here

ncd - info about this

getFileTypeId

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"

check

@Deprecated
public void check(Formatter f)

Deprecated. do not use

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

main

public static void main(String[] arg)
                 throws IOException

Main program - cover to ucar.nc2.FileWriter, for all files that can be read by NetcdfDataset.openFile()

ucar.nc2.dataset.NetcdfDataset -in fileIn -out fileOut

where:

• fileIn : path of any CDM readable file
• fileOut: local pathname where netdf-3 file will be written

Parameters:

arg - -in -out [-isLargeFile] [-netcdf4]

Throws:

IOException - on read or write error