|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectucar.nc2.NetcdfFile
ucar.nc2.dataset.NetcdfDataset
public class NetcdfDataset
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:
NetcdfFile
Nested Class Summary | |
---|---|
static class |
NetcdfDataset.Enhance
Possible enhancements for a NetcdfDataset |
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 |
---|
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 | |
---|---|
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,
Set<NetcdfDataset.Enhance> mode)
Transform a NetcdfFile into a NetcdfDataset, optionally enhance it. |
Method Summary | |
---|---|
static NetcdfDataset |
acquireDataset(FileFactory fac,
String location,
Set<NetcdfDataset.Enhance> enhanceMode,
int buffer_size,
CancelTask cancelTask,
Object iospMessage)
Same as openDataset, but file is acquired through the File Cache. |
static NetcdfDataset |
acquireDataset(String location,
boolean enhance,
CancelTask cancelTask)
|
static NetcdfDataset |
acquireDataset(String location,
CancelTask cancelTask)
Same as openDataset, but file is acquired through the File Cache, with defaultEnhanceMode. |
static NetcdfFile |
acquireFile(FileFactory factory,
Object hashKey,
String location,
int buffer_size,
CancelTask cancelTask,
Object spiObject)
Same as openFile, but file is acquired through the File Cache. |
static NetcdfFile |
acquireFile(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(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(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(Set<NetcdfDataset.Enhance> mode)
recalc enhancement info |
boolean |
enhanceNeeded(Set<NetcdfDataset.Enhance> want)
is this enhancement already done ? |
CoordinateAxis |
findCoordinateAxis(AxisType type)
Retrieve the CoordinateAxis with the specified Axis Type. |
CoordinateAxis |
findCoordinateAxis(String fullName)
Retrieve the CoordinateAxis with the specified type. |
CoordinateSystem |
findCoordinateSystem(String name)
Retrieve the CoordinateSystem with the specified name. |
CoordinateTransform |
findCoordinateTransform(String name)
Retrieve the CoordinateTransform with the specified name. |
Aggregation |
getAggregation()
If its an NcML aggregation, it has an Aggregation object associated. |
String |
getConventionUsed()
Get conventions used to analyse coordinate systems. |
List<CoordinateAxis> |
getCoordinateAxes()
Get the list of all CoordinateAxis objects used by this dataset. |
List<CoordinateSystem> |
getCoordinateSystems()
Get the list of all CoordinateSystem objects used by this dataset. |
List<CoordinateTransform> |
getCoordinateTransforms()
Get the list of all CoordinateTransform objects used by this dataset. |
static Set<NetcdfDataset.Enhance> |
getDefaultEnhanceMode()
Get the default set of Enhancements |
void |
getDetailInfo(Formatter f)
Show debug / underlying implementation details |
static Set<NetcdfDataset.Enhance> |
getEnhanceAll()
|
static Set<NetcdfDataset.Enhance> |
getEnhanceDefault()
|
EnumSet<NetcdfDataset.Enhance> |
getEnhanceMode()
Get the current state of dataset enhancement. |
static Set<NetcdfDataset.Enhance> |
getEnhanceNone()
|
String |
getFileTypeDescription()
Get a human-readable description for this file type. |
String |
getFileTypeId()
Get the file type id for the underlying data source. |
static boolean |
getFillValueIsMissing()
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(String[] arg)
Main program - cover to ucar.nc2.FileWriter, for all files that can be read by NetcdfDataset.openFile() |
static Array |
makeArray(DataType dtype,
List<String> stringValues)
Deprecated. use Array#makeArray directly |
protected Boolean |
makeRecordStructure()
If there is an unlimited dimension, make all variables that use it into a Structure. |
static NetcdfDataset |
openDataset(String location)
Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables. |
static NetcdfDataset |
openDataset(String location,
boolean enhance,
CancelTask cancelTask)
Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables. |
static NetcdfDataset |
openDataset(String location,
boolean enhance,
int buffer_size,
CancelTask cancelTask,
Object spiObject)
Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables. |
static NetcdfDataset |
openDataset(String location,
Set<NetcdfDataset.Enhance> enhanceMode,
int buffer_size,
CancelTask cancelTask,
Object spiObject)
Factory method for opening a dataset through the netCDF API, and identifying its coordinate variables. |
static NetcdfFile |
openFile(String location,
CancelTask cancelTask)
Factory method for opening a NetcdfFile through the netCDF API. |
static NetcdfFile |
openFile(String location,
int buffer_size,
CancelTask cancelTask,
Object spiObject)
Factory method for opening a NetcdfFile through the netCDF API. |
static Set<NetcdfDataset.Enhance> |
parseEnhanceMode(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,
List<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 String |
toStringDebug(Object o)
Access to iosp debugging info. |
static NetcdfDataset |
wrap(NetcdfFile ncfile,
Set<NetcdfDataset.Enhance> mode)
Make NetcdfFile into NetcdfDataset with given enhance mode |
void |
writeNcML(OutputStream os,
String uri)
Write the NcML representation. |
void |
writeNcMLG(OutputStream os,
boolean showCoords,
String uri)
Write the NcML-G representation. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
protected static boolean useNaNs
protected static boolean fillValueIsMissing
protected static boolean invalidDataIsMissing
protected static boolean missingDataIsMissing
Constructor Detail |
---|
public NetcdfDataset(NetcdfFile ncfile) throws IOException
ncfile
- NetcdfFile to transform.
IOException
- on read errorpublic NetcdfDataset(NetcdfFile ncfile, boolean enhance) throws IOException
ncfile
- NetcdfFile to transform, do not use independently after this.enhance
- if true, enhance with defaultEnhanceMode
IOException
- on read errorpublic NetcdfDataset(NetcdfFile ncfile, Set<NetcdfDataset.Enhance> mode) throws IOException
ncfile
- NetcdfFile to transform, do not use independently after this.mode
- set of enhance modes. If null, then none
IOException
- on read errorpublic NetcdfDataset()
Method Detail |
---|
public static Set<NetcdfDataset.Enhance> getEnhanceAll()
public static Set<NetcdfDataset.Enhance> getEnhanceNone()
public static Set<NetcdfDataset.Enhance> getEnhanceDefault()
public static Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()
public static Set<NetcdfDataset.Enhance> parseEnhanceMode(String enhanceMode)
enhanceMode
- : 'None', 'All', 'ScaleMissing', 'ScaleMissingDefer', 'CoordSystems', All', case insensitive
public static void setUseNaNs(boolean b)
b
- true if want to replace missing values with NaNs (default true)public static boolean getUseNaNs()
public static void setFillValueIsMissing(boolean b)
b
- true if _FillValue are missing (default true)public static boolean getFillValueIsMissing()
public static void setInvalidDataIsMissing(boolean b)
b
- true if valid_range are missing (default true)public static boolean getInvalidDataIsMissing()
public static void setMissingDataIsMissing(boolean b)
b
- true if missing_data are missing (default true)public static boolean getMissingDataIsMissing()
public static void initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int period)
minElementsInMemory
- keep this number in the cachemaxElementsInMemory
- trigger a cleanup if it goes over this number.period
- (secs) do periodic cleanups every this number of seconds.public static void initNetcdfFileCache(int minElementsInMemory, int maxElementsInMemory, int hardLimit, int period)
minElementsInMemory
- keep this number in the cachemaxElementsInMemory
- 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.public static void disableNetcdfFileCache()
public static void shutdown()
public static FileCache getNetcdfFileCache()
public static NetcdfDataset wrap(NetcdfFile ncfile, Set<NetcdfDataset.Enhance> mode) throws IOException
ncfile
- wrap thismode
- using this enhance mode (may be null)
IOException
- on io errorpublic static NetcdfDataset openDataset(String location) throws IOException
location
- location of file
IOException
- on read errorpublic static NetcdfDataset openDataset(String location, boolean enhance, CancelTask cancelTask) throws IOException
location
- location of fileenhance
- if true, process scale/offset/missing and add Coordinate SystemscancelTask
- allow task to be cancelled; may be null.
IOException
- on read errorpublic static NetcdfDataset openDataset(String location, boolean enhance, int buffer_size, CancelTask cancelTask, Object spiObject) throws IOException
location
- location of fileenhance
- if true, use defaultEnhanceMode, else no enhancementsbuffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.spiObject
- sent to iosp.setSpecial() if not null
IOException
- on read errorpublic static NetcdfDataset openDataset(String location, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object spiObject) throws IOException
location
- location of fileenhanceMode
- set of enhancements. If null, then nonebuffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.spiObject
- sent to iosp.setSpecial() if not null
IOException
- on read errorpublic static NetcdfDataset acquireDataset(String location, CancelTask cancelTask) throws IOException
location
- location of file, passed to FileFactorycancelTask
- allow task to be cancelled; may be null.
IOException
- on read errorpublic static NetcdfDataset acquireDataset(String location, boolean enhance, CancelTask cancelTask) throws IOException
IOException
public static NetcdfDataset acquireDataset(FileFactory fac, String location, Set<NetcdfDataset.Enhance> enhanceMode, int buffer_size, CancelTask cancelTask, Object iospMessage) throws IOException
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 FileFactoryenhanceMode
- how to enhance. if null, then no enhancementbuffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.iospMessage
- sent to iosp.setSpecial() if not null
IOException
- on read errorpublic static NetcdfFile openFile(String location, CancelTask cancelTask) throws IOException
location
- location of dataset.cancelTask
- use to allow task to be cancelled; may be null.
IOException
- on read errorpublic static NetcdfFile openFile(String location, int buffer_size, CancelTask cancelTask, Object spiObject) throws IOException
This does not necessarily return a NetcdfDataset, or enhance the dataset; use NetcdfDataset.openDataset() method for that.
location
- location of dataset. This may be a
buffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.spiObject
- sent to iosp.setSpecial() if not null
IOException
- on read errorpublic static NetcdfFile acquireFile(String location, CancelTask cancelTask) throws IOException
location
- location of file, passed to FileFactorycancelTask
- allow task to be cancelled; may be null.
IOException
- on read errorpublic static NetcdfFile acquireFile(FileFactory factory, Object hashKey, String location, int buffer_size, CancelTask cancelTask, Object spiObject) throws IOException
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 locationlocation
- location of file, passed to FileFactorybuffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.spiObject
- sent to iosp.setSpecial(); may be null
IOException
- on read errorpublic Aggregation getAggregation()
public void setAggregation(Aggregation agg)
agg
- the Aggregation objectpublic List<CoordinateSystem> getCoordinateSystems()
public String getConventionUsed()
public EnumSet<NetcdfDataset.Enhance> getEnhanceMode()
public List<CoordinateTransform> getCoordinateTransforms()
public List<CoordinateAxis> getCoordinateAxes()
public void clearCoordinateSystems()
public CoordinateAxis findCoordinateAxis(AxisType type)
type
- axis type
public CoordinateAxis findCoordinateAxis(String fullName)
fullName
- full escaped name of the coordinate axis
public CoordinateSystem findCoordinateSystem(String name)
name
- String which identifies the desired CoordinateSystem
public CoordinateTransform findCoordinateTransform(String name)
name
- String which identifies the desired CoordinateSystem
public void close() throws IOException
close
in interface FileCacheable
close
in class NetcdfFile
IOException
public boolean sync() throws IOException
sync
in interface FileCacheable
sync
in class NetcdfFile
IOException
public void empty()
NetcdfFile
empty
in class NetcdfFile
public boolean syncExtend() throws IOException
NetcdfFile
syncExtend
in class NetcdfFile
IOException
- if errorpublic void writeNcML(OutputStream os, String uri) throws IOException
writeNcML
in class NetcdfFile
os
- write to this Output Stream.uri
- use this for the uri attribute; if null use getLocation().
IOException
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public void writeNcMLG(OutputStream os, boolean showCoords, String uri) throws IOException
os
- write to this Output Stream.showCoords
- shoe the values of coordinate axesuri
- use this for the uri attribute; if null use getLocation().
IOException
- on write errorprotected Boolean makeRecordStructure()
NetcdfFile
makeRecordStructure
in class NetcdfFile
public void sort()
public NetcdfFile getReferencedFile()
public IOServiceProvider getIosp()
NetcdfFile
getIosp
in class NetcdfFile
public void setReferencedFile(NetcdfFile ncfile)
ncfile
- underlying "referenced file"protected String toStringDebug(Object o)
NetcdfFile
toStringDebug
in class NetcdfFile
o
- must be a Variable, Dimension, Attribute, or Group
public void addCoordinateSystem(CoordinateSystem cs)
cs
- add this CoordinateSystem to the datasetpublic void addCoordinateTransform(CoordinateTransform ct)
ct
- add this CoordinateTransform to the datasetpublic CoordinateAxis addCoordinateAxis(VariableDS v)
v
- make this VariableDS into a CoordinateAxis
public Variable addVariable(Group g, Variable v)
NetcdfFile
addVariable
in class NetcdfFile
g
- add to this group. If group is null, use root groupv
- add this Variable
public CoordSysBuilderIF enhance() throws IOException
IOException
- on errorpublic void enhance(Set<NetcdfDataset.Enhance> mode) throws IOException
mode
- how to enhance
IOException
- on errorpublic boolean enhanceNeeded(Set<NetcdfDataset.Enhance> want) throws IOException
want
- enhancements wanted
IOException
- on errorpublic void setValues(Variable v, int npts, double start, double incr)
v
- for this variablenpts
- number of values, must = v.getSize()start
- starting valueincr
- incrementpublic void setValues(Variable v, List<String> values) throws IllegalArgumentException
v
- for this variablevalues
- list of Strings
IllegalArgumentException
- if values array not correct size, or values wont parse to the correct typepublic static Array makeArray(DataType dtype, List<String> stringValues) throws NumberFormatException
dtype
- data type of the array.stringValues
- list of strings.
NumberFormatException
- if string values not parssable to specified data typepublic void getDetailInfo(Formatter f)
getDetailInfo
in class NetcdfFile
public static void debugDump(PrintStream out, NetcdfDataset ncd)
out
- write herencd
- info about thispublic String getFileTypeId()
NetcdfFile
getFileTypeId
in class NetcdfFile
public String getFileTypeDescription()
NetcdfFile
getFileTypeDescription
in class NetcdfFile
public void check(Formatter f)
public static void main(String[] arg) throws IOException
ucar.nc2.dataset.NetcdfDataset -in fileIn -out fileOut
where:
arg
- -in fileIn -out fileOut [-delay millisecs]
IOException
- on read or write error
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |