ucar.nc2.dataset
Class NetcdfDataset

java.lang.Object
  extended by ucar.nc2.NetcdfFile
      extended by ucar.nc2.dataset.NetcdfDataset
All Implemented Interfaces:
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, 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:

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
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_REMOVE_RECORD_STRUCTURE, reserved
 
Constructor Summary
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
static NetcdfDataset acquireDataset(ucar.nc2.util.cache.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, CancelTask cancelTask)
          Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode.
static NetcdfFile acquireFile(ucar.nc2.util.cache.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 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 enhance()
          recalc enhancement info - use default enhance mode
 void enhance(java.util.Set<NetcdfDataset.Enhance> mode)
          recalc enhancement info
 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.
 ucar.nc2.ncml.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> getCoordSysEnhanceMode()
          Get the default set of Enhancements, and add CoordSystems if not present
static java.util.Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()
          Get the default set of Enhancements
 java.lang.String getDetailInfo()
          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()
 ucar.nc2.iosp.IOServiceProvider getIosp()
          DO NOT USE - public by accident
static boolean getMissingDataIsMissing()
          Get if missing_data attribute is considered isMissing()
static ucar.nc2.util.cache.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
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(ucar.nc2.ncml.Aggregation agg)
          Set the Aggregation object associated with this NcML dataset
static void setDefaultEnhanceMode(java.util.Set<NetcdfDataset.Enhance> mode)
          Set the default set of Enhancements to do for all subsequent dataset opens and acquires.
static void setFillValueIsMissing(boolean b)
          Set if _FillValue attribute is considered isMissing()
static void setHttpClient(org.apache.commons.httpclient.HttpClient client)
          Set the HttpClient object - so that a single, shared instance is used within the application.
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)
          Generate the list of values from a starting value and an increment.
 void setValues(Variable v, java.util.List<java.lang.String> values)
          Set the data values from a list of Strings.
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.
static NetcdfDataset wrap(NetcdfFile ncfile, java.util.Set<NetcdfDataset.Enhance> enhanceMode)
          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, empty, escapeName, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findTopVariable, findVariable, finish, getCacheName, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, isUnlocked, open, open, open, open, open, openInMemory, openInMemory, openInMemory, read, readArrays, readAttributeDouble, readAttributeInteger, readSection, registerIOProvider, registerIOProvider, removeDimension, removeVariable, sendIospMessage, setDebugFlags, setFileCache, setId, setImmutable, setLocation, setProperty, setTitle, toString, unescapeName, writeCDL, writeCDL, writeNcML
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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

setDefaultEnhanceMode

public static void setDefaultEnhanceMode(java.util.Set<NetcdfDataset.Enhance> mode)
Set the default set of Enhancements to do for all subsequent dataset opens and acquires.

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

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

getCoordSysEnhanceMode

public static java.util.Set<NetcdfDataset.Enhance> getCoordSysEnhanceMode()
Get the default set of Enhancements, and add CoordSystems if not present

Returns:
EnhanceMode including CoordSystems

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 ucar.nc2.util.cache.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> enhanceMode)
                          throws java.io.IOException
Make NetcdfFile into NetcdfDataset with given enhance mode

Parameters:
ncfile - wrap this
enhanceMode - using this enhancemode
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(ucar.nc2.util.cache.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
  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: 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 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(ucar.nc2.util.cache.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

setHttpClient

public static void setHttpClient(org.apache.commons.httpclient.HttpClient client)
Set the HttpClient object - so that a single, shared instance is used within the application.

Parameters:
client - the HttpClient object

getAggregation

public ucar.nc2.ncml.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(ucar.nc2.ncml.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 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 ucar.nc2.util.cache.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 ucar.nc2.util.cache.FileCacheable
Overrides:
sync in class NetcdfFile
Returns:
true if file was changed.
Throws:
java.io.IOException

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

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 ucar.nc2.iosp.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"

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 void enhance()
             throws java.io.IOException
recalc enhancement info - use default enhance mode

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

setValues

public void setValues(Variable v,
                      int npts,
                      double start,
                      double incr)
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
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 java.lang.String getDetailInfo()
Show debug / underlying implementation details

Overrides:
getDetailInfo in class NetcdfFile
Returns:
debug / underlying implementation details

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"

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: