|
||||||||||
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 |
---|
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 java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public NetcdfDataset(NetcdfFile ncfile) throws java.io.IOException
ncfile
- NetcdfFile to transform.
java.io.IOException
- on read errorpublic NetcdfDataset(NetcdfFile ncfile, boolean enhance) throws java.io.IOException
ncfile
- NetcdfFile to transform, do not use independently after this.enhance
- if true, enhance with defaultEnhanceMode
java.io.IOException
- on read errorpublic NetcdfDataset(NetcdfFile ncfile, java.util.Set<NetcdfDataset.Enhance> mode) throws java.io.IOException
ncfile
- NetcdfFile to transform, do not use independently after this.mode
- set of enhance modes. If null, then none
java.io.IOException
- on read errorpublic NetcdfDataset()
Method Detail |
---|
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceAll()
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceNone()
public static java.util.Set<NetcdfDataset.Enhance> getEnhanceDefault()
public static void setDefaultEnhanceMode(java.util.Set<NetcdfDataset.Enhance> mode)
mode
- the default set of Enhancements for open and acquire factory methodspublic static java.util.Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()
public static java.util.Set<NetcdfDataset.Enhance> getCoordSysEnhanceMode()
public static java.util.Set<NetcdfDataset.Enhance> parseEnhanceMode(java.lang.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 ucar.nc2.util.cache.FileCache getNetcdfFileCache()
public static NetcdfDataset wrap(NetcdfFile ncfile, java.util.Set<NetcdfDataset.Enhance> enhanceMode) throws java.io.IOException
ncfile
- wrap thisenhanceMode
- using this enhancemode
java.io.IOException
- on io errorpublic static NetcdfDataset openDataset(java.lang.String location) throws java.io.IOException
location
- location of file
java.io.IOException
- on read errorpublic static NetcdfDataset openDataset(java.lang.String location, boolean enhance, CancelTask cancelTask) throws java.io.IOException
location
- location of fileenhance
- if true, process scale/offset/missing and add Coordinate SystemscancelTask
- allow task to be cancelled; may be null.
java.io.IOException
- on read errorpublic static NetcdfDataset openDataset(java.lang.String location, boolean enhance, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject) throws java.io.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
java.io.IOException
- on read errorpublic 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
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
java.io.IOException
- on read errorpublic static NetcdfDataset acquireDataset(java.lang.String location, CancelTask cancelTask) throws java.io.IOException
location
- location of file, passed to FileFactorycancelTask
- allow task to be cancelled; may be null.
java.io.IOException
- on read errorpublic 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
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
java.io.IOException
- on read errorpublic static NetcdfFile openFile(java.lang.String location, CancelTask cancelTask) throws java.io.IOException
location
- location of dataset.cancelTask
- use to allow task to be cancelled; may be null.
java.io.IOException
- on read errorpublic static NetcdfFile openFile(java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object spiObject) throws java.io.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
java.io.IOException
- on read errorpublic static NetcdfFile acquireFile(java.lang.String location, CancelTask cancelTask) throws java.io.IOException
location
- location of file, passed to FileFactorycancelTask
- allow task to be cancelled; may be null.
java.io.IOException
- on read errorpublic 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
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
java.io.IOException
- on read errorpublic static void setHttpClient(org.apache.commons.httpclient.HttpClient client)
client
- the HttpClient objectpublic ucar.nc2.ncml.Aggregation getAggregation()
public void setAggregation(ucar.nc2.ncml.Aggregation agg)
agg
- the Aggregation objectpublic java.util.List<CoordinateSystem> getCoordinateSystems()
public java.lang.String getConventionUsed()
public java.util.EnumSet<NetcdfDataset.Enhance> getEnhanceMode()
public java.util.List<CoordinateTransform> getCoordinateTransforms()
public java.util.List<CoordinateAxis> getCoordinateAxes()
public void clearCoordinateSystems()
public CoordinateAxis findCoordinateAxis(AxisType type)
type
- axis type
public CoordinateAxis findCoordinateAxis(java.lang.String fullName)
fullName
- full name of the coordinate axis
public CoordinateSystem findCoordinateSystem(java.lang.String name)
name
- String which identifies the desired CoordinateSystem
public CoordinateTransform findCoordinateTransform(java.lang.String name)
name
- String which identifies the desired CoordinateSystem
public void close() throws java.io.IOException
close
in interface ucar.nc2.util.cache.FileCacheable
close
in class NetcdfFile
java.io.IOException
public boolean sync() throws java.io.IOException
sync
in interface ucar.nc2.util.cache.FileCacheable
sync
in class NetcdfFile
java.io.IOException
public boolean syncExtend() throws java.io.IOException
NetcdfFile
syncExtend
in class NetcdfFile
java.io.IOException
- if errorpublic void writeNcML(java.io.OutputStream os, java.lang.String uri) throws java.io.IOException
writeNcML
in class NetcdfFile
os
- write to this Output Stream.uri
- use this for the uri attribute; if null use getLocation().
java.io.IOException
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public void writeNcMLG(java.io.OutputStream os, boolean showCoords, java.lang.String uri) throws java.io.IOException
os
- write to this Output Stream.showCoords
- shoe the values of coordinate axesuri
- use this for the uri attribute; if null use getLocation().
java.io.IOException
- on write errorpublic void sort()
public NetcdfFile getReferencedFile()
public ucar.nc2.iosp.IOServiceProvider getIosp()
NetcdfFile
getIosp
in class NetcdfFile
public void setReferencedFile(NetcdfFile ncfile)
ncfile
- underlying "referenced file"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 void enhance() throws java.io.IOException
java.io.IOException
- on errorpublic void enhance(java.util.Set<NetcdfDataset.Enhance> mode) throws java.io.IOException
mode
- how to enhance
java.io.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, java.util.List<java.lang.String> values) throws java.lang.IllegalArgumentException
v
- for this variablevalues
- list of Strings
java.lang.IllegalArgumentException
- if values array not correct size, or values wont parse to the correct typepublic static Array makeArray(DataType dtype, java.util.List<java.lang.String> stringValues) throws java.lang.NumberFormatException
dtype
- data type of the array.stringValues
- list of strings.
java.lang.NumberFormatException
- if string values not parssable to specified data typepublic java.lang.String getDetailInfo()
getDetailInfo
in class NetcdfFile
public static void debugDump(java.io.PrintStream out, NetcdfDataset ncd)
out
- write herencd
- info about thispublic java.lang.String getFileTypeId()
NetcdfFile
getFileTypeId
in class NetcdfFile
public java.lang.String getFileTypeDescription()
NetcdfFile
getFileTypeDescription
in class NetcdfFile
public static void main(java.lang.String[] arg) throws java.io.IOException
ucar.nc2.dataset.NetcdfDataset -in fileIn -out fileOut
where:
arg
- -in fileIn -out fileOut [-delay millisecs]
java.io.IOException
- on read or write error
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |