Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

ucar.nc2.dataset
Class NetcdfDataset

java.lang.Object
  extended by ucar.nc2.NetcdfFile
      extended by 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

Field Summary
protected static boolean fillValueIsMissing
           
protected static boolean invalidDataIsMissing
           
protected static boolean missingDataIsMissing
           
protected static boolean useNaNs
           
 
Fields inherited from class ucar.nc2.NetcdfFile
addedRecordStructure, cacheName, cacheState, dimensions, gattributes, id, isClosed, location, rootGroup, spi, title, variables
 
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.
 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.
 java.lang.String getDetailInfo()
          Show debug / underlying implementation details
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)
           
static void main2(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() !!
protected  void replaceDimension(Variable v, Dimension d)
          Replace a Dimension in a Variable.
protected  void replaceGroupVariables(Group g, java.util.ArrayList vlist)
          Replace the group's list of variables.
protected  void replaceStructureMembers(Structure s, java.util.ArrayList vlist)
          Replace the structure's list of variables.
 void setAggregation(Aggregation agg)
          Set the Aggregation object associated with this NcML dataset
protected  void setCacheName(java.lang.String cacheName)
          Used by NetcdfDatasetCache.
protected  void setCacheState(int cacheState)
          Used by NetcdfDatasetCache.
 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.
protected  java.lang.String toStringDebug(java.lang.Object o)
          Debug info for this object.
 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, finalize, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findTopVariable, findVariable, finish, getCacheName, getCacheState, getDimensions, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getValidNetcdfObjectNamePattern, getVariables, hasRecordStructure, hasUnlimitedDimension, isClosed, isNetcdf3FileFormat, isValidNetcdfObjectName, makeFullName, makeFullNameWithString, open, open, open, open, open, openInMemory, openInMemory, read, readArrays, registerIOProvider, registerIOProvider, removeDimension, removeVariable, setDebugFlags, setDebugOutputStream, setId, setLocation, setProperty, setTitle, toString, toStringEnd, toStringStart, writeCDL
 
Methods inherited from class java.lang.Object
clone, equals, 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

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 Aggregation getAggregation()
If its an NcML aggregation, it has an Aggregation object associated. This is public for use by NcmlWriter.

setAggregation

public void setAggregation(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

setCacheState

protected void setCacheState(int cacheState)
Used by NetcdfDatasetCache.

Overrides:
setCacheState in class NetcdfFile

setCacheName

protected void setCacheName(java.lang.String cacheName)
Used by NetcdfDatasetCache.

Overrides:
setCacheName in class NetcdfFile

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

toStringDebug

protected java.lang.String toStringDebug(java.lang.Object o)
Description copied from class: NetcdfFile
Debug info for this object.

Overrides:
toStringDebug in class NetcdfFile

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.

replaceDimension

protected void replaceDimension(Variable v,
                                Dimension d)
Replace a Dimension in a Variable.

Overrides:
replaceDimension in class NetcdfFile
Parameters:
v - replace in this Variable.
d - replace existing dimension of the same name.

replaceGroupVariables

protected void replaceGroupVariables(Group g,
                                     java.util.ArrayList vlist)
Replace the group's list of variables. For copy construction.

Overrides:
replaceGroupVariables in class NetcdfFile

replaceStructureMembers

protected void replaceStructureMembers(Structure s,
                                       java.util.ArrayList vlist)
Replace the structure's list of variables. For copy construction.

Overrides:
replaceStructureMembers in class NetcdfFile

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.IllegalArgumentException
Set the data values from a list of Strings.

Parameters:
values - list of Strings
Throws:
java.lang.NumberFormatException
java.lang.IllegalArgumentException

makeArray

public static Array makeArray(DataType dtype,
                              java.util.ArrayList stringValues)
                       throws java.lang.NumberFormatException
Make an 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

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

getDetailInfo

public java.lang.String getDetailInfo()
Show debug / underlying implementation details

Overrides:
getDetailInfo in class NetcdfFile

getInfo

public NetcdfDatasetInfo getInfo()
Debugging: get the information from parsing

debugDump

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

main2

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

main

public static void main(java.lang.String[] arg)
                 throws java.io.IOException
Throws:
java.io.IOException
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD