|
||||||||||
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. However, reading data is not thread-safe.
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 | |
---|---|
protected FileCache |
cache
|
protected String |
cacheName
|
protected static boolean |
debugCompress
|
protected static boolean |
debugSPI
|
protected List<Dimension> |
dimensions
|
protected List<Attribute> |
gattributes
|
protected String |
id
|
static String |
IOSP_MESSAGE_ADD_RECORD_STRUCTURE
|
static String |
IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE
|
static String |
IOSP_MESSAGE_RANDOM_ACCESS_FILE
|
static String |
IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
|
protected String |
location
|
static String |
reserved
|
static String |
reservedCdl
|
static String |
reservedSectionSpec
|
protected Group |
rootGroup
|
protected static boolean |
showRequest
|
protected IOServiceProvider |
spi
|
protected String |
title
|
protected boolean |
unlocked
|
protected List<Variable> |
variables
|
Constructor Summary | |
---|---|
protected |
NetcdfFile()
For subclass construction. |
protected |
NetcdfFile(IOServiceProvider spi,
RandomAccessFile raf,
String location,
CancelTask cancelTask)
Open an existing netcdf file (read only). |
protected |
NetcdfFile(NetcdfFile ncfile)
Copy constructor, used by NetcdfDataset. |
|
NetcdfFile(String filename)
Deprecated. use NetcdfFile.open( location) or NetcdfDataset.openFile( location) |
protected |
NetcdfFile(String iospClassName,
String iospParam,
String location,
int buffer_size,
CancelTask cancelTask)
Open an existing netcdf file (read only), using the specified iosp. |
|
NetcdfFile(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,
String shortName,
String dims,
int strlen)
Create a new Variable of type Datatype.CHAR, and add to the given group. |
Variable |
addVariable(Group g,
String shortName,
DataType dtype,
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(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 String |
escapeName(String vname)
Escape standard special characters in a netcdf object name. |
static String |
escapeNameCDL(String vname)
Escape special characters in a netcdf object name for CDL. |
static String |
escapeNameSectionSpec(String vname)
Escape special characters in a netcdf object name for SectionSpec. |
String |
findAttValueIgnoreCase(Variable v,
String attName,
String defaultValue)
Find a String-valued global or variable Attribute by Attribute name (ignore case), return the Value of the Attribute. |
Dimension |
findDimension(String name)
Retrieve a dimension by fullName. |
Attribute |
findGlobalAttribute(String name)
Look up global Attribute by (full) name. |
Attribute |
findGlobalAttributeIgnoreCase(String name)
Look up global Attribute by name, ignore case. |
Group |
findGroup(String fullName)
Find a Group, with the specified (full) name. |
Variable |
findVariable(String fullNameEscaped)
Find a Variable, with the specified (escaped full) name. |
void |
finish()
Finish constructing the object model. |
String |
getCacheName()
Public by accident. |
String |
getDetailInfo()
Access to iosp debugging info. |
void |
getDetailInfo(Formatter f)
|
List<Dimension> |
getDimensions()
Get the shared Dimensions used in this file. |
String |
getFileTypeDescription()
Get a human-readable description for this file type. |
String |
getFileTypeId()
Get the file type id for the underlying data source. |
String |
getFileTypeVersion()
Get the version of this file type. |
List<Attribute> |
getGlobalAttributes()
Returns the set of global attributes associated with this file. |
String |
getId()
Get the globally unique dataset identifier, if it exists. |
IOServiceProvider |
getIosp()
DO NOT USE - public by accident |
String |
getLocation()
Get the NetcdfFile location. |
Group |
getRootGroup()
Get the root group. |
protected StructureDataIterator |
getStructureIterator(Structure s,
int bufferSize)
|
String |
getTitle()
Get the human-readable title, if it exists. |
Dimension |
getUnlimitedDimension()
Return the unlimited (record) dimension, or null if not exist. |
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(String[] arg)
debugging - do not use |
protected static String |
makeFullName(Variable v)
|
protected static String |
makeFullName(Variable v,
String reserved)
|
protected static String |
makeFullNameEscaped(Variable v)
|
protected static String |
makeFullNameEscapedSectionSpec(Variable v)
|
protected String |
makeFullNameWithString(Group parent,
String name)
|
protected Boolean |
makeRecordStructure()
If there is an unlimited dimension, make all variables that use it into a Structure. |
protected Group |
makeRootGroup()
|
static String |
makeValidCdmObjectName(String name)
Create a valid CDM object name. |
static NetcdfFile |
open(String location)
Open an existing netcdf file (read only). |
static NetcdfFile |
open(String location,
CancelTask cancelTask)
Open an existing file (read only), with option of cancelling. |
static NetcdfFile |
open(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(String location,
int buffer_size,
CancelTask cancelTask,
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(String location,
String iospClassName,
int bufferSize,
CancelTask cancelTask,
Object iospMessage)
Open an existing file (read only), specifying which IOSP is to be used. |
static NetcdfFile |
openInMemory(String filename)
Read a local CDM file into memory. |
static NetcdfFile |
openInMemory(String name,
byte[] data)
Open an in-memory netcdf file. |
static NetcdfFile |
openInMemory(String name,
byte[] data,
String iospClassName)
Open an in-memory netcdf file, with a specific iosp. |
static NetcdfFile |
openInMemory(URI uri)
Read a remote CDM file into memory. |
Array |
read(String variableSection,
boolean flatten)
Deprecated. use readSection(), flatten=false no longer supported |
List<Array> |
readArrays(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,
String attName,
double defValue)
|
int |
readAttributeInteger(Variable v,
String attName,
int defValue)
|
protected Array |
readData(Variable v,
Section ranges)
|
Array |
readSection(String variableSection)
Read a variable using the given section specification. |
protected long |
readToByteChannel(Variable v,
Section section,
WritableByteChannel wbc)
Read data from a top level Variable and send data to a WritableByteChannel. |
static void |
registerIOProvider(Class iospClass)
Register an IOServiceProvider. |
static void |
registerIOProvider(String className)
Register an IOServiceProvider, using its class string name. |
boolean |
removeDimension(Group g,
String dimName)
Remove a shared Dimension from a Group by name. |
protected Boolean |
removeRecordStructure()
|
boolean |
removeVariable(Group g,
String varName)
Remove a Variable from the given group by name. |
Object |
sendIospMessage(Object message)
Generic way to send a "message" to the underlying IOSP. |
protected void |
setCacheName(String cacheName)
Public by accident. |
static void |
setDebugFlags(DebugFlags debugFlag)
debugging |
void |
setFileCache(FileCache cache)
Public by accident. |
void |
setId(String id)
Set the globally unique dataset identifier. |
NetcdfFile |
setImmutable()
Make this immutable. |
void |
setLocation(String location)
Set the location, a URL or local filename. |
static void |
setProperty(String name,
String value)
Set properties. |
void |
setTitle(String title)
Set the dataset "human readable" title. |
protected void |
showCached(Formatter f)
|
protected void |
showProxies(Formatter f)
|
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. |
String |
toString()
CDL representation of Netcdf header info. |
protected String |
toStringDebug(Object o)
Access to iosp debugging info. |
protected void |
toStringEnd(PrintWriter pw)
|
protected void |
toStringStart(PrintWriter pw,
boolean strict)
|
static String |
unescapeName(String vname)
Unescape any escaped characters in a name. |
void |
writeCDL(OutputStream out,
boolean strict)
Write CDL representation to OutputStream. |
void |
writeCDL(PrintWriter pw,
boolean strict)
Write CDL representation to PrintWriter. |
void |
writeNcML(OutputStream os,
String uri)
Write the NcML representation: dont show coodinate values |
void |
writeNcML(Writer writer,
String uri)
Write the NcML representation: dont show coodinate values |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final String IOSP_MESSAGE_ADD_RECORD_STRUCTURE
public static final String IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE
public static final String IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
public static final String IOSP_MESSAGE_RANDOM_ACCESS_FILE
protected static boolean debugSPI
protected static boolean debugCompress
protected static boolean showRequest
public static final String reserved
public static final String reservedSectionSpec
public static final String reservedCdl
protected String location
protected String id
protected String title
protected String cacheName
protected Group rootGroup
protected boolean unlocked
protected FileCache cache
protected IOServiceProvider spi
protected List<Variable> variables
protected List<Dimension> dimensions
protected List<Attribute> gattributes
Constructor Detail |
---|
public NetcdfFile(String filename) throws IOException
filename
- location
IOException
- if errorpublic NetcdfFile(URL url) throws IOException
url
- HTTP URL location
IOException
- if errorprotected NetcdfFile(String iospClassName, String iospParam, String location, int buffer_size, CancelTask cancelTask) throws IOException, IllegalAccessException, InstantiationException, ClassNotFoundException
iospClassName
- the name of the class implementing IOServiceProvideriospParam
- parameter to pass to the IOSP (before open is called)location
- location of file. This is a URL string, or a local pathname.buffer_size
- use this buffer size on the RandomAccessFilecancelTask
- allow user to cancel
ClassNotFoundException
- if the iospClassName cannot be found
IllegalAccessException
- if the class or its nullary constructor is not accessible.
InstantiationException
- if the class cannot be instatiated, eg if it has no nullary constructor
IOException
- if I/O errorprotected NetcdfFile(IOServiceProvider spi, RandomAccessFile raf, String location, CancelTask cancelTask) throws IOException
location
- location of file. This is a URL string, or a local pathname.spi
- use this IOServiceProvider instanceraf
- read from this RandomAccessFilecancelTask
- allow user to cancel
IOException
- if I/O errorprotected NetcdfFile()
protected NetcdfFile(NetcdfFile ncfile)
ncfile
- copy from hereMethod Detail |
---|
public static String makeValidCdmObjectName(String name)
name
- from this name
public static String escapeName(String vname)
vname
- the name
public static String escapeNameCDL(String vname)
vname
- the name
public static String escapeNameSectionSpec(String vname)
vname
- the name
public static String unescapeName(String vname)
vname
- the escaped name
protected static String makeFullName(Variable v)
protected static String makeFullNameEscaped(Variable v)
protected static String makeFullNameEscapedSectionSpec(Variable v)
protected static String makeFullName(Variable v, String reserved)
public static void registerIOProvider(String className) throws IllegalAccessException, InstantiationException, ClassNotFoundException
className
- Class that implements IOServiceProvider.
IllegalAccessException
- if class is not accessible.
InstantiationException
- if class doesnt have a no-arg constructor.
ClassNotFoundException
- if class not found.public static void registerIOProvider(Class iospClass) throws IllegalAccessException, InstantiationException
iospClass
- Class that implements IOServiceProvider.
IllegalAccessException
- if class is not accessible.
InstantiationException
- if class doesnt have a no-arg constructor.
ClassCastException
- if class doesnt implement IOServiceProvider interface.public static void setDebugFlags(DebugFlags debugFlag)
debugFlag
- debug flagspublic static void setProperty(String name, String value)
name
- name of propertyvalue
- value of propertypublic static NetcdfFile open(String location) throws IOException
location
- location of file.
IOException
- if errorpublic static NetcdfFile open(String location, CancelTask cancelTask) throws IOException
location
- location of the file.cancelTask
- allow task to be cancelled; may be null.
IOException
- if errorpublic static NetcdfFile open(String location, int buffer_size, CancelTask cancelTask) throws IOException
location
- location of file.buffer_size
- RandomAccessFile buffer size, if <= 0, use default sizecancelTask
- allow task to be cancelled; may be null.
IOException
- if errorpublic static NetcdfFile open(String location, int buffer_size, CancelTask cancelTask, Object iospMessage) throws 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
IOException
- if errorpublic static boolean canOpen(String location) throws IOException
location
- same as open
IOException
- on read errorpublic static NetcdfFile open(String location, String iospClassName, int bufferSize, CancelTask cancelTask, Object iospMessage) throws ClassNotFoundException, IllegalAccessException, InstantiationException, 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
IOException
- if read error
ClassNotFoundException
- cannat find iospClassName in thye class path
InstantiationException
- if class cannot be instantiated
IllegalAccessException
- if class is not accessiblepublic static NetcdfFile openInMemory(String name, byte[] data, String iospClassName) throws IOException, ClassNotFoundException, IllegalAccessException, InstantiationException
name
- name of the dataset. Typically use the filename or URI.data
- in-memory netcdf fileiospClassName
- fully qualified class name of the IOSP class to handle this file
IOException
- if read error
ClassNotFoundException
- cannat find iospClassName in the class path
InstantiationException
- if class cannot be instantiated
IllegalAccessException
- if class is not accessiblepublic static NetcdfFile openInMemory(String name, byte[] data) throws IOException
name
- name of the dataset. Typically use the filename or URI.data
- in-memory netcdf file
IOException
- if errorpublic static NetcdfFile openInMemory(String filename) throws IOException
filename
- location of CDM file, must be a local file.
IOException
- if error reading filepublic static NetcdfFile openInMemory(URI uri) throws IOException
uri
- location of CDM file, must be accessible through uri.toURL().openStream().
IOException
- if error reading filepublic boolean isUnlocked()
public void close() throws IOException
close
in interface FileCacheable
IOException
- if error when closingpublic void setFileCache(FileCache cache)
setFileCache
in interface FileCacheable
cache
- must store this, use it on close as above.public String getCacheName()
protected void setCacheName(String cacheName)
cacheName
- name in the cache, should be unique for this NetcdfFile. Usually the location.public String getLocation()
getLocation
in interface FileCacheable
public String getId()
public String getTitle()
public Group getRootGroup()
public List<Variable> getVariables()
public Group findGroup(String fullName)
fullName
- eg "/group/subgroup/wantGroup". Null or empty string returns the root group.
public Variable findVariable(String fullNameEscaped)
fullNameEscaped
- eg "/group/subgroup/name1.name2.name".
escapeName(java.lang.String)
,
unescapeName(java.lang.String)
public 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(String name)
name
- dimension full name, (using parent group names if not in the root group)
public boolean hasUnlimitedDimension()
public Dimension getUnlimitedDimension()
public List<Attribute> getGlobalAttributes()
public Attribute findGlobalAttribute(String name)
name
- the name of the attribute
public Attribute findGlobalAttributeIgnoreCase(String name)
name
- the name of the attribute
public String findAttValueIgnoreCase(Variable v, String attName, 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, String attName, double defValue)
public int readAttributeInteger(Variable v, String attName, int defValue)
public void writeCDL(OutputStream out, boolean strict)
out
- write to this OutputStreamstrict
- if true, make it stricly CDL, otherwise, add a little extra infopublic void writeCDL(PrintWriter pw, boolean strict)
pw
- write to this PrintWriterstrict
- if true, make it stricly CDL, otherwise, add a little extra infopublic String toString()
toString
in class Object
protected void toStringStart(PrintWriter pw, boolean strict)
protected void toStringEnd(PrintWriter pw)
public void writeNcML(OutputStream os, String uri) throws IOException
os
- : write to this Output Stream.uri
- use this for the uri attribute; if null use getLocation(). // ??
IOException
- if errorNCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public void writeNcML(Writer writer, String uri) throws IOException
writer
- : write to this Writer, should have encoding of UTF-8 if applicableuri
- use this for the uri attribute; if null use getLocation().
IOException
- if errorNCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)
public boolean syncExtend() throws IOException
IOException
- if errorpublic boolean sync() throws IOException
sync
in interface FileCacheable
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, 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, String shortName, DataType dtype, 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, String shortName, 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, 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 Object sendIospMessage(Object message)
message
- iosp specific message
Special:protected Boolean makeRecordStructure()
protected Boolean removeRecordStructure()
public void setId(String id)
id
- the idpublic void setTitle(String title)
title
- the titlepublic void setLocation(String location)
location
- the locationpublic NetcdfFile setImmutable()
public void empty()
protected Group makeRootGroup()
public void finish()
protected String makeFullNameWithString(Group parent, String name)
protected Array readData(Variable v, Section ranges) throws IOException, InvalidRangeException
IOException
InvalidRangeException
public Array readSection(String variableSection) throws IOException, InvalidRangeException
variableSection
- the constraint expression.
IOException
- if error
InvalidRangeException
- if variableSection is invalidprotected long readToByteChannel(Variable v, Section section, WritableByteChannel wbc) throws IOException, InvalidRangeException
v
- a top-level Variablesection
- the section of data to read.
There must be a Range for each Dimension in the variable, in order.
Note: no nulls allowed. IOSP may not modify.wbc
- write data to this WritableByteChannel
IOException
- if read error
InvalidRangeException
- if invalid sectionprotected StructureDataIterator getStructureIterator(Structure s, int bufferSize) throws IOException
IOException
public List<Array> readArrays(List<Variable> variables) throws IOException
variables
- List of type Variable
IOException
- if read errorpublic Array read(String variableSection, boolean flatten) throws IOException, InvalidRangeException
variableSection
- the constraint expression.flatten
- MUST BE TRUE
IOException
- if error
InvalidRangeException
- if variableSection is invalidprotected String toStringDebug(Object o)
o
- must be a Variable, Dimension, Attribute, or Group
public String getDetailInfo()
public void getDetailInfo(Formatter f)
protected void showCached(Formatter f)
protected void showProxies(Formatter f)
public IOServiceProvider getIosp()
public String getFileTypeId()
public String getFileTypeDescription()
public String getFileTypeVersion()
public static void main(String[] arg) throws Exception
Exception
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |