ucar.nc2

Class NetcdfFile

java.lang.Object

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. 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
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
static java.lang.String	reserved
static java.lang.String	reservedCdl
static java.lang.String	reservedSectionSpec

Constructor Summary

Constructors

Constructor and Description
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

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.
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 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)
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_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

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

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

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

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

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

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.

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

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

getDetailInfo

public java.lang.String getDetailInfo()

Access to iosp debugging info.

Returns:

debug / underlying implementation details

getDetailInfo

public void getDetailInfo(java.util.Formatter f)

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