ucar.nc2
Class NetcdfFile

java.lang.Object
  extended by ucar.nc2.NetcdfFile
All Implemented Interfaces:
ucar.nc2.util.cache.FileCacheable
Direct Known Subclasses:
NetcdfDataset, NetcdfFileWriteable

public class NetcdfFile
extends java.lang.Object
implements ucar.nc2.util.cache.FileCacheable

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

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
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

IOSP_MESSAGE_ADD_RECORD_STRUCTURE

public static final java.lang.String IOSP_MESSAGE_ADD_RECORD_STRUCTURE
See Also:
Constant Field Values

IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

public static final java.lang.String IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE
See Also:
Constant Field Values

reserved

public static final java.lang.String reserved
The set of characters in a netcdf object name that must be escaped.

See Also:
Constant Field Values
Constructor Detail

NetcdfFile

public NetcdfFile(java.lang.String filename)
           throws java.io.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:
java.io.IOException - if error

NetcdfFile

public NetcdfFile(java.net.URL url)
           throws java.io.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:
java.io.IOException - if error
Method Detail

escapeName

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

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

unescapeName

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

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

registerIOProvider

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

Parameters:
className - Class that implements IOServiceProvider.
Throws:
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.

registerIOProvider

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

Parameters:
iospClass - Class that implements IOServiceProvider.
Throws:
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.

setDebugFlags

public static void setDebugFlags(DebugFlags debugFlag)
debugging

Parameters:
debugFlag - debug flags

setProperty

public static void setProperty(java.lang.String name,
                               java.lang.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(java.lang.String location)
                       throws java.io.IOException
Open an existing netcdf file (read only).

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

open

public static NetcdfFile open(java.lang.String location,
                              CancelTask cancelTask)
                       throws java.io.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:
java.io.IOException - if error

open

public static NetcdfFile open(java.lang.String location,
                              int buffer_size,
                              CancelTask cancelTask)
                       throws java.io.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:
java.io.IOException - if error

open

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

canOpen

public static boolean canOpen(java.lang.String location)
                       throws java.io.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:
java.io.IOException - on read error

open

public 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
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:
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 accessible

openInMemory

public static NetcdfFile openInMemory(java.lang.String name,
                                      byte[] data)
                               throws java.io.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:
java.io.IOException - if error

openInMemory

public static NetcdfFile openInMemory(java.lang.String filename)
                               throws java.io.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:
java.io.IOException - if error reading file

openInMemory

public static NetcdfFile openInMemory(java.net.URI uri)
                               throws java.io.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:
java.io.IOException - if error reading file

isUnlocked

public boolean isUnlocked()

close

public void close()
           throws java.io.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 ucar.nc2.util.cache.FileCacheable
Throws:
java.io.IOException - if error when closing

setFileCache

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

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

getCacheName

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

Returns:
name in the cache.

getLocation

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

Specified by:
getLocation in interface ucar.nc2.util.cache.FileCacheable
Returns:
location URL or file pathname.

getId

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

Returns:
id, or null if none.

getTitle

public java.lang.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 java.util.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.

findTopVariable

public Variable findTopVariable(java.lang.String name)
Retrieve the Variable with the specified (full) name, which is not a member of a Structure.

Parameters:
name - full name, starting from root group.
Returns:
the Variable, or null if not found

findGroup

public Group findGroup(java.lang.String fullNameEscaped)
Find a Group, with the specified (full) name. An embedded "/" is interpreted as seperating group names. If the name actually has a "/", you must escape it (replace with "%2f")

Parameters:
fullNameEscaped - eg "/group/subgroup/wantGroup". Null or empty string returns the root group. Any chars may be escaped
Returns:
Group or null if not found.
See Also:
escapeName(java.lang.String), unescapeName(java.lang.String)

findVariable

public Variable findVariable(java.lang.String fullNameEscaped)
Find a Variable, with the specified (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 (replace with "%2e") If the name actually has a "/", you must escape it (replace with "%2f")

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

getDimensions

public java.util.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(java.lang.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 java.util.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(java.lang.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(java.lang.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 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. 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,
                                  java.lang.String attName,
                                  double defValue)

readAttributeInteger

public int readAttributeInteger(Variable v,
                                java.lang.String attName,
                                int defValue)

writeCDL

public void writeCDL(java.io.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(java.io.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 java.lang.String toString()
CDL representation of Netcdf header info.

Overrides:
toString in class java.lang.Object

writeNcML

public void writeNcML(java.io.OutputStream os,
                      java.lang.String uri)
               throws java.io.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:
java.io.IOException - if error
See Also:
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)

writeNcML

public void writeNcML(java.io.Writer writer,
                      java.lang.String uri)
               throws java.io.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:
java.io.IOException - if error
See Also:
NCdumpW.writeNcML(ucar.nc2.NetcdfFile, java.io.Writer, boolean, java.lang.String)

syncExtend

public boolean syncExtend()
                   throws java.io.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:
java.io.IOException - if error

sync

public boolean sync()
             throws java.io.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 ucar.nc2.util.cache.FileCacheable
Returns:
true if file was changed.
Throws:
java.io.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,
                               java.lang.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,
                            java.lang.String shortName,
                            DataType dtype,
                            java.lang.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,
                                  java.lang.String shortName,
                                  java.lang.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,
                              java.lang.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 java.lang.Object sendIospMessage(java.lang.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

setId

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

Parameters:
id - the id

setTitle

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

Parameters:
title - the title

setLocation

public void setLocation(java.lang.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().


finish

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


readArrays

public java.util.List<Array> readArrays(java.util.List<Variable> variables)
                                 throws java.io.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:
java.io.IOException - if read error

read

public Array read(java.lang.String variableSection,
                  boolean flatten)
           throws java.io.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:
java.io.IOException - if error
InvalidRangeException - if variableSection is invalid
See Also:
SectionSpecification

readSection

public Array readSection(java.lang.String variableSection)
                  throws java.io.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:
java.io.IOException - if error
InvalidRangeException - if variableSection is invalid
See Also:
SectionSpecification

getDetailInfo

public java.lang.String getDetailInfo()
Access to iosp debugging info.

Returns:
debug / underlying implementation details

getIosp

public ucar.nc2.iosp.IOServiceProvider getIosp()
DO NOT USE - public by accident

Returns:
the IOSP for this NetcdfFile

getFileTypeId

public java.lang.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 java.lang.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 java.lang.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(java.lang.String[] arg)
                 throws java.lang.Exception
debugging - do not use

Throws:
java.lang.Exception