ucar.nc2
Class NetcdfFile

java.lang.Object
  extended by ucar.nc2.NetcdfFile
All Implemented Interfaces:
FileCacheable
Direct Known Subclasses:
AreaServiceProvider.MakeNetcdfFile, CdmRemote, DODSNetcdfFile, GempakGridServiceProvider.MakeNetcdfFile, GempakSoundingIOSP.MakeNetcdfFile, GempakSurfaceIOSP.MakeNetcdfFile, NetcdfDataset, NetcdfFileWriteable, Vis5DIosp.MakeNetcdfFile

public class NetcdfFile
extends Object
implements FileCacheable

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();
 }
 

Naming

Each object has a name (aka "full name") that is unique within the entire netcdf file, and a "short name" that is unique within the parent group. These coincide for objects in the root group, and so are backwards compatible with version 3 files.
  1. Variable: group1/group2/varname
  2. Structure member Variable: group1/group2/varname.s1.s2
  3. Group Attribute: group1/group2@attName
  4. Variable Attribute: group1/group2/varName@attName

Author:
caron

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

IOSP_MESSAGE_ADD_RECORD_STRUCTURE

public static final String IOSP_MESSAGE_ADD_RECORD_STRUCTURE
See Also:
Constant Field Values

IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE

public static final String IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE
See Also:
Constant Field Values

IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

public static final String IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
See Also:
Constant Field Values

IOSP_MESSAGE_RANDOM_ACCESS_FILE

public static final String IOSP_MESSAGE_RANDOM_ACCESS_FILE
See Also:
Constant Field Values

debugSPI

protected static boolean debugSPI

debugCompress

protected static boolean debugCompress

showRequest

protected static boolean showRequest

reserved

public static final String reserved
See Also:
Constant Field Values

reservedSectionSpec

public static final String reservedSectionSpec
See Also:
Constant Field Values

reservedCdl

public static final String reservedCdl
See Also:
Constant Field Values

location

protected String location

id

protected String id

title

protected String title

cacheName

protected String cacheName

rootGroup

protected Group rootGroup

unlocked

protected boolean unlocked

cache

protected FileCache cache

spi

protected IOServiceProvider spi

variables

protected List<Variable> variables

dimensions

protected List<Dimension> dimensions

gattributes

protected List<Attribute> gattributes
Constructor Detail

NetcdfFile

public NetcdfFile(String filename)
           throws IOException
Deprecated. use NetcdfFile.open( location) or NetcdfDataset.openFile( location)

This is can only be used for local netcdf-3 files.

Parameters:
filename - location
Throws:
IOException - if error

NetcdfFile

public NetcdfFile(URL url)
           throws IOException
Deprecated. use NetcdfFile.open( http:location) or NetcdfDataset.openFile( http:location)

This can only be used for netcdf-3 files served over HTTP

Parameters:
url - HTTP URL location
Throws:
IOException - if error

NetcdfFile

protected NetcdfFile(String iospClassName,
                     String iospParam,
                     String location,
                     int buffer_size,
                     CancelTask cancelTask)
              throws IOException,
                     IllegalAccessException,
                     InstantiationException,
                     ClassNotFoundException
Open an existing netcdf file (read only), using the specified iosp. The ClassLoader for the NetcdfFile class is used.

Parameters:
iospClassName - the name of the class implementing IOServiceProvider
iospParam - 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 RandomAccessFile
cancelTask - allow user to cancel
Throws:
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 error

NetcdfFile

protected NetcdfFile(IOServiceProvider spi,
                     RandomAccessFile raf,
                     String location,
                     CancelTask cancelTask)
              throws IOException
Open an existing netcdf file (read only).

Parameters:
location - location of file. This is a URL string, or a local pathname.
spi - use this IOServiceProvider instance
raf - read from this RandomAccessFile
cancelTask - allow user to cancel
Throws:
IOException - if I/O error

NetcdfFile

protected NetcdfFile()
For subclass construction. Call finish() when completed construction.


NetcdfFile

protected NetcdfFile(NetcdfFile ncfile)
Copy constructor, used by NetcdfDataset. Shares the iosp.

Parameters:
ncfile - copy from here
Method Detail

makeValidCdmObjectName

public static String makeValidCdmObjectName(String name)
Create a valid CDM object name. Control chars (< 0x20) are not allowed. Trailing and leading blanks are not allowed and are stripped off. A forward slash "/" is converted into an underscore "_".

Parameters:
name - from this name
Returns:
valid CDM object name

escapeName

public static String escapeName(String vname)
Escape standard special characters in a netcdf object name.

Parameters:
vname - the name
Returns:
escaped version of it

escapeNameCDL

public static String escapeNameCDL(String vname)
Escape special characters in a netcdf object name for CDL.

Parameters:
vname - the name
Returns:
escaped version of it

escapeNameSectionSpec

public static String escapeNameSectionSpec(String vname)
Escape special characters in a netcdf object name for SectionSpec.

Parameters:
vname - the name
Returns:
escaped version of it

unescapeName

public static String unescapeName(String vname)
Unescape any escaped characters in a name.

Parameters:
vname - the escaped name
Returns:
unescaped version of it

makeFullName

protected static String makeFullName(Variable v)

makeFullNameEscaped

protected static String makeFullNameEscaped(Variable v)

makeFullNameEscapedSectionSpec

protected static String makeFullNameEscapedSectionSpec(Variable v)

makeFullName

protected static String makeFullName(Variable v,
                                     String reserved)

registerIOProvider

public static void registerIOProvider(String className)
                               throws IllegalAccessException,
                                      InstantiationException,
                                      ClassNotFoundException
Register an IOServiceProvider, using its class string name.

Parameters:
className - Class that implements IOServiceProvider.
Throws:
IllegalAccessException - if class is not accessible.
InstantiationException - if class doesnt have a no-arg constructor.
ClassNotFoundException - if class not found.

registerIOProvider

public static void registerIOProvider(Class iospClass)
                               throws IllegalAccessException,
                                      InstantiationException
Register an IOServiceProvider. A new instance will be created when one of its files is opened.

Parameters:
iospClass - Class that implements IOServiceProvider.
Throws:
IllegalAccessException - if class is not accessible.
InstantiationException - if class doesnt have a no-arg constructor.
ClassCastException - if class doesnt implement IOServiceProvider interface.

setDebugFlags

public static void setDebugFlags(DebugFlags debugFlag)
debugging

Parameters:
debugFlag - debug flags

setProperty

public static void setProperty(String name,
                               String value)
Set properties. Currently recognized: "syncExtendOnly", "true" or "false" (default). if true, can only extend file on a sync.

Parameters:
name - name of property
value - value of property

open

public static NetcdfFile open(String location)
                       throws IOException
Open an existing netcdf file (read only).

Parameters:
location - location of file.
Returns:
the NetcdfFile.
Throws:
IOException - if error

open

public static NetcdfFile open(String location,
                              CancelTask cancelTask)
                       throws IOException
Open an existing file (read only), with option of cancelling.

Parameters:
location - location of the file.
cancelTask - allow task to be cancelled; may be null.
Returns:
NetcdfFile object, or null if cant find IOServiceProver
Throws:
IOException - if error

open

public static NetcdfFile open(String location,
                              int buffer_size,
                              CancelTask cancelTask)
                       throws IOException
Open an existing file (read only), with option of cancelling, setting the RandomAccessFile buffer size for efficiency.

Parameters:
location - location of file.
buffer_size - RandomAccessFile buffer size, if <= 0, use default size
cancelTask - allow task to be cancelled; may be null.
Returns:
NetcdfFile object, or null if cant find IOServiceProver
Throws:
IOException - if error

open

public static NetcdfFile open(String location,
                              int buffer_size,
                              CancelTask cancelTask,
                              Object iospMessage)
                       throws IOException
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.

Parameters:
location - location of file. This may be a
  1. local netcdf-3 filename (with a file: prefix or no prefix)
  2. remote netcdf-3 filename (with an http: prefix)
  3. local netcdf-4 filename (with a file: prefix or no prefix)
  4. local hdf-5 filename (with a file: prefix or no prefix)
  5. local iosp filename (with a file: prefix or no prefix)
If file ends with ".Z", ".zip", ".gzip", ".gz", or ".bz2", it will uncompress/unzip and write to new file without the suffix, then use the uncompressed file. It will look for the uncompressed file before it does any of that. Generally it prefers to place the uncompressed file in the same directory as the original file. If it does not have write permission on that directory, it will use the directory defined by ucar.nc2.util.DiskCache class.
buffer_size - RandomAccessFile buffer size, if <= 0, use default size
cancelTask - allow task to be cancelled; may be null.
iospMessage - special iosp tweaking (sent before open is called), may be null
Returns:
NetcdfFile object, or null if cant find IOServiceProver
Throws:
IOException - if error

canOpen

public static boolean canOpen(String location)
                       throws IOException
Find out if the file can be opened, but dont actually open it.

Parameters:
location - same as open
Returns:
true if can be opened
Throws:
IOException - on read error

open

public static NetcdfFile open(String location,
                              String iospClassName,
                              int bufferSize,
                              CancelTask cancelTask,
                              Object iospMessage)
                       throws ClassNotFoundException,
                              IllegalAccessException,
                              InstantiationException,
                              IOException
Open an existing file (read only), specifying which IOSP is to be used.

Parameters:
location - location of file
iospClassName - fully qualified class name of the IOSP class to handle this file
bufferSize - RandomAccessFile buffer size, if <= 0, use default size
cancelTask - allow task to be cancelled; may be null.
iospMessage - special iosp tweaking (sent before open is called), may be null
Returns:
NetcdfFile object, or null if cant find IOServiceProver
Throws:
IOException - if read error
ClassNotFoundException - cannat find iospClassName in thye class path
InstantiationException - if class cannot be instantiated
IllegalAccessException - if class is not accessible

openInMemory

public static NetcdfFile openInMemory(String name,
                                      byte[] data,
                                      String iospClassName)
                               throws IOException,
                                      ClassNotFoundException,
                                      IllegalAccessException,
                                      InstantiationException
Open an in-memory netcdf file, with a specific iosp.

Parameters:
name - name of the dataset. Typically use the filename or URI.
data - in-memory netcdf file
iospClassName - fully qualified class name of the IOSP class to handle this file
Returns:
NetcdfFile object, or null if cant find IOServiceProver
Throws:
IOException - if read error
ClassNotFoundException - cannat find iospClassName in the class path
InstantiationException - if class cannot be instantiated
IllegalAccessException - if class is not accessible

openInMemory

public static NetcdfFile openInMemory(String name,
                                      byte[] data)
                               throws IOException
Open an in-memory netcdf file.

Parameters:
name - name of the dataset. Typically use the filename or URI.
data - in-memory netcdf file
Returns:
memory-resident NetcdfFile
Throws:
IOException - if error

openInMemory

public static NetcdfFile openInMemory(String filename)
                               throws IOException
Read a local CDM file into memory. All reads are then done from memory.

Parameters:
filename - location of CDM file, must be a local file.
Returns:
a NetcdfFile, which is completely in memory
Throws:
IOException - if error reading file

openInMemory

public static NetcdfFile openInMemory(URI uri)
                               throws IOException
Read a remote CDM file into memory. All reads are then done from memory.

Parameters:
uri - location of CDM file, must be accessible through uri.toURL().openStream().
Returns:
a NetcdfFile, which is completely in memory
Throws:
IOException - if error reading file

isUnlocked

public boolean isUnlocked()

close

public void close()
           throws IOException
Close all resources (files, sockets, etc) associated with this file. If the underlying file was acquired, it will be released, otherwise closed. if isClosed() already, nothing will happen

Specified by:
close in interface FileCacheable
Throws:
IOException - if error when closing

setFileCache

public void setFileCache(FileCache cache)
Public by accident. Optional file caching.

Specified by:
setFileCache in interface FileCacheable
Parameters:
cache - must store this, use it on close as above.

getCacheName

public String getCacheName()
Public by accident. Get the name used in the cache, if any.

Returns:
name in the cache.

setCacheName

protected void setCacheName(String cacheName)
Public by accident.

Parameters:
cacheName - name in the cache, should be unique for this NetcdfFile. Usually the location.

getLocation

public String getLocation()
Get the NetcdfFile location. This is a URL, or a file pathname.

Specified by:
getLocation in interface FileCacheable
Returns:
location URL or file pathname.

getId

public String getId()
Get the globally unique dataset identifier, if it exists.

Returns:
id, or null if none.

getTitle

public String getTitle()
Get the human-readable title, if it exists.

Returns:
title, or null if none.

getRootGroup

public Group getRootGroup()
Get the root group.

Returns:
root group

getVariables

public List<Variable> getVariables()
Get all of the variables in the file, in all groups. This is part of "version 3 compatibility" interface. Alternatively, use groups.

Returns:
List of type Variable.

findGroup

public Group findGroup(String fullName)
Find a Group, with the specified (full) name. An embedded "/" is interpreted as separating group names.

Parameters:
fullName - eg "/group/subgroup/wantGroup". Null or empty string returns the root group.
Returns:
Group or null if not found.

findVariable

public Variable findVariable(String fullNameEscaped)
Find a Variable, with the specified (escaped full) name. It may possibly be nested in multiple groups and/or structures. An embedded "." is interpreted as structure.member. An embedded "/" is interpreted as group/variable. If the name actually has a ".", you must escape it (call NetcdfFile.escapeName(varname)) Any other chars may also be escaped, as they are removed before testing.

Parameters:
fullNameEscaped - eg "/group/subgroup/name1.name2.name".
Returns:
Variable or null if not found.
See Also:
escapeName(java.lang.String), unescapeName(java.lang.String)

getDimensions

public List<Dimension> getDimensions()
Get the shared Dimensions used in this file. This is part of "version 3 compatibility" interface.

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.

Returns:
List of type Dimension.

findDimension

public Dimension findDimension(String name)
Retrieve a dimension by fullName.

Parameters:
name - dimension full name, (using parent group names if not in the root group)
Returns:
the dimension, or null if not found

hasUnlimitedDimension

public boolean hasUnlimitedDimension()
Return true if this file has one or more unlimited (record) dimension.

Returns:
if this file has an unlimited Dimension(s)

getUnlimitedDimension

public Dimension getUnlimitedDimension()
Return the unlimited (record) dimension, or null if not exist. If there are multiple unlimited dimensions, it will return the first one.

Returns:
the unlimited Dimension, or null if none.

getGlobalAttributes

public List<Attribute> getGlobalAttributes()
Returns the set of global attributes associated with this file. This is part of "version 3 compatibility" interface. Alternatively, use groups.

Returns:
List of type Attribute

findGlobalAttribute

public Attribute findGlobalAttribute(String name)
Look up global Attribute by (full) name.

Parameters:
name - the name of the attribute
Returns:
the attribute, or null if not found

findGlobalAttributeIgnoreCase

public Attribute findGlobalAttributeIgnoreCase(String name)
Look up global Attribute by name, ignore case.

Parameters:
name - the name of the attribute
Returns:
the attribute, or null if not found

findAttValueIgnoreCase

public 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. If not found return defaultValue

Parameters:
v - the variable or null for global attribute
attName - the (full) name of the attribute, case insensitive
defaultValue - return this if attribute not found
Returns:
the attribute value, or defaultValue if not found

readAttributeDouble

public double readAttributeDouble(Variable v,
                                  String attName,
                                  double defValue)

readAttributeInteger

public int readAttributeInteger(Variable v,
                                String attName,
                                int defValue)

writeCDL

public void writeCDL(OutputStream out,
                     boolean strict)
Write CDL representation to OutputStream.

Parameters:
out - write to this OutputStream
strict - if true, make it stricly CDL, otherwise, add a little extra info

writeCDL

public void writeCDL(PrintWriter pw,
                     boolean strict)
Write CDL representation to PrintWriter.

Parameters:
pw - write to this PrintWriter
strict - if true, make it stricly CDL, otherwise, add a little extra info

toString

public String toString()
CDL representation of Netcdf header info.

Overrides:
toString in class Object

toStringStart

protected void toStringStart(PrintWriter pw,
                             boolean strict)

toStringEnd

protected void toStringEnd(PrintWriter pw)

writeNcML

public void writeNcML(OutputStream os,
                      String uri)
               throws IOException
Write the NcML representation: dont show coodinate values

Parameters:
os - : write to this Output Stream.
uri - use this for the uri attribute; if null use getLocation(). // ??
Throws:
IOException - if error
See Also:
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)

writeNcML

public void writeNcML(Writer writer,
                      String uri)
               throws IOException
Write the NcML representation: dont show coodinate values

Parameters:
writer - : write to this Writer, should have encoding of UTF-8 if applicable
uri - use this for the uri attribute; if null use getLocation().
Throws:
IOException - if error
See Also:
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)

syncExtend

public boolean syncExtend()
                   throws IOException
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, ok if dimension lengths, data has changed. All previous object references (variables, dimensions, etc) remain valid.

Returns:
true if file was extended.
Throws:
IOException - if error

sync

public boolean sync()
             throws 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. DO NOT USE THIS ROUTINE YET - NOT FULLY TESTED

Specified by:
sync in interface FileCacheable
Returns:
true if file was changed.
Throws:
IOException - if error

addAttribute

public Attribute addAttribute(Group parent,
                              Attribute att)
Add an attribute to a group.

Parameters:
parent - add to this group. If group is null, use root group
att - add this attribute
Returns:
the attribute that was added

addGroup

public Group addGroup(Group parent,
                      Group g)
Add a group to the parent group.

Parameters:
parent - add to this group. If group is null, use root group
g - add this group
Returns:
the group that was added

addDimension

public Dimension addDimension(Group parent,
                              Dimension d)
Add a shared Dimension to a Group.

Parameters:
parent - add to this group. If group is null, use root group
d - add this Dimension
Returns:
the dimension that was added

removeDimension

public boolean removeDimension(Group g,
                               String dimName)
Remove a shared Dimension from a Group by name.

Parameters:
g - remove from this group. If group is null, use root group
dimName - name of Dimension to remove.
Returns:
true if found and removed.

addVariable

public Variable addVariable(Group g,
                            Variable v)
Add a Variable to the given group.

Parameters:
g - add to this group. If group is null, use root group
v - add this Variable
Returns:
the variable that was added

addVariable

public Variable addVariable(Group g,
                            String shortName,
                            DataType dtype,
                            String dims)
Create a new Variable, and add to the given group.

Parameters:
g - add to this group. If group is null, use root group
shortName - short name of the Variable
dtype - data type of the Variable
dims - list of dimension names
Returns:
the new Variable

addStringVariable

public Variable addStringVariable(Group g,
                                  String shortName,
                                  String dims,
                                  int strlen)
Create a new Variable of type Datatype.CHAR, and add to the given group.

Parameters:
g - add to this group. If group is null, use root group
shortName - short name of the Variable
dims - list of dimension names
strlen - dimension length of the inner (fastest changing) dimension
Returns:
the new Variable

removeVariable

public boolean removeVariable(Group g,
                              String varName)
Remove a Variable from the given group by name.

Parameters:
g - remove from this group. If group is null, use root group
varName - name of variable to remove.
Returns:
true is variable found and removed

addVariableAttribute

public Attribute addVariableAttribute(Variable v,
                                      Attribute att)
Add a variable attribute.

Parameters:
v - add to this Variable.
att - add this attribute
Returns:
the added Attribute

sendIospMessage

public Object sendIospMessage(Object message)
Generic way to send a "message" to the underlying IOSP. This message is sent after the file is open. To affect the creation of the file, you must send into the factory method.

Parameters:
message - iosp specific message Special:
  • NetcdfFile.IOSP_MESSAGE_ADD_RECORD_STRUCTURE : tells Netcdf-3 files to make record (unlimited) variables into a structure. return true if it has a Nectdf-3 record structure
Returns:
iosp specific return, may be null

makeRecordStructure

protected Boolean makeRecordStructure()
If there is an unlimited dimension, make all variables that use it into a Structure. A Variable called "record" is added. You can then access these through the record structure.

Returns:
true if it has a Nectdf-3 record structure

removeRecordStructure

protected Boolean removeRecordStructure()

setId

public void setId(String id)
Set the globally unique dataset identifier.

Parameters:
id - the id

setTitle

public void setTitle(String title)
Set the dataset "human readable" title.

Parameters:
title - the title

setLocation

public void setLocation(String location)
Set the location, a URL or local filename.

Parameters:
location - the location

setImmutable

public NetcdfFile setImmutable()
Make this immutable.

Returns:
this

empty

public void empty()
Completely empty the objects in the netcdf file. Used for rereading the file on a sync().


makeRootGroup

protected Group makeRootGroup()

finish

public void finish()
Finish constructing the object model. This construsts the "global" variables, attributes and dimensions. It also looks for coordinate variables.


makeFullNameWithString

protected String makeFullNameWithString(Group parent,
                                        String name)

readData

protected Array readData(Variable v,
                         Section ranges)
                  throws IOException,
                         InvalidRangeException
Throws:
IOException
InvalidRangeException

readSection

public Array readSection(String variableSection)
                  throws IOException,
                         InvalidRangeException
Read a variable using the given section specification. The result is always an array of the type of the innermost variable. Its shape is the accumulation of all the shapes of its parent structures.

Parameters:
variableSection - the constraint expression.
Returns:
data requested
Throws:
IOException - if error
InvalidRangeException - if variableSection is invalid
See Also:
SectionSpecification

readToByteChannel

protected long readToByteChannel(Variable v,
                                 Section section,
                                 WritableByteChannel wbc)
                          throws IOException,
                                 InvalidRangeException
Read data from a top level Variable and send data to a WritableByteChannel. Experimental.

Parameters:
v - a top-level Variable
section - 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
Returns:
the number of bytes written to the channel
Throws:
IOException - if read error
InvalidRangeException - if invalid section

getStructureIterator

protected StructureDataIterator getStructureIterator(Structure s,
                                                     int bufferSize)
                                              throws IOException
Throws:
IOException

readArrays

public List<Array> readArrays(List<Variable> variables)
                       throws IOException
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. This is mostly here so DODSNetcdf can override it with one call to the server.

Parameters:
variables - List of type Variable
Returns:
List of Array, one for each Variable in the input.
Throws:
IOException - if read error

read

public Array read(String variableSection,
                  boolean flatten)
           throws IOException,
                  InvalidRangeException
Deprecated. use readSection(), flatten=false no longer supported

Read a variable using the given section specification.

Parameters:
variableSection - the constraint expression.
flatten - MUST BE TRUE
Returns:
Array data read.
Throws:
IOException - if error
InvalidRangeException - if variableSection is invalid
See Also:
SectionSpecification

toStringDebug

protected String toStringDebug(Object o)
Access to iosp debugging info.

Parameters:
o - must be a Variable, Dimension, Attribute, or Group
Returns:
debug info for this object.

getDetailInfo

public String getDetailInfo()
Access to iosp debugging info.

Returns:
debug / underlying implementation details

getDetailInfo

public void getDetailInfo(Formatter f)

showCached

protected void showCached(Formatter f)

showProxies

protected void showProxies(Formatter f)

getIosp

public IOServiceProvider getIosp()
DO NOT USE - public by accident

Returns:
the IOSP for this NetcdfFile

getFileTypeId

public String getFileTypeId()
Get the file type id for the underlying data source.

Returns:
registered id of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getFileTypeDescription

public String getFileTypeDescription()
Get a human-readable description for this file type.

Returns:
description of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getFileTypeVersion

public String getFileTypeVersion()
Get the version of this file type.

Returns:
version of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

main

public static void main(String[] arg)
                 throws Exception
debugging - do not use

Throws:
Exception


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.