NetcdfDataset (NetCDF-Java 4.2 Public and Private API)

java.lang.Object
- ucar.nc2.NetcdfFile
- - ucar.nc2.dataset.NetcdfDataset

All Implemented Interfaces:

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, best practice is to enclose in a try/finally block:
```
 NetcdfDataset ncd = null;
 try {
   ncd = NetcdfDataset.openDataset(fileName);
   ...
 } finally {
   ncd.close();
 }
 
```
By default 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:
- ScaleMissing : process scale/offset/missing attributes, and automatically convert the data.
- ScaleMissingDefer : process scale/offset/missing attributes, but dont automatically convert the data. You can call VariableEnhanced.convertScaleOffsetMissing() on the data manually.
- CoordSystem : extract CoordinateSystem using the CoordSysBuilder plug-in mechanism
- ConvertEnums : automaticlly convert enum values to their corresponding Strings. If you want to do this manually, you can call Variable.lookupEnumString() manually.
Automatic ScaleMissing processing has some overhead, and if you need maximum performance, but still want to use scale/offset/missing value handling, open the NetcdfDataset with ScaleMissingDefer. The VariableDS data type is not promoted, and the data is not converted on a read, but you can call the convertScaleOffsetMissing() routines which will do the conversion on a point-by-point basis.
Author:

caron

See Also:
NetcdfFile

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NetcdfDataset.Enhance
Possible enhancements for a NetcdfDataset

Nested Classes
Modifier and Type	Class and Description
`static class`	`NetcdfDataset.Enhance` Possible enhancements for a NetcdfDataset

Field Summary

Fields
Modifier and Type	Field and Description
`protected static boolean`	`fillValueIsMissing`
`protected static boolean`	`invalidDataIsMissing`
`protected static boolean`	`missingDataIsMissing`
`protected static boolean`	`useNaNs`

Fields inherited from class ucar.nc2.NetcdfFile
cache, cacheName, debugCompress, debugSPI, dimensions, gattributes, id, IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE, IOSP_MESSAGE_RANDOM_ACCESS_FILE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE, location, reserved, reservedCdl, reservedSectionSpec, rootGroup, showRequest, spi, title, unlocked, variables

Constructor Summary

Constructors
Constructor and Description
`NetcdfDataset()` No-arg Constructor
`NetcdfDataset(NetcdfFile ncfile)` Transform a NetcdfFile into a NetcdfDataset.
`NetcdfDataset(NetcdfFile ncfile, boolean enhance)` Transform a NetcdfFile into a NetcdfDataset, optionally enhance it.
`NetcdfDataset(NetcdfFile ncfile, java.util.Set<NetcdfDataset.Enhance> mode)` Transform a NetcdfFile into a NetcdfDataset, optionally enhance it.

Method Summary

Methods
Modifier and Type	Method and Description
`static NetcdfDataset`	`acquireDataset(FileFactory fac, java.lang.String location, java.util.Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, java.lang.Object iospMessage)` Same as openDataset, but file is acquired through the File Cache.
`static NetcdfDataset`	`acquireDataset(java.lang.String location, boolean enhance, CancelTask cancelTask)`
`static NetcdfDataset`	`acquireDataset(java.lang.String location, CancelTask cancelTask)` Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode.
`static NetcdfFile`	`acquireFile(FileFactory factory, java.lang.Object hashKey, java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject)` Same as openFile, but file is acquired through the File Cache.
`static NetcdfFile`	`acquireFile(java.lang.String location, CancelTask cancelTask)` Same as openFile, but file is acquired through the File Cache.
`CoordinateAxis`	`addCoordinateAxis(VariableDS v)` Add a CoordinateAxis to the dataset, by turning the VariableDS into a CoordinateAxis (if needed).
`void`	`addCoordinateSystem(CoordinateSystem cs)` Add a CoordinateSystem to the dataset.
`void`	`addCoordinateTransform(CoordinateTransform ct)` Add a CoordinateTransform to the dataset.
`Variable`	`addVariable(Group g, Variable v)` Add a Variable to the given group.
`void`	`check(java.util.Formatter f)`
`void`	`clearCoordinateSystems()` Clear Coordinate System metadata, to allow them to be redone
`void`	`close()` Close all resources (files, sockets, etc) associated with this dataset.
`static void`	`debugDump(java.io.PrintStream out, NetcdfDataset ncd)` Debugging
`static void`	`disableNetcdfFileCache()`
`void`	`empty()` Completely empty the objects in the netcdf file.
`CoordSysBuilderIF`	`enhance()` recalc enhancement info - use default enhance mode
`void`	`enhance(java.util.Set<NetcdfDataset.Enhance> mode)` recalc enhancement info
`boolean`	`enhanceNeeded(java.util.Set<NetcdfDataset.Enhance> want)` is this enhancement already done ?
`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.
`Aggregation`	`getAggregation()` If its an NcML aggregation, it has an Aggregation object associated.
`java.lang.String`	`getConventionUsed()` Get conventions used to analyse coordinate systems.
`java.util.List<CoordinateAxis>`	`getCoordinateAxes()` Get the list of all CoordinateAxis objects used by this dataset.
`java.util.List<CoordinateSystem>`	`getCoordinateSystems()` Get the list of all CoordinateSystem objects used by this dataset.
`java.util.List<CoordinateTransform>`	`getCoordinateTransforms()` Get the list of all CoordinateTransform objects used by this dataset.
`static java.util.Set<NetcdfDataset.Enhance>`	`getDefaultEnhanceMode()` Get the default set of Enhancements
`void`	`getDetailInfo(java.util.Formatter f)` Show debug / underlying implementation details
`static java.util.Set<NetcdfDataset.Enhance>`	`getEnhanceAll()`
`static java.util.Set<NetcdfDataset.Enhance>`	`getEnhanceDefault()`
`java.util.EnumSet<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.
`static boolean`	`getFillValueIsMissing()` Get if _FillValue attribute is considered isMissing()
`static boolean`	`getInvalidDataIsMissing()` Get if valid_range attribute is considered isMissing()
`IOServiceProvider`	`getIosp()` DO NOT USE - public by accident
`static boolean`	`getMissingDataIsMissing()` Get if missing_data attribute is considered isMissing()
`static FileCache`	`getNetcdfFileCache()` Get the File Cache
`NetcdfFile`	`getReferencedFile()` A NetcdfDataset usually wraps a NetcdfFile, where the actual I/O happens.
`static boolean`	`getUseNaNs()` Get whether to use NaNs for missing values, for efficiency
`static void`	`initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int period)` Enable file caching.
`static void`	`initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int hardLimit, int period)` Enable file caching.
`static void`	`main(java.lang.String[] arg)` Main program - cover to ucar.nc2.FileWriter, for all files that can be read by NetcdfDataset.openFile()
`static Array`	`makeArray(DataType dtype, java.util.List<java.lang.String> stringValues)` Deprecated. use Array#makeArray directly
`protected java.lang.Boolean`	`makeRecordStructure()` If there is an unlimited dimension, make all variables that use it into a Structure.
`static NetcdfDataset`	`openDataset(java.lang.String location)` Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
`static NetcdfDataset`	`openDataset(java.lang.String location, boolean enhance, CancelTask cancelTask)` Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
`static NetcdfDataset`	`openDataset(java.lang.String location, boolean enhance, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject)` Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
`static NetcdfDataset`	`openDataset(java.lang.String location, java.util.Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject)` Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
`static NetcdfFile`	`openFile(java.lang.String location, CancelTask cancelTask)` Factory method for opening a NetcdfFile through the netCDF API.
`static NetcdfFile`	`openFile(java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject)` Factory method for opening a NetcdfFile through the netCDF API.
`static java.util.Set<NetcdfDataset.Enhance>`	`parseEnhanceMode(java.lang.String enhanceMode)` Find the set of Enhancements that matches the String.
`void`	`setAggregation(Aggregation agg)` Set the Aggregation object associated with this NcML dataset
`static void`	`setFillValueIsMissing(boolean b)` Set if _FillValue attribute is considered isMissing()
`static void`	`setInvalidDataIsMissing(boolean b)` Set if valid_range attribute is considered isMissing()
`static void`	`setMissingDataIsMissing(boolean b)` Set if missing_data attribute is considered isMissing()
`void`	`setReferencedFile(NetcdfFile ncfile)` Set underlying file.
`static void`	`setUseNaNs(boolean b)` Set whether to use NaNs for missing values, for efficiency
`void`	`setValues(Variable v, int npts, double start, double incr)` Deprecated. use Variable.setValues()
`void`	`setValues(Variable v, java.util.List<java.lang.String> values)` Deprecated. use Variable.setValues()
`static void`	`shutdown()` Call when application exits, if you have previously called initNetcdfFileCache.
`void`	`sort()` Sort Variables, CoordAxes by name.
`boolean`	`sync()` Check if file has changed, and reread metadata if needed.
`boolean`	`syncExtend()` 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.
`protected java.lang.String`	`toStringDebug(java.lang.Object o)` Access to iosp debugging info.
`static NetcdfDataset`	`wrap(NetcdfFile ncfile, java.util.Set<NetcdfDataset.Enhance> mode)` Make NetcdfFile into NetcdfDataset with given enhance mode
`void`	`writeNcML(java.io.OutputStream os, java.lang.String uri)` Write the NcML representation.
`void`	`writeNcMLG(java.io.OutputStream os, boolean showCoords, java.lang.String uri)` Write the NcML-G representation.

Methods inherited from class ucar.nc2.NetcdfFile
addAttribute, addDimension, addGroup, addStringVariable, addVariable, addVariableAttribute, canOpen, escapeName, escapeNameCDL, escapeNameSectionSpec, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findVariable, finish, getCacheName, getDetailInfo, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getLocation, getRootGroup, getStructureIterator, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, isUnlocked, makeFullName, makeFullName, makeFullNameEscaped, makeFullNameEscapedSectionSpec, makeFullNameWithString, makeRootGroup, makeValidCdmObjectName, open, open, open, open, open, openInMemory, openInMemory, openInMemory, openInMemory, read, readArrays, readAttributeDouble, readAttributeInteger, readData, readSection, readToByteChannel, registerIOProvider, registerIOProvider, removeDimension, removeRecordStructure, removeVariable, sendIospMessage, setCacheName, setDebugFlags, setFileCache, setId, setImmutable, setLocation, setProperty, setTitle, showCached, showProxies, toString, toStringEnd, toStringStart, unescapeName, writeCDL, writeCDL, writeNcML

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - useNaNs
```
protected static boolean useNaNs
```
  - fillValueIsMissing
```
protected static boolean fillValueIsMissing
```
  - invalidDataIsMissing
```
protected static boolean invalidDataIsMissing
```
  - missingDataIsMissing
```
protected static boolean missingDataIsMissing
```
- Constructor Detail
  - NetcdfDataset
```
public NetcdfDataset(NetcdfFile ncfile)
              throws java.io.IOException
```
    Transform a NetcdfFile into a NetcdfDataset. You must not use the underlying NetcdfFile after this call.
    
    Parameters:
    ncfile - NetcdfFile to transform.
    
    Throws:
    
    java.io.IOException - on read error
  - NetcdfDataset
```
public NetcdfDataset(NetcdfFile ncfile,
             boolean enhance)
              throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - NetcdfDataset
```
public NetcdfDataset(NetcdfFile ncfile,
             java.util.Set<NetcdfDataset.Enhance> mode)
              throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - NetcdfDataset
```
public NetcdfDataset()
```
    No-arg Constructor
- Method Detail
  - getEnhanceAll
```
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceAll()
```
  - getEnhanceNone
```
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceNone()
```
  - getEnhanceDefault
```
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceDefault()
```
  - getDefaultEnhanceMode
```
public static java.util.Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()
```
    Get the default set of Enhancements
    
    Returns:
    the the default set of Enhancements for open and acquire factory methods
  - parseEnhanceMode
```
public static java.util.Set<NetcdfDataset.Enhance> parseEnhanceMode(java.lang.String enhanceMode)
```
    Find the set of Enhancements that matches the String. For backwards compatibility, 'true' = All.
    
    Parameters:
    enhanceMode - : 'None', 'All', 'ScaleMissing', 'ScaleMissingDefer', 'CoordSystems', All', case insensitive
    
    Returns:
    EnumSet
  - setUseNaNs
```
public static void setUseNaNs(boolean b)
```
    Set whether to use NaNs for missing values, for efficiency
    
    Parameters:
    b - true if want to replace missing values with NaNs (default true)
  - getUseNaNs
```
public static boolean getUseNaNs()
```
    Get whether to use NaNs for missing values, for efficiency
    
    Returns:
    whether to use NaNs for missing values, for efficiency
  - setFillValueIsMissing
```
public static void setFillValueIsMissing(boolean b)
```
    Set if _FillValue attribute is considered isMissing()
    
    Parameters:
    b - true if _FillValue are missing (default true)
  - getFillValueIsMissing
```
public static boolean getFillValueIsMissing()
```
    Get if _FillValue attribute is considered isMissing()
    
    Returns:
    if _FillValue attribute is considered isMissing()
  - setInvalidDataIsMissing
```
public static void setInvalidDataIsMissing(boolean b)
```
    Set if valid_range attribute is considered isMissing()
    
    Parameters:
    b - true if valid_range are missing (default true)
  - getInvalidDataIsMissing
```
public static boolean getInvalidDataIsMissing()
```
    Get if valid_range attribute is considered isMissing()
    
    Returns:
    if valid_range attribute is considered isMissing()
  - setMissingDataIsMissing
```
public static void setMissingDataIsMissing(boolean b)
```
    Set if missing_data attribute is considered isMissing()
    
    Parameters:
    b - true if missing_data are missing (default true)
  - getMissingDataIsMissing
```
public static boolean getMissingDataIsMissing()
```
    Get if missing_data attribute is considered isMissing()
    
    Returns:
    if missing_data attribute is considered isMissing()
  - initNetcdfFileCache
```
public static void initNetcdfFileCache(int minElementsInMemory,
                       int maxElementsInMemory,
                       int period)
```
    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.
  - initNetcdfFileCache
```
public static void initNetcdfFileCache(int minElementsInMemory,
                       int maxElementsInMemory,
                       int hardLimit,
                       int period)
```
    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
```
public static void disableNetcdfFileCache()
```
  - shutdown
```
public static void 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
```
public static FileCache getNetcdfFileCache()
```
    Get the File Cache
    
    Returns:
    File Cache or null if not enabled.
  - wrap
```
public static NetcdfDataset wrap(NetcdfFile ncfile,
                 java.util.Set<NetcdfDataset.Enhance> mode)
                          throws java.io.IOException
```
    Make NetcdfFile into NetcdfDataset with given enhance mode
    
    Parameters:
    ncfile - wrap this
    mode - using this enhance mode (may be null)
    
    Returns:
    NetcdfDataset wrapping the given ncfile
    
    Throws:
    
    java.io.IOException - on io error
  - openDataset
```
public static NetcdfDataset openDataset(java.lang.String location)
                                 throws java.io.IOException
```
    Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
    
    Parameters:
    location - location of file
    
    Returns:
    NetcdfDataset object
    
    Throws:
    
    java.io.IOException - on read error
  - openDataset
```
public static NetcdfDataset openDataset(java.lang.String location,
                        boolean enhance,
                        CancelTask cancelTask)
                                 throws java.io.IOException
```
    Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables.
    
    Parameters:
    location - location of file
    enhance - if true, process scale/offset/missing and add Coordinate Systems
    cancelTask - allow task to be cancelled; may be null.
    
    Returns:
    NetcdfDataset object
    
    Throws:
    
    java.io.IOException - on read error
  - openDataset
```
public static NetcdfDataset openDataset(java.lang.String location,
                        boolean enhance,
                        int buffer_size,
                        CancelTask cancelTask,
                        java.lang.Object spiObject)
                                 throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - openDataset
```
public static NetcdfDataset openDataset(java.lang.String location,
                        java.util.Set<NetcdfDataset.Enhance> enhanceMode,
                        int buffer_size,
                        CancelTask cancelTask,
                        java.lang.Object spiObject)
                                 throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - acquireDataset
```
public static NetcdfDataset acquireDataset(java.lang.String location,
                           CancelTask cancelTask)
                                    throws java.io.IOException
```
    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
    cancelTask - allow task to be cancelled; may be null.
    
    Returns:
    NetcdfDataset object
    
    Throws:
    
    java.io.IOException - on read error
  - acquireDataset
```
public static NetcdfDataset acquireDataset(java.lang.String location,
                           boolean enhance,
                           CancelTask cancelTask)
                                    throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - acquireDataset
```
public static NetcdfDataset acquireDataset(FileFactory fac,
                           java.lang.String location,
                           java.util.Set<NetcdfDataset.Enhance> enhanceMode,
                           int buffer_size,
                           CancelTask cancelTask,
                           java.lang.Object iospMessage)
                                    throws java.io.IOException
```
    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.
    location - 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 object
    
    Throws:
    
    java.io.IOException - on read error
  - openFile
```
public static NetcdfFile openFile(java.lang.String location,
                  CancelTask cancelTask)
                           throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - openFile
```
public static NetcdfFile openFile(java.lang.String location,
                  int buffer_size,
                  CancelTask cancelTask,
                  java.lang.Object spiObject)
                           throws java.io.IOException
```
    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
    
    local filename (with a file: prefix or no prefix) for netCDF (version 3), hdf5 files, or any file type registered with NetcdfFile.registerIOProvider().
    OpenDAP dataset URL (with a dods: or http: prefix).
    NcML file or URL if the location ends with ".xml" or ".ncml"
    NetCDF file through an HTTP server (http: prefix)
    thredds dataset (thredds: prefix), see ThreddsDataFactory.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:
    
    java.io.IOException - on read error
  - acquireFile
```
public static NetcdfFile acquireFile(java.lang.String location,
                     CancelTask cancelTask)
                              throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - acquireFile
```
public static NetcdfFile acquireFile(FileFactory factory,
                     java.lang.Object hashKey,
                     java.lang.String location,
                     int buffer_size,
                     CancelTask cancelTask,
                     java.lang.Object spiObject)
                              throws java.io.IOException
```
    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:
    
    java.io.IOException - on read error
  - getAggregation
```
public Aggregation getAggregation()
```
    If its an NcML aggregation, it has an Aggregation object associated. This is public for use by NcmlWriter.
    
    Returns:
    Aggregation or null
  - setAggregation
```
public void setAggregation(Aggregation agg)
```
    Set the Aggregation object associated with this NcML dataset
    
    Parameters:
    agg - the Aggregation object
  - getCoordinateSystems
```
public java.util.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 java.lang.String getConventionUsed()
```
    Get conventions used to analyse coordinate systems.
    
    Returns:
    conventions used to analyse coordinate systems
  - getEnhanceMode
```
public java.util.EnumSet<NetcdfDataset.Enhance> getEnhanceMode()
```
    Get the current state of dataset enhancement.
    
    Returns:
    the current state of dataset enhancement.
  - getCoordinateTransforms
```
public java.util.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 java.util.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
```
public void clearCoordinateSystems()
```
    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(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
  - 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 FileCacheable
    
    Overrides:
    
    close in class NetcdfFile
    
    Throws:
    
    java.io.IOException
  - sync
```
public boolean sync()
             throws java.io.IOException
```
    Check if file has changed, and reread metadata if needed. All previous object references (variables, dimensions, etc) may become invalid - you must re-obtain.
    
    Specified by:
    
    sync in interface FileCacheable
    
    Overrides:
    
    sync in class NetcdfFile
    
    Returns:
    true if file was changed.
    
    Throws:
    
    java.io.IOException
  - empty
```
public void empty()
```
    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
```
public boolean syncExtend()
                   throws java.io.IOException
```
    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:
    
    java.io.IOException - if error
  - writeNcML
```
public void writeNcML(java.io.OutputStream os,
             java.lang.String uri)
               throws java.io.IOException
```
    Write the NcML representation.
    
    Overrides:
    
    writeNcML in class NetcdfFile
    
    Parameters:
    os - write to this Output Stream.
    uri - use this for the uri attribute; if null use getLocation().
    
    Throws:
    
    java.io.IOException
    See Also:
    NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
  - writeNcMLG
```
public void writeNcMLG(java.io.OutputStream os,
              boolean showCoords,
              java.lang.String uri)
                throws java.io.IOException
```
    Write the NcML-G representation.
    
    Parameters:
    os - write to this Output Stream.
    showCoords - shoe the values of coordinate axes
    uri - use this for the uri attribute; if null use getLocation().
    
    Throws:
    
    java.io.IOException - on write error
  - makeRecordStructure
```
protected java.lang.Boolean makeRecordStructure()
```
    Description copied from class: NetcdfFile
    
    If there is an unlimited dimension, make all variables that use it into a Structure. A Variable called "record" is added. You can then access these through the record structure.
    
    Overrides:
    
    makeRecordStructure in class NetcdfFile
    
    Returns:
    true if it has a Nectdf-3 record structure
  - sort
```
public void sort()
```
    Sort Variables, CoordAxes by name.
  - getReferencedFile
```
public NetcdfFile getReferencedFile()
```
    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
```
public IOServiceProvider getIosp()
```
    Description copied from class: NetcdfFile
    
    DO NOT USE - public by accident
    
    Overrides:
    
    getIosp in class NetcdfFile
    
    Returns:
    the IOSP for this NetcdfFile
  - setReferencedFile
```
public void setReferencedFile(NetcdfFile ncfile)
```
    Set underlying file. CAUTION - normally only done through the constructor.
    
    Parameters:
    ncfile - underlying "referenced file"
  - toStringDebug
```
protected java.lang.String toStringDebug(java.lang.Object o)
```
    Description copied from class: NetcdfFile
    
    Access to iosp debugging info.
    
    Overrides:
    
    toStringDebug in class NetcdfFile
    
    Parameters:
    o - must be a Variable, Dimension, Attribute, or Group
    
    Returns:
    debug info for this object.
  - addCoordinateSystem
```
public void addCoordinateSystem(CoordinateSystem cs)
```
    Add a CoordinateSystem to the dataset.
    
    Parameters:
    cs - add this CoordinateSystem to the dataset
  - addCoordinateTransform
```
public void addCoordinateTransform(CoordinateTransform ct)
```
    Add a CoordinateTransform to the dataset.
    
    Parameters:
    ct - add this CoordinateTransform to the dataset
  - addCoordinateAxis
```
public CoordinateAxis addCoordinateAxis(VariableDS v)
```
    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
```
public Variable addVariable(Group g,
                   Variable v)
```
    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
```
public CoordSysBuilderIF enhance()
                          throws java.io.IOException
```
    recalc enhancement info - use default enhance mode
    
    Returns:
    the CoordSysBuilder used, for debugging. do not modify or retain a reference
    
    Throws:
    
    java.io.IOException - on error
  - enhance
```
public void enhance(java.util.Set<NetcdfDataset.Enhance> mode)
             throws java.io.IOException
```
    recalc enhancement info
    
    Parameters:
    mode - how to enhance
    
    Throws:
    
    java.io.IOException - on error
  - enhanceNeeded
```
public boolean enhanceNeeded(java.util.Set<NetcdfDataset.Enhance> want)
                      throws java.io.IOException
```
    is this enhancement already done ?
    
    Parameters:
    want - enhancements wanted
    
    Returns:
    true if wanted enhancement is not done
    
    Throws:
    
    java.io.IOException - on error
  - setValues
```
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
```
public void setValues(Variable v,
             java.util.List<java.lang.String> values)
               throws java.lang.IllegalArgumentException
```
    Deprecated. use Variable.setValues()
    
    Set the data values from a list of Strings.
    
    Parameters:
    v - for this variable
    values - list of Strings
    
    Throws:
    
    java.lang.IllegalArgumentException - if values array not correct size, or values wont parse to the correct type
  - makeArray
```
public static Array makeArray(DataType dtype,
              java.util.List<java.lang.String> stringValues)
                       throws java.lang.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:
    
    java.lang.NumberFormatException - if string values not parssable to specified data type
  - getDetailInfo
```
public void getDetailInfo(java.util.Formatter f)
```
    Show debug / underlying implementation details
    
    Overrides:
    
    getDetailInfo in class NetcdfFile
  - debugDump
```
public static void debugDump(java.io.PrintStream out,
             NetcdfDataset ncd)
```
    Debugging
    
    Parameters:
    out - write here
    ncd - info about this
  - 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:
    "http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"
  - 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:
    "http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"
  - check
```
public void check(java.util.Formatter f)
```
  - main
```
public static void main(java.lang.String[] arg)
                 throws java.io.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:
    Parameters:
    arg - -in fileIn -out fileOut [-delay millisecs]
    
    Throws:
    
    java.io.IOException - on read or write error

Class NetcdfDataset

Nested Class Summary

Field Summary

Fields inherited from class ucar.nc2.NetcdfFile

Constructor Summary

Method Summary

Methods inherited from class ucar.nc2.NetcdfFile

Methods inherited from class java.lang.Object

Field Detail

useNaNs

fillValueIsMissing

invalidDataIsMissing

missingDataIsMissing

Constructor Detail

NetcdfDataset

NetcdfDataset

NetcdfDataset

NetcdfDataset

Method Detail

getEnhanceAll

getEnhanceNone

getEnhanceDefault

getDefaultEnhanceMode

parseEnhanceMode

setUseNaNs

getUseNaNs

setFillValueIsMissing

getFillValueIsMissing

setInvalidDataIsMissing

getInvalidDataIsMissing

setMissingDataIsMissing

getMissingDataIsMissing

initNetcdfFileCache

initNetcdfFileCache

disableNetcdfFileCache

shutdown

getNetcdfFileCache

wrap

openDataset

openDataset

openDataset

openDataset

acquireDataset

acquireDataset

acquireDataset

openFile

openFile

acquireFile

acquireFile

getAggregation

setAggregation

getCoordinateSystems

getConventionUsed

getEnhanceMode

getCoordinateTransforms

getCoordinateAxes

clearCoordinateSystems

findCoordinateAxis

findCoordinateAxis

findCoordinateSystem

findCoordinateTransform

close

sync

empty

syncExtend

writeNcML

writeNcMLG

makeRecordStructure

sort

getReferencedFile

getIosp

setReferencedFile

toStringDebug

addCoordinateSystem

addCoordinateTransform

addCoordinateAxis

addVariable

enhance

enhance

enhanceNeeded