NetcdfFile (NetCDF-Java 4.2 Public and Private API)

java.lang.Object
- 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 java.lang.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

Fields
Modifier and Type	Field and Description
`protected FileCache`	`cache`
`protected java.lang.String`	`cacheName`
`protected static boolean`	`debugCompress`
`protected static boolean`	`debugSPI`
`protected java.util.List<Dimension>`	`dimensions`
`protected java.util.List<Attribute>`	`gattributes`
`protected java.lang.String`	`id`
`static java.lang.String`	`IOSP_MESSAGE_ADD_RECORD_STRUCTURE`
`static java.lang.String`	`IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE`
`static java.lang.String`	`IOSP_MESSAGE_RANDOM_ACCESS_FILE`
`static java.lang.String`	`IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE`
`protected java.lang.String`	`location`
`static java.lang.String`	`reserved`
`static java.lang.String`	`reservedCdl`
`static java.lang.String`	`reservedSectionSpec`
`protected Group`	`rootGroup`
`protected static boolean`	`showRequest`
`protected IOServiceProvider`	`spi`
`protected java.lang.String`	`title`
`protected boolean`	`unlocked`
`protected java.util.List<Variable>`	`variables`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`NetcdfFile()` For subclass construction.
`protected`	`NetcdfFile(IOServiceProvider spi, RandomAccessFile raf, java.lang.String location, CancelTask cancelTask)` Open an existing netcdf file (read only).
`protected`	`NetcdfFile(NetcdfFile ncfile)` Copy constructor, used by NetcdfDataset.
	`NetcdfFile(java.lang.String filename)` Deprecated. use NetcdfFile.open( location) or NetcdfDataset.openFile( location)
`protected`	`NetcdfFile(java.lang.String iospClassName, java.lang.String iospParam, java.lang.String location, int buffer_size, CancelTask cancelTask)` Open an existing netcdf file (read only), using the specified iosp.
	`NetcdfFile(java.net.URL url)` Deprecated. use NetcdfFile.open( http:location) or NetcdfDataset.openFile( http:location)

Method Summary

Methods
Modifier and Type	Method and Description
`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 standard special characters in a netcdf object name.
`static java.lang.String`	`escapeNameCDL(java.lang.String vname)` Escape special characters in a netcdf object name for CDL.
`static java.lang.String`	`escapeNameSectionSpec(java.lang.String vname)` Escape special characters in a netcdf object name for SectionSpec.
`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 fullName)` Find a Group, with the specified (full) name.
`Variable`	`findVariable(java.lang.String fullNameEscaped)` Find a Variable, with the specified (escaped 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.
`void`	`getDetailInfo(java.util.Formatter f)`
`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.
`IOServiceProvider`	`getIosp()` DO NOT USE - public by accident
`java.lang.String`	`getLocation()` Get the NetcdfFile location.
`Group`	`getRootGroup()` Get the root group.
`protected StructureDataIterator`	`getStructureIterator(Structure s, int bufferSize)`
`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
`protected static java.lang.String`	`makeFullName(Variable v)`
`protected static java.lang.String`	`makeFullName(Variable v, java.lang.String reserved)`
`protected static java.lang.String`	`makeFullNameEscaped(Variable v)`
`protected static java.lang.String`	`makeFullNameEscapedSectionSpec(Variable v)`
`protected java.lang.String`	`makeFullNameWithString(Group parent, java.lang.String name)`
`protected java.lang.Boolean`	`makeRecordStructure()` If there is an unlimited dimension, make all variables that use it into a Structure.
`protected Group`	`makeRootGroup()`
`static java.lang.String`	`makeValidCdmObjectName(java.lang.String name)` Create a valid CDM object name.
`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.lang.String name, byte[] data, java.lang.String iospClassName)` Open an in-memory netcdf file, with a specific iosp.
`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)`
`protected Array`	`readData(Variable v, Section ranges)`
`Array`	`readSection(java.lang.String variableSection)` Read a variable using the given section specification.
`protected long`	`readToByteChannel(Variable v, Section section, java.nio.channels.WritableByteChannel wbc)` Read data from a top level Variable and send data to a WritableByteChannel.
`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.
`protected java.lang.Boolean`	`removeRecordStructure()`
`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.
`protected void`	`setCacheName(java.lang.String cacheName)` Public by accident.
`static void`	`setDebugFlags(DebugFlags debugFlag)` debugging
`void`	`setFileCache(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.
`protected void`	`showCached(java.util.Formatter f)`
`protected void`	`showProxies(java.util.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.
`java.lang.String`	`toString()` CDL representation of Netcdf header info.
`protected java.lang.String`	`toStringDebug(java.lang.Object o)` Access to iosp debugging info.
`protected void`	`toStringEnd(java.io.PrintWriter pw)`
`protected void`	`toStringStart(java.io.PrintWriter pw, boolean strict)`
`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
clone, equals, finalize, 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_CONVERT_RECORD_STRUCTURE
```
public static final java.lang.String IOSP_MESSAGE_CONVERT_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
  - IOSP_MESSAGE_RANDOM_ACCESS_FILE
```
public static final java.lang.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 java.lang.String reserved
```
    See Also:
    Constant Field Values
  - reservedSectionSpec
```
public static final java.lang.String reservedSectionSpec
```
    See Also:
    Constant Field Values
  - reservedCdl
```
public static final java.lang.String reservedCdl
```
    See Also:
    Constant Field Values
  - location
```
protected java.lang.String location
```
  - id
```
protected java.lang.String id
```
  - title
```
protected java.lang.String title
```
  - cacheName
```
protected java.lang.String cacheName
```
  - rootGroup
```
protected Group rootGroup
```
  - unlocked
```
protected boolean unlocked
```
  - cache
```
protected FileCache cache
```
  - spi
```
protected IOServiceProvider spi
```
  - variables
```
protected java.util.List<Variable> variables
```
  - dimensions
```
protected java.util.List<Dimension> dimensions
```
  - gattributes
```
protected java.util.List<Attribute> gattributes
```
- 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
  - NetcdfFile
```
protected NetcdfFile(java.lang.String iospClassName,
          java.lang.String iospParam,
          java.lang.String location,
          int buffer_size,
          CancelTask cancelTask)
              throws java.io.IOException,
                     java.lang.IllegalAccessException,
                     java.lang.InstantiationException,
                     java.lang.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:
    
    java.lang.ClassNotFoundException - if the iospClassName cannot be found
    
    java.lang.IllegalAccessException - if the class or its nullary constructor is not accessible.
    
    java.lang.InstantiationException - if the class cannot be instatiated, eg if it has no nullary constructor
    
    java.io.IOException - if I/O error
  - NetcdfFile
```
protected NetcdfFile(IOServiceProvider spi,
          RandomAccessFile raf,
          java.lang.String location,
          CancelTask cancelTask)
              throws java.io.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:
    
    java.io.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 java.lang.String makeValidCdmObjectName(java.lang.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 java.lang.String escapeName(java.lang.String vname)
```
    Escape standard special characters in a netcdf object name.
    
    Parameters:
    vname - the name
    
    Returns:
    escaped version of it
  - escapeNameCDL
```
public static java.lang.String escapeNameCDL(java.lang.String vname)
```
    Escape special characters in a netcdf object name for CDL.
    
    Parameters:
    vname - the name
    
    Returns:
    escaped version of it
  - escapeNameSectionSpec
```
public static java.lang.String escapeNameSectionSpec(java.lang.String vname)
```
    Escape special characters in a netcdf object name for SectionSpec.
    
    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
  - makeFullName
```
protected static java.lang.String makeFullName(Variable v)
```
  - makeFullNameEscaped
```
protected static java.lang.String makeFullNameEscaped(Variable v)
```
  - makeFullNameEscapedSectionSpec
```
protected static java.lang.String makeFullNameEscapedSectionSpec(Variable v)
```
  - makeFullName
```
protected static java.lang.String makeFullName(Variable v,
                            java.lang.String reserved)
```
  - 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
    
    local netcdf-3 filename (with a file: prefix or no prefix)
    remote netcdf-3 filename (with an http: prefix)
    local netcdf-4 filename (with a file: prefix or no prefix)
    local hdf-5 filename (with a file: prefix or no prefix)
    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,
                      java.lang.String iospClassName)
                               throws java.io.IOException,
                                      java.lang.ClassNotFoundException,
                                      java.lang.IllegalAccessException,
                                      java.lang.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:
    
    java.io.IOException - if read error
    
    java.lang.ClassNotFoundException - cannat find iospClassName in the 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 FileCacheable
    
    Throws:
    
    java.io.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 java.lang.String getCacheName()
```
    Public by accident. Get the name used in the cache, if any.
    
    Returns:
    name in the cache.
  - setCacheName
```
protected void setCacheName(java.lang.String cacheName)
```
    Public by accident.
    
    Parameters:
    cacheName - name in the cache, should be unique for this NetcdfFile. Usually the location.
  - getLocation
```
public java.lang.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 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.
  - findGroup
```
public Group findGroup(java.lang.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(java.lang.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 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
  - toStringStart
```
protected void toStringStart(java.io.PrintWriter pw,
                 boolean strict)
```
  - toStringEnd
```
protected void toStringEnd(java.io.PrintWriter pw)
```
  - 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 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
  - makeRecordStructure
```
protected java.lang.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 java.lang.Boolean removeRecordStructure()
```
  - 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().
  - 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 java.lang.String makeFullNameWithString(Group parent,
                                      java.lang.String name)
```
  - readData
```
protected Array readData(Variable v,
             Section ranges)
                  throws java.io.IOException,
                         InvalidRangeException
```
    Throws:
    
    java.io.IOException
    
    InvalidRangeException
  - 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
  - readToByteChannel
```
protected long readToByteChannel(Variable v,
                     Section section,
                     java.nio.channels.WritableByteChannel wbc)
                          throws java.io.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:
    
    java.io.IOException - if read error
    
    InvalidRangeException - if invalid section
  - getStructureIterator
```
protected StructureDataIterator getStructureIterator(Structure s,
                                         int bufferSize)
                                              throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - 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
  - toStringDebug
```
protected java.lang.String toStringDebug(java.lang.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 java.lang.String getDetailInfo()
```
    Access to iosp debugging info.
    
    Returns:
    debug / underlying implementation details
  - getDetailInfo
```
public void getDetailInfo(java.util.Formatter f)
```
  - showCached
```
protected void showCached(java.util.Formatter f)
```
  - showProxies
```
protected void showProxies(java.util.Formatter f)
```
  - getIosp
```
public 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

Class NetcdfFile

Naming

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

IOSP_MESSAGE_ADD_RECORD_STRUCTURE

IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE

IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE

IOSP_MESSAGE_RANDOM_ACCESS_FILE

debugSPI

debugCompress

showRequest

reserved

reservedSectionSpec

reservedCdl

location

id

title

cacheName

rootGroup

unlocked

cache

spi

variables

dimensions

gattributes

Constructor Detail

NetcdfFile

NetcdfFile

NetcdfFile

NetcdfFile

NetcdfFile

NetcdfFile

Method Detail

makeValidCdmObjectName

escapeName

escapeNameCDL

escapeNameSectionSpec

unescapeName

makeFullName

makeFullNameEscaped

makeFullNameEscapedSectionSpec

makeFullName

registerIOProvider

registerIOProvider

setDebugFlags

setProperty

open

open

open

open

canOpen

open

openInMemory

openInMemory

openInMemory

openInMemory

isUnlocked

close

setFileCache

getCacheName

setCacheName

getLocation

getId

getTitle

getRootGroup

getVariables

findGroup

findVariable

getDimensions

findDimension

hasUnlimitedDimension

getUnlimitedDimension

getGlobalAttributes

findGlobalAttribute

findGlobalAttributeIgnoreCase

findAttValueIgnoreCase

readAttributeDouble