|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectucar.nc2.NetcdfFile
public class NetcdfFile
Read-only scientific datasets that are accessible through the netCDF API. Immutable after setImmutable() is called.
Be sure to close the file when done, best practice is to enclose in a try/finally block:
NetcdfFile ncfile = null; try { ncfile = NetcdfFile.open(fileName); ... } finally { ncfile.close(); }
Field Summary | |
---|---|
static java.lang.String |
IOSP_MESSAGE_ADD_RECORD_STRUCTURE
|
static java.lang.String |
IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
|
static java.lang.String |
reserved
The set of characters in a netcdf object name that must be escaped. |
Constructor Summary | |
---|---|
NetcdfFile(java.lang.String filename)
Deprecated. use NetcdfFile.open( location) or NetcdfDataset.openFile( location) |
|
NetcdfFile(java.net.URL url)
Deprecated. use NetcdfFile.open( http:location) or NetcdfDataset.openFile( http:location) |
Method Summary | |
---|---|
Attribute |
addAttribute(Group parent,
Attribute att)
Add an attribute to a group. |
Dimension |
addDimension(Group parent,
Dimension d)
Add a shared Dimension to a Group. |
Group |
addGroup(Group parent,
Group g)
Add a group to the parent group. |
Variable |
addStringVariable(Group g,
java.lang.String shortName,
java.lang.String dims,
int strlen)
Create a new Variable of type Datatype.CHAR, and add to the given group. |
Variable |
addVariable(Group g,
java.lang.String shortName,
DataType dtype,
java.lang.String dims)
Create a new Variable, and add to the given group. |
Variable |
addVariable(Group g,
Variable v)
Add a Variable to the given group. |
Attribute |
addVariableAttribute(Variable v,
Attribute att)
Add a variable attribute. |
static boolean |
canOpen(java.lang.String location)
Find out if the file can be opened, but dont actually open it. |
void |
close()
Close all resources (files, sockets, etc) associated with this file. |
void |
empty()
Completely empty the objects in the netcdf file. |
static java.lang.String |
escapeName(java.lang.String vname)
Escape any special characters in a netcdf object name. |
java.lang.String |
findAttValueIgnoreCase(Variable v,
java.lang.String attName,
java.lang.String defaultValue)
Find a String-valued global or variable Attribute by Attribute name (ignore case), return the Value of the Attribute. |
Dimension |
findDimension(java.lang.String name)
Retrieve a dimension by fullName. |
Attribute |
findGlobalAttribute(java.lang.String name)
Look up global Attribute by (full) name. |
Attribute |
findGlobalAttributeIgnoreCase(java.lang.String name)
Look up global Attribute by name, ignore case. |
Group |
findGroup(java.lang.String fullNameEscaped)
Find a Group, with the specified (full) name. |
Variable |
findTopVariable(java.lang.String name)
Retrieve the Variable with the specified (full) name, which is not a member of a Structure. |
Variable |
findVariable(java.lang.String fullNameEscaped)
Find a Variable, with the specified (full) name. |
void |
finish()
Finish constructing the object model. |
java.lang.String |
getCacheName()
Public by accident. |
java.lang.String |
getDetailInfo()
Access to iosp debugging info. |
java.util.List<Dimension> |
getDimensions()
Get the shared Dimensions used in this file. |
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. |
java.lang.String |
getFileTypeVersion()
Get the version of this file type. |
java.util.List<Attribute> |
getGlobalAttributes()
Returns the set of global attributes associated with this file. |
java.lang.String |
getId()
Get the globally unique dataset identifier, if it exists. |
ucar.nc2.iosp.IOServiceProvider |
getIosp()
DO NOT USE - public by accident |
java.lang.String |
getLocation()
Get the NetcdfFile location. |
Group |
getRootGroup()
Get the root group. |
java.lang.String |
getTitle()
Get the human-readable title, if it exists. |
Dimension |
getUnlimitedDimension()
Return the unlimited (record) dimension, or null if not exist. |
java.util.List<Variable> |
getVariables()
Get all of the variables in the file, in all groups. |
boolean |
hasUnlimitedDimension()
Return true if this file has one or more unlimited (record) dimension. |
boolean |
isUnlocked()
|
static void |
main(java.lang.String[] arg)
debugging - do not use |
static NetcdfFile |
open(java.lang.String location)
Open an existing netcdf file (read only). |
static NetcdfFile |
open(java.lang.String location,
CancelTask cancelTask)
Open an existing file (read only), with option of cancelling. |
static NetcdfFile |
open(java.lang.String location,
int buffer_size,
CancelTask cancelTask)
Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency. |
static NetcdfFile |
open(java.lang.String location,
int buffer_size,
CancelTask cancelTask,
java.lang.Object iospMessage)
Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency, with an optional special object for the iosp. |
static NetcdfFile |
open(java.lang.String location,
java.lang.String iospClassName,
int bufferSize,
CancelTask cancelTask,
java.lang.Object iospMessage)
Open an existing file (read only), specifying which IOSP is to be used. |
static NetcdfFile |
openInMemory(java.lang.String filename)
Read a local CDM file into memory. |
static NetcdfFile |
openInMemory(java.lang.String name,
byte[] data)
Open an in-memory netcdf file. |
static NetcdfFile |
openInMemory(java.net.URI uri)
Read a remote CDM file into memory. |
Array |
read(java.lang.String variableSection,
boolean flatten)
Deprecated. use readSection(), flatten=false no longer supported |
java.util.List<Array> |
readArrays(java.util.List<Variable> variables)
Do a bulk read on a list of Variables and return a corresponding list of Array that contains the results of a full read on each Variable. |
double |
readAttributeDouble(Variable v,
java.lang.String attName,
double defValue)
|
int |
readAttributeInteger(Variable v,
java.lang.String attName,
int defValue)
|
Array |
readSection(java.lang.String variableSection)
Read a variable using the given section specification. |
static void |
registerIOProvider(java.lang.Class iospClass)
Register an IOServiceProvider. |
static void |
registerIOProvider(java.lang.String className)
Register an IOServiceProvider, using its class string name. |
boolean |
removeDimension(Group g,
java.lang.String dimName)
Remove a shared Dimension from a Group by name. |
boolean |
removeVariable(Group g,
java.lang.String varName)
Remove a Variable from the given group by name. |
java.lang.Object |
sendIospMessage(java.lang.Object message)
Generic way to send a "message" to the underlying IOSP. |
static void |
setDebugFlags(DebugFlags debugFlag)
debugging |
void |
setFileCache(ucar.nc2.util.cache.FileCache cache)
Public by accident. |
void |
setId(java.lang.String id)
Set the globally unique dataset identifier. |
NetcdfFile |
setImmutable()
Make this immutable. |
void |
setLocation(java.lang.String location)
Set the location, a URL or local filename. |
static void |
setProperty(java.lang.String name,
java.lang.String value)
Set properties. |
void |
setTitle(java.lang.String title)
Set the dataset "human readable" title. |
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. |
java.lang.String |
toString()
CDL representation of Netcdf header info. |
static java.lang.String |
unescapeName(java.lang.String vname)
Unescape any escaped characters in a name. |
void |
writeCDL(java.io.OutputStream out,
boolean strict)
Write CDL representation to OutputStream. |
void |
writeCDL(java.io.PrintWriter pw,
boolean strict)
Write CDL representation to PrintWriter. |
void |
writeNcML(java.io.OutputStream os,
java.lang.String uri)
Write the NcML representation: dont show coodinate values |
void |
writeNcML(java.io.Writer writer,
java.lang.String uri)
Write the NcML representation: dont show coodinate values |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String IOSP_MESSAGE_ADD_RECORD_STRUCTURE
public static final java.lang.String IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
public static final java.lang.String reserved
Constructor Detail |
---|
public NetcdfFile(java.lang.String filename) throws java.io.IOException
filename
- location
java.io.IOException
- if errorpublic NetcdfFile(java.net.URL url) throws java.io.IOException
url
- HTTP URL location
java.io.IOException
- if errorMethod Detail |
---|
public static java.lang.String escapeName(java.lang.String vname)
vname
- the name
public static java.lang.String unescapeName(java.lang.String vname)
vname
- the escaped name
public static void registerIOProvider(java.lang.String className) throws java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.ClassNotFoundException
className
- Class that implements IOServiceProvider.
java.lang.IllegalAccessException
- if class is not accessible.
java.lang.InstantiationException
- if class doesnt have a no-arg constructor.
java.lang.ClassNotFoundException
- if class not found.public static void registerIOProvider(java.lang.Class iospClass) throws java.lang.IllegalAccessException, java.lang.InstantiationException
iospClass
- Class that implements IOServiceProvider.
java.lang.IllegalAccessException
- if class is not accessible.
java.lang.InstantiationException
- if class doesnt have a no-arg constructor.
java.lang.ClassCastException
- if class doesnt implement IOServiceProvider interface.public static void setDebugFlags(DebugFlags debugFlag)
debugFlag
- debug flagspublic static void setProperty(java.lang.String name, java.lang.String value)
name
- name of propertyvalue
- value of propertypublic static NetcdfFile open(java.lang.String location) throws java.io.IOException
location
- location of file.
java.io.IOException
- if errorpublic static NetcdfFile open(java.lang.String location, CancelTask cancelTask) throws java.io.IOException
location
- location of the file.cancelTask
- allow task to be cancelled; may be null.
java.io.IOException
- if errorpublic static NetcdfFile open(java.lang.String location, int buffer_size, CancelTask cancelTask) throws java.io.IOException
location
- location of file.buffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.
java.io.IOException
- if errorpublic static NetcdfFile open(java.lang.String location, int buffer_size, CancelTask cancelTask, java.lang.Object iospMessage) throws java.io.IOException
location
- location of file. This may be a
buffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.iospMessage
- special iosp tweaking (sent before open is called), may be null
java.io.IOException
- if errorpublic static boolean canOpen(java.lang.String location) throws java.io.IOException
location
- same as open
java.io.IOException
- on read errorpublic static NetcdfFile open(java.lang.String location, java.lang.String iospClassName, int bufferSize, CancelTask cancelTask, java.lang.Object iospMessage) throws java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.io.IOException
location
- location of fileiospClassName
- fully qualified class name of the IOSP class to handle this filebufferSize
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.iospMessage
- special iosp tweaking (sent before open is called), may be null
java.io.IOException
- if read error
java.lang.ClassNotFoundException
- cannat find iospClassName in thye class path
java.lang.InstantiationException
- if class cannot be instantiated
java.lang.IllegalAccessException
- if class is not accessiblepublic static NetcdfFile openInMemory(java.lang.String name, byte[] data) throws java.io.IOException
name
- name of the dataset. Typically use the filename or URI.data
- in-memory netcdf file
java.io.IOException
- if errorpublic static NetcdfFile openInMemory(java.lang.String filename) throws java.io.IOException
filename
- location of CDM file, must be a local file.
java.io.IOException
- if error reading filepublic static NetcdfFile openInMemory(java.net.URI uri) throws java.io.IOException
uri
- location of CDM file, must be accessible through uri.toURL().openStream().
java.io.IOException
- if error reading filepublic boolean isUnlocked()
public void close() throws java.io.IOException
close
in interface ucar.nc2.util.cache.FileCacheable
java.io.IOException
- if error when closingpublic void setFileCache(ucar.nc2.util.cache.FileCache cache)
setFileCache
in interface ucar.nc2.util.cache.FileCacheable
cache
- must store this, use it on close as above.public java.lang.String getCacheName()
public java.lang.String getLocation()
getLocation
in interface ucar.nc2.util.cache.FileCacheable
public java.lang.String getId()
public java.lang.String getTitle()
public Group getRootGroup()
public java.util.List<Variable> getVariables()
public Variable findTopVariable(java.lang.String name)
name
- full name, starting from root group.
public Group findGroup(java.lang.String fullNameEscaped)
fullNameEscaped
- eg "/group/subgroup/wantGroup". Null or empty string returns the root group.
Any chars may be escaped
escapeName(java.lang.String)
,
unescapeName(java.lang.String)
public Variable findVariable(java.lang.String fullNameEscaped)
fullNameEscaped
- eg "/group/subgroup/name1.name2.name". Any chars may be escaped
escapeName(java.lang.String)
,
unescapeName(java.lang.String)
public java.util.List<Dimension> getDimensions()
If the dimensions are in a group, the dimension name will have the group name, in order to disambiguate the dimensions. This means that a Variable's dimensions will not match Dimensions in this list. Therefore it is better to get the shared Dimensions directly from the Groups.
public Dimension findDimension(java.lang.String name)
name
- dimension full name, (using parent group names if not in the root group)
public boolean hasUnlimitedDimension()
public Dimension getUnlimitedDimension()
public java.util.List<Attribute> getGlobalAttributes()
public Attribute findGlobalAttribute(java.lang.String name)
name
- the name of the attribute
public Attribute findGlobalAttributeIgnoreCase(java.lang.String name)
name
- the name of the attribute
public java.lang.String findAttValueIgnoreCase(Variable v, java.lang.String attName, java.lang.String defaultValue)
v
- the variable or null for global attributeattName
- the (full) name of the attribute, case insensitivedefaultValue
- return this if attribute not found
public double readAttributeDouble(Variable v, java.lang.String attName, double defValue)
public int readAttributeInteger(Variable v, java.lang.String attName, int defValue)
public void writeCDL(java.io.OutputStream out, boolean strict)
out
- write to this OutputStreamstrict
- if true, make it stricly CDL, otherwise, add a little extra infopublic void writeCDL(java.io.PrintWriter pw, boolean strict)
pw
- write to this PrintWriterstrict
- if true, make it stricly CDL, otherwise, add a little extra infopublic java.lang.String toString()
toString
in class java.lang.Object
public void writeNcML(java.io.OutputStream os, java.lang.String uri) throws java.io.IOException
os
- : write to this Output Stream.uri
- use this for the uri attribute; if null use getLocation(). // ??
java.io.IOException
- if errorNCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public void writeNcML(java.io.Writer writer, java.lang.String uri) throws java.io.IOException
writer
- : write to this Writer, should have encoding of UTF-8 if applicableuri
- use this for the uri attribute; if null use getLocation().
java.io.IOException
- if errorNCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public boolean syncExtend() throws java.io.IOException
java.io.IOException
- if errorpublic boolean sync() throws java.io.IOException
sync
in interface ucar.nc2.util.cache.FileCacheable
java.io.IOException
- if errorpublic Attribute addAttribute(Group parent, Attribute att)
parent
- add to this group. If group is null, use root groupatt
- add this attribute
public Group addGroup(Group parent, Group g)
parent
- add to this group. If group is null, use root groupg
- add this group
public Dimension addDimension(Group parent, Dimension d)
parent
- add to this group. If group is null, use root groupd
- add this Dimension
public boolean removeDimension(Group g, java.lang.String dimName)
g
- remove from this group. If group is null, use root groupdimName
- name of Dimension to remove.
public Variable addVariable(Group g, Variable v)
g
- add to this group. If group is null, use root groupv
- add this Variable
public Variable addVariable(Group g, java.lang.String shortName, DataType dtype, java.lang.String dims)
g
- add to this group. If group is null, use root groupshortName
- short name of the Variabledtype
- data type of the Variabledims
- list of dimension names
public Variable addStringVariable(Group g, java.lang.String shortName, java.lang.String dims, int strlen)
g
- add to this group. If group is null, use root groupshortName
- short name of the Variabledims
- list of dimension namesstrlen
- dimension length of the inner (fastest changing) dimension
public boolean removeVariable(Group g, java.lang.String varName)
g
- remove from this group. If group is null, use root groupvarName
- name of variable to remove.
public Attribute addVariableAttribute(Variable v, Attribute att)
v
- add to this Variable.att
- add this attribute
public java.lang.Object sendIospMessage(java.lang.Object message)
message
- iosp specific message
Special:public void setId(java.lang.String id)
id
- the idpublic void setTitle(java.lang.String title)
title
- the titlepublic void setLocation(java.lang.String location)
location
- the locationpublic NetcdfFile setImmutable()
public void empty()
public void finish()
public java.util.List<Array> readArrays(java.util.List<Variable> variables) throws java.io.IOException
variables
- List of type Variable
java.io.IOException
- if read errorpublic Array read(java.lang.String variableSection, boolean flatten) throws java.io.IOException, InvalidRangeException
variableSection
- the constraint expression.flatten
- MUST BE TRUE
java.io.IOException
- if error
InvalidRangeException
- if variableSection is invalidpublic Array readSection(java.lang.String variableSection) throws java.io.IOException, InvalidRangeException
variableSection
- the constraint expression.
java.io.IOException
- if error
InvalidRangeException
- if variableSection is invalidpublic java.lang.String getDetailInfo()
public ucar.nc2.iosp.IOServiceProvider getIosp()
public java.lang.String getFileTypeId()
public java.lang.String getFileTypeDescription()
public java.lang.String getFileTypeVersion()
public static void main(java.lang.String[] arg) throws java.lang.Exception
java.lang.Exception
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |