ucar.nc2
Class NetcdfFile

java.lang.Object
  ucar.nc2.NetcdfFile

Direct Known Subclasses:

NetcdfDataset, NetcdfFileWriteable

public class NetcdfFile
extends java.lang.Object

Read-only scientific datasets that are accessible through the netCDF API.

Be sure to close the file when done, best practive is to enclose in a try/finally block:

 NetcdfFile ncfile = null;
 try {
 ncfile = NetcdfFile.open(fileName);
 ...
 } finally {
 ncfile.close();
 }
 

Be sure to close the file after opening, eg:

  NetcdfFile ncfile = null;
 try {
 ncfile = NetcdfFile.open(fileName);
 ...
 } finally {
 if (null != ncfile) 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

Constructor Summary

NetcdfFile(java.lang.String filename)
Deprecated. use NetcdfFile.open( location) or NetcdfFileCache.acquire( location)

NetcdfFile(java.net.URL url)
Deprecated. use NetcdfFile.open( http:location) or NetcdfFileCache.acquire( http:location)

Method Summary

void	addAttribute(Group parent, Attribute att) Add an attribute to a group.
void	addDimension(Group parent, Dimension d) Add a shared Dimension to a Group.
void	addGroup(Group parent, Group g) Add a group to the parent group.
void	addMemberVariable(Structure s, Variable v) Add a Variable to the given structure.
boolean	addRecordStructure() If there is an unlimited dimension, make all variables that use it into an array of structures.
void	addVariable(Group g, Variable v) Add a Variable to the given group.
void	addVariableAttribute(Variable v, Attribute att) Add a variable attribute.
void	close() Close all resources (files, sockets, etc) associated with this file.
static java.lang.String	createValidNetcdfObjectName(java.lang.String name) Convert a name to a legal netcdf name.
void	empty() Completely empty the objects in the netcdf file.
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.
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 fullName) Find a variable, with the specified (full) name.
void	finish() Finish constructing the object model.
java.lang.String	getCacheName() Get the name used in the cache, if any.
int	getCacheState() Get the cache state.
java.lang.String	getDetailInfo() Show debug / underlying implementation details
java.util.List<Dimension>	getDimensions() Get the shared Dimensions used in this file.
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
IOServiceProvider	getIosp() Experimental - DO NOT USE!!!
java.lang.String	getLocation() Get the NetcdfFile location.
Group	getRootGroup() Get the root group.
java.lang.String	getTitle() Get the human-readable title.
Dimension	getUnlimitedDimension() Return the unlimited (record) dimension, or null if not exist.
static java.lang.String	getValidNetcdfObjectNamePattern() Valid Netcdf Object name as a regular expression.
java.util.List<Variable>	getVariables() Get all of the variables in the file, in all groups.
boolean	hasRecordStructure() Find out if if it has a record Structure.
boolean	hasUnlimitedDimension() Return true if this file has an unlimited (record) dimension.
boolean	isClosed() is the dataset already closed?
static boolean	isValidNetcdfObjectName(java.lang.String name) Determine if the given name can be used for a Dimension, Attribute, or Variable name.
static void	main(java.lang.String[] arg)
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 spiObject) 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 className, int bufferSize, CancelTask cancelTask, java.lang.String iospParam)
static NetcdfFile	openInMemory(java.lang.String location) Read a netcdf file into memory.
static NetcdfFile	openInMemory(java.lang.String location, byte[] data) Open an in-memory netcdf file.
Array	read(java.lang.String variableSection, boolean flatten) Read a variable using the given section specification, equivilent to readAllStructures() if its a member of a Structure, or read() otherwise.
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.
Array	readData(Variable v, java.util.List section) do not call this directly, use Variable.read() !!
Array	readMemberData(Variable v, java.util.List section, boolean flatten) do not call this directly, use Variable.readSection() !!
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.
static void	setDebugFlags(DebugFlags debugFlag) debugging
static void	setDebugOutputStream(java.io.PrintStream printStream) debugging
void	setId(java.lang.String id) Set the globally unique dataset identifier.
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.
void	writeCDL(java.io.OutputStream os, boolean strict) Write CDL representation to OutputStream.
void	writeNcML(java.io.OutputStream os, 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

Constructor Detail

NetcdfFile

public NetcdfFile(java.lang.String filename)
           throws java.io.IOException

Deprecated. use NetcdfFile.open( location) or NetcdfFileCache.acquire( 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 NetcdfFileCache.acquire( http:location)

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

Parameters:

url - HTTP URL location

Throws:

java.io.IOException - if error

Method Detail

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

setDebugOutputStream

public static void setDebugOutputStream(java.io.PrintStream printStream)

debugging

Parameters:

printStream - write to this stream.

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

spiObject - sent to iosp.setSpecial() if not null

Returns:

NetcdfFile object, or null if cant find IOServiceProver

Throws:

java.io.IOException - if error

openInMemory

public static NetcdfFile openInMemory(java.lang.String location,
                                      byte[] data)
                               throws java.io.IOException

Open an in-memory netcdf file.

Parameters:

location - location of file, used as the name.

data - in-memory netcdf file

Returns:

memory-resident NetcdfFile

Throws:

java.io.IOException - if error

openInMemory

public static NetcdfFile openInMemory(java.lang.String location)
                               throws java.io.IOException

Read a netcdf file into memory. All reads are then done from memory.

Parameters:

location - location of CDM file, used as the name.

Returns:

a NetcdfFile, which is completely in memory

Throws:

java.io.IOException - if error reading file

open

public static NetcdfFile open(java.lang.String location,
                              java.lang.String className,
                              int bufferSize,
                              CancelTask cancelTask,
                              java.lang.String iospParam)
                       throws java.lang.ClassNotFoundException,
                              java.lang.IllegalAccessException,
                              java.lang.InstantiationException,
                              java.io.IOException

Throws:

java.lang.ClassNotFoundException

java.lang.IllegalAccessException

java.lang.InstantiationException

java.io.IOException

isValidNetcdfObjectName

public static boolean isValidNetcdfObjectName(java.lang.String name)

Determine if the given name can be used for a Dimension, Attribute, or Variable name.

Parameters:

name - test this.

Returns:

true if valid name.

getValidNetcdfObjectNamePattern

public static java.lang.String getValidNetcdfObjectNamePattern()

Valid Netcdf Object name as a regular expression.

Returns:

regular expression pattern describing valid Netcdf Object names.

createValidNetcdfObjectName

public static java.lang.String createValidNetcdfObjectName(java.lang.String name)

Convert a name to a legal netcdf name. From the user manual: "The names of dimensions, variables and attributes consist of arbitrary sequences of alphanumeric characters (as well as underscore '_' and hyphen '-'), beginning with a letter or underscore. (However names commencing with underscore are reserved for system use.) Case is significant in netCDF names."

Algorithm:

1. leading character: if alpha or underscore, ok; if digit, prepend "N"; otherwise discard
2. other characters: if space, change to underscore; other delete.

Parameters:

name - convert this name

Returns:

converted name

isClosed

public boolean isClosed()

is the dataset already closed?

Returns:

true if closed

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.

Throws:

java.io.IOException - if error closing

getCacheState

public int getCacheState()

Get the cache state.

Returns:

0 = not cached, 1 = NetcdfFileCache, 2 = NetcdfDatasetCache, 3 = Fmrc

getCacheName

public java.lang.String getCacheName()

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.

Returns:

location URL or file pathname.

getId

public java.lang.String getId()

Get the globally unique dataset identifier

Returns:

id, or null if none.

getTitle

public java.lang.String getTitle()

Get the human-readable title.

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

findVariable

public Variable findVariable(java.lang.String fullName)

Find a variable, with the specified (full) name. It may possibly be nested in multiple groups and/or structures.

Parameters:

fullName - eg "group/subgroup/name1.name2.name".

Returns:

Variable or null if not found.

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 generally better to get the shared Dimensions 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 an 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

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

Read a variable using the given section specification, equivilent to readAllStructures() if its a member of a Structure, or read() otherwise.

Parameters:

variableSection - the constraint expression. This must start with a top variable.

flatten - if true and its a member of a Structure, remove the surrounding StructureData.

Returns:

Array data read.

Throws:

java.io.IOException - if error

InvalidRangeException - if variableSection is invalid

See Also:

for syntax of constraint expression

writeCDL

public void writeCDL(java.io.OutputStream os,
                     boolean strict)

Write CDL representation to OutputStream.

Parameters:

os - write to this OutputStream

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:

NCdump.writeNcML(ucar.nc2.NetcdfFile, java.io.OutputStream, 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, if the unlimited dimension has grown. 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

Returns:

true if file was changed.

Throws:

java.io.IOException - if error

addAttribute

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

addGroup

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

addDimension

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

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

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 void addVariableAttribute(Variable v,
                                 Attribute att)

Add a variable attribute.

Parameters:

v - add to this Variable.

att - add this attribute

addMemberVariable

public void addMemberVariable(Structure s,
                              Variable v)

Add a Variable to the given structure.

Parameters:

s - add to this Structure

v - add this Variable.

addRecordStructure

public boolean addRecordStructure()

If there is an unlimited dimension, make all variables that use it into an array of structures. A Variable called "record" is added. You can then access these through the record structure.

Returns:

true if record was actually added on this call.

hasRecordStructure

public boolean hasRecordStructure()

Find out if if it has a record Structure. Optimization for Netcdf-3 files.

Returns:

true if it has a record Structure

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

finish

public void finish()

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

empty

public void empty()

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

readData

public Array readData(Variable v,
                      java.util.List section)
               throws java.io.IOException,
                      InvalidRangeException

do not call this directly, use Variable.read() !!

Throws:

java.io.IOException

InvalidRangeException

readMemberData

public Array readMemberData(Variable v,
                            java.util.List section,
                            boolean flatten)
                     throws java.io.IOException,
                            InvalidRangeException

do not call this directly, use Variable.readSection() !!

Throws:

java.io.IOException

InvalidRangeException

getDetailInfo

public java.lang.String getDetailInfo()

Show debug / underlying implementation details

getIosp

public IOServiceProvider getIosp()

Experimental - DO NOT USE!!!

Returns:

the IOSP for this NetcdfFile

main

public static void main(java.lang.String[] arg)
                 throws java.lang.Exception

Throws:

java.lang.Exception