ucar.nc2.dataset
Class NetcdfDataset

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

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 either 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();
    }
  

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

See Also:

NetcdfFile

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 add Coordinates.

Method Summary

static NetcdfDataset	acquireDataset(java.lang.String location, CancelTask cancelTask) Same as openDataset, but file is acquired through the NetcdfFileCache, and its always enhanced.
static NetcdfFile	acquireFile(java.lang.String location, CancelTask cancelTask) Same as openFile, but file is acquired through the NetcdfFileCache.
CoordinateAxis	addCoordinateAxis(VariableDS v) Add a CoordinateAxis.
void	addCoordinateSystem(CoordinateSystem cs) Add a CoordinateSystem to the dataset.
void	addCoordinateSystem(VariableEnhanced v, CoordinateSystem cs) Add a CoordinateSystem to a variable.
void	addCoordinateTransform(CoordinateTransform ct) Add a CoordinateTransform to the dataset.
boolean	addRecordStructure() If there is an unlimited dimension, make all variables that use it into an array of structures.
void	close() Close all resources (files, sockets, etc) associated with this dataset.
static void	debugDump(java.io.PrintStream out, NetcdfDataset ncd) debugging
void	enhance() recalc any enhancement info
CoordinateAxis	findCoordinateAxis(java.lang.String fullName) Retrieve the CoordinateAxis with the specified name.
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.
Variable	findStandardVariable(java.lang.String name) Retrieve a "standard" Variable with the specified name, that handles scale, offset, etc.
ucar.nc2.ncml.Aggregation	getAggregation() If its an NcML aggregation, it has an Aggregation object associated.
java.util.List	getCoordinateAxes() Get the list of all CoordinateAxis objects used by this dataset.
java.util.List	getCoordinateSystems() Get the list of all CoordinateSystem objects used by this dataset.
java.util.List	getCoordinateTransforms() Get the list of all CoordinateTransform objects used by this dataset.
boolean	getCoordSysWereAdded() Has Coordinate System metadata been added.
static boolean	getFillValueIsMissing() Get if _FillValue attribute is considered isMissing()
NetcdfDatasetInfo	getInfo() Debugging: get the information from parsing
static boolean	getInvalidDataIsMissing() Get if valid_range attribute is considered isMissing()
static boolean	getMissingDataIsMissing() Get if missing_data attribute is considered isMissing()
NetcdfFile	getReferencedFile() Often a NetcdfDataset wraps a NetcdfFile.
static boolean	getUseNaNs() Get whether to use NaNs for missing values, for efficiency
boolean	isEnhanced() Get whether the dataset was enhanced.
static void	main(java.lang.String[] arg) debug
static Array	makeArray(DataType dtype, java.util.ArrayList stringValues) Make an 1D array from a list of strings.
static Array	makeArray(DataType dtype, int npts, double start, double incr) Make a 1D array from a start and inccr.
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 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.
Array	readData(Variable v, java.util.List section) do not call this directly, use Variable.read() !!
Array	readMemberData(Variable v, java.util.List section, boolean flatten) do not call this directly, use Variable.readSection() !!
void	setAggregation(ucar.nc2.ncml.Aggregation agg) Set the Aggregation object associated with this NcML dataset
void	setCoordSysWereAdded(boolean coordSysWereAdded) Set whether Coordinate System metadata has been added.
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, java.util.ArrayList values) Set the data values from a list of Strings.
void	setValues(Variable v, int npts, double start, double incr) Generate the list of values from a starting value and an increment.
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.
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, addMemberVariable, addVariable, addVariableAttribute, createValidNetcdfObjectName, empty, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findTopVariable, findVariable, finish, getCacheName, getCacheState, getDetailInfo, getDimensions, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getValidNetcdfObjectNamePattern, getVariables, hasUnlimitedDimension, isClosed, isNetcdf3FileFormat, isValidNetcdfObjectName, open, open, open, open, openInMemory, read, readArrays, registerIOProvider, registerIOProvider, removeDimension, removeVariable, setDebugFlags, setDebugOutputStream, setId, setLocation, setTitle, toString, writeCDL

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

NetcdfDataset

public NetcdfDataset(NetcdfFile ncfile,
                     boolean enhance)
              throws java.io.IOException

Transform a NetcdfFile into a NetcdfDataset, optionally add Coordinates. You must not use the underlying NetcdfFile after this call.

Parameters:

ncfile - NetcdfFile to transform.

enhance - if true, process scale/offset/missing and add Coordinate Systems

Throws:

java.io.IOException

NetcdfDataset

public NetcdfDataset()

No-arg Constructor

Method Detail

setUseNaNs

public static void setUseNaNs(boolean b)

Set whether to use NaNs for missing values, for efficiency

getUseNaNs

public static boolean getUseNaNs()

Get whether to use NaNs for missing values, for efficiency

setFillValueIsMissing

public static void setFillValueIsMissing(boolean b)

Set if _FillValue attribute is considered isMissing()

getFillValueIsMissing

public static boolean getFillValueIsMissing()

Get if _FillValue attribute is considered isMissing()

setInvalidDataIsMissing

public static void setInvalidDataIsMissing(boolean b)

Set if valid_range attribute is considered isMissing()

getInvalidDataIsMissing

public static boolean getInvalidDataIsMissing()

Get if valid_range attribute is considered isMissing()

setMissingDataIsMissing

public static void setMissingDataIsMissing(boolean b)

Set if missing_data attribute is considered isMissing()

getMissingDataIsMissing

public static boolean getMissingDataIsMissing()

Get if missing_data attribute is considered isMissing()

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

See Also:

openDataset(String location, boolean enhance, ucar.nc2.util.CancelTask cancelTask)

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

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, process scale/offset/missing and add Coordinate Systems

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

acquireDataset

public static NetcdfDataset acquireDataset(java.lang.String location,
                                           CancelTask cancelTask)
                                    throws java.io.IOException

Same as openDataset, but file is acquired through the NetcdfFileCache, and its always enhanced. You still close with NetcdfDataset.close(), the release is handled automatically.

Throws:

java.io.IOException

See Also:

for meaning of parameters

acquireFile

public static NetcdfFile acquireFile(java.lang.String location,
                                     CancelTask cancelTask)
                              throws java.io.IOException

Same as openFile, but file is acquired through the NetcdfFileCache.

1. Regular NetcDF file is acquired through NetcdfFileCache
2. HTTP Netcdf file is acquired through NetcdfFileCache
3. DODS file is acquired through NetcdfFileCache with factory
4. NcML file is acquired through NetcdfFileCache with factory, underlying file is not acquired

Throws:

java.io.IOException

See Also:

openFile(java.lang.String, ucar.nc2.util.CancelTask)

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

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 turn it into a NetcdfDataset (it may), use NetcdfDataset.open() method for that. It definitely does not add coordinate systems

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

findStandardVariable

public Variable findStandardVariable(java.lang.String name)

Retrieve a "standard" Variable with the specified name, that handles scale, offset, etc. This is for backwards compatibility with 2.1, used in ucar.unidata.geoloc.vertical

Parameters:

name - String which //identifies the desired variable

Returns:

the VariableStandardized, or null if not found

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.

setAggregation

public void setAggregation(ucar.nc2.ncml.Aggregation agg)

Set the Aggregation object associated with this NcML dataset

getCoordinateSystems

public java.util.List getCoordinateSystems()

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

Returns:

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

isEnhanced

public boolean isEnhanced()

Get whether the dataset was enhanced.

getCoordinateTransforms

public java.util.List 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 getCoordinateAxes()

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

Returns:

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

getCoordSysWereAdded

public boolean getCoordSysWereAdded()

Has Coordinate System metadata been added.

setCoordSysWereAdded

public void setCoordSysWereAdded(boolean coordSysWereAdded)

Set whether Coordinate System metadata has been added.

findCoordinateAxis

public CoordinateAxis findCoordinateAxis(java.lang.String fullName)

Retrieve the CoordinateAxis with the specified name.

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.

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.

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, if the unlimited dimension has grown. All previous object references (variables, dimensions, etc) remain valid.

Overrides:

syncExtend in class NetcdfFile

Returns:

true if file was extended.

Throws:

java.io.IOException

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

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 -

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

Throws:

java.io.IOException

addRecordStructure

public boolean addRecordStructure()

Description copied from class: NetcdfFile

If there is an unlimited dimension, make all variables that use it into an array of structures. A Variable called "record" is added. You can then access these through the record structure.

Overrides:

addRecordStructure in class NetcdfFile

Returns:

true if record was actually added on this call

sort

public void sort()

Sort Variables, CoordAxes by name.

getReferencedFile

public NetcdfFile getReferencedFile()

Often a NetcdfDataset wraps a NetcdfFile. For debugging

Returns:

underlying file, or null if none.

setReferencedFile

public void setReferencedFile(NetcdfFile ncfile)

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

readMemberData

public Array readMemberData(Variable v,
                            java.util.List section,
                            boolean flatten)
                     throws java.io.IOException,
                            InvalidRangeException

Description copied from class: NetcdfFile

do not call this directly, use Variable.readSection() !!

Overrides:

readMemberData in class NetcdfFile

Throws:

java.io.IOException

InvalidRangeException

readData

public Array readData(Variable v,
                      java.util.List section)
               throws java.io.IOException,
                      InvalidRangeException

Description copied from class: NetcdfFile

do not call this directly, use Variable.read() !!

Overrides:

readData in class NetcdfFile

Throws:

java.io.IOException

InvalidRangeException

addCoordinateSystem

public void addCoordinateSystem(CoordinateSystem cs)

Add a CoordinateSystem to the dataset.

addCoordinateTransform

public void addCoordinateTransform(CoordinateTransform ct)

Add a CoordinateTransform to the dataset.

addCoordinateSystem

public void addCoordinateSystem(VariableEnhanced v,
                                CoordinateSystem cs)

Add a CoordinateSystem to a variable.

addCoordinateAxis

public CoordinateAxis addCoordinateAxis(VariableDS v)

Add a CoordinateAxis. Also adds it as a variable. Remove any previous with the same name.

enhance

public void enhance()
             throws java.io.IOException

recalc any enhancement info

Throws:

java.io.IOException

setValues

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

Generate the list of values from a starting value and an increment.

Parameters:

npts - number of values

start - starting value

incr - increment

setValues

public void setValues(Variable v,
                      java.util.ArrayList values)
               throws java.lang.NumberFormatException

Set the data values from a list of Strings.

Parameters:

values - list of Strings

Throws:

java.lang.NumberFormatException

makeArray

public static Array makeArray(DataType dtype,
                              java.util.ArrayList stringValues)

Make an 1D array from a list of strings.

Parameters:

dtype - data type of the array.

stringValues - list of strings.

Returns:

resulting 1D array.

makeArray

public static Array makeArray(DataType dtype,
                              int npts,
                              double start,
                              double incr)

Make a 1D array from a start and inccr.

Parameters:

dtype - data type of result. must be convertible to double.

npts - number of points

start - starting values

incr - increment

Returns:

1D array

getInfo

public NetcdfDatasetInfo getInfo()

Debugging: get the information from parsing

debugDump

public static void debugDump(java.io.PrintStream out,
                             NetcdfDataset ncd)

debugging

main

public static void main(java.lang.String[] arg)

debug