ucar.nc2
Class NetcdfFileWriteable

java.lang.Object
  ucar.nc2.NetcdfFile
      ucar.nc2.NetcdfFileWriteable

public class NetcdfFileWriteable
extends NetcdfFile

Create/Write netCDF files.

Because of the limitations of the underlying implementation, netcdf files can only have Dimensions, Attributes and Variables added to it at creation time. Thus, when a file is first opened, it in is "define mode" where these may added. Once create() is called, you can no longer add, delete, or modify the Dimensions, Attributes or Variables.

After create has been called you can then write the Variables' data values.

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

See Also:

NetcdfFile

Constructor Summary

NetcdfFileWriteable()
Deprecated. use createNew(String filename, boolean fill)

NetcdfFileWriteable(java.lang.String location)
Deprecated. use openExisting(String filename, boolean fill)

NetcdfFileWriteable(java.lang.String location, boolean fill)
Deprecated. use createNew(String filename, boolean fill)

Method Summary

Dimension	addDimension(java.lang.String dimName, int length) Add a Dimension to the file.
Dimension	addDimension(java.lang.String dimName, int length, boolean isShared, boolean isUnlimited, boolean isVariableLength) Add a Dimension to the file.
void	addGlobalAttribute(java.lang.String name, Array values) Add a Global attribute of type Array to the file.
void	addGlobalAttribute(java.lang.String name, java.lang.Number value) Add a Global attribute of type Number to the file.
void	addGlobalAttribute(java.lang.String name, java.lang.String value) Add a Global attribute of type String to the file.
Dimension	addUnlimitedDimension(java.lang.String dimName, int length) Add an Uunlimited Dimension to the file.
void	addVariable(java.lang.String varName, java.lang.Class componentType, Dimension[] dims) Deprecated. use addVariable(String varName, DataType dataType, ArrayList dims);
void	addVariable(java.lang.String varName, DataType dataType, Dimension[] dims) Add a variable to the file.
void	addVariable(java.lang.String varName, DataType dataType, java.util.List dims) Add a variable to the file.
void	addVariableAttribute(java.lang.String varName, Attribute att) Add an attribute to the named Variable.
void	addVariableAttribute(java.lang.String varName, java.lang.String attName, Array value) Add an attribute of type Array to the named Variable.
void	addVariableAttribute(java.lang.String varName, java.lang.String attName, java.lang.Number value) Add an attribute of type Number to the named Variable.
void	addVariableAttribute(java.lang.String varName, java.lang.String attName, java.lang.String value) Add an attribute of type String to the named Variable.
void	close() close the file.
void	create() After you have added all of the Dimensions, Variables, and Attributes, call create() to actually create the file.
static NetcdfFileWriteable	createNew(java.lang.String location) Create a new Netcdf file, with fill mode true.
static NetcdfFileWriteable	createNew(java.lang.String location, boolean fill) Create a new Netcdf file, put it into define mode.
void	flush() Flush anything written to disk.
static NetcdfFileWriteable	openExisting(java.lang.String location) Open an existing Netcdf file for writing data.
static NetcdfFileWriteable	openExisting(java.lang.String location, boolean fill) Open an existing Netcdf file for writing data.
void	setFill(boolean fill) Deprecated. use openExisting(String filename, boolean fill) or createNew(String filename, boolean fill)
void	setName(java.lang.String filename) Deprecated. use NetcdfFileWriteable(String filename);
void	write(java.lang.String varName, Array values) Write data to the named variable, origin assumed to be 0.
void	write(java.lang.String varName, int[] origin, Array values) Write data to the named variable.

Methods inherited from class ucar.nc2.NetcdfFile

addAttribute, addDimension, addGroup, addMemberVariable, addRecordStructure, addVariable, addVariableAttribute, createValidNetcdfObjectName, empty, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findTopVariable, findVariable, finish, getCacheName, getCacheState, getDetailInfo, getDimensions, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getValidNetcdfObjectNamePattern, getVariables, hasUnlimitedDimension, isClosed, isNetcdf3FileFormat, isValidNetcdfObjectName, main, open, open, open, open, openInMemory, read, readArrays, readData, readMemberData, registerIOProvider, registerIOProvider, removeDimension, removeVariable, setDebugFlags, setDebugOutputStream, setId, setLocation, setTitle, sync, syncExtend, toString, writeCDL, writeNcML

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NetcdfFileWriteable

public NetcdfFileWriteable(java.lang.String location,
                           boolean fill)

Deprecated. use createNew(String filename, boolean fill)

Create a new Netcdf file, put it into define mode.

NetcdfFileWriteable

public NetcdfFileWriteable()

Deprecated. use createNew(String filename, boolean fill)

Open a new Netcdf file, put it into define mode.

NetcdfFileWriteable

public NetcdfFileWriteable(java.lang.String location)
                    throws java.io.IOException

Deprecated. use openExisting(String filename, boolean fill)

Open an existing Netcdf file for writing data.

Throws:

java.io.IOException

Method Detail

openExisting

public static NetcdfFileWriteable openExisting(java.lang.String location)
                                        throws java.io.IOException

Open an existing Netcdf file for writing data. Fill mode is true. Cannot add new objects, you can only read/write data to existing Variables.

Parameters:

location - name of existing file to open.

Throws:

java.io.IOException

openExisting

public static NetcdfFileWriteable openExisting(java.lang.String location,
                                               boolean fill)
                                        throws java.io.IOException

Open an existing Netcdf file for writing data. Cannot add new objects, you can only read/write data to existing Variables.

Parameters:

location - name of existing file to open.

fill - if true, the data is first written with fill values.

Throws:

java.io.IOException

createNew

public static NetcdfFileWriteable createNew(java.lang.String location)

Create a new Netcdf file, with fill mode true.

Parameters:

location - name of new file to open; if it exists, will overwrite it.

createNew

public static NetcdfFileWriteable createNew(java.lang.String location,
                                            boolean fill)

Create a new Netcdf file, put it into define mode. Make calls to addXXX(), then when all objects are added, call create(). You cannot read or write data until create() is called.

Parameters:

location - name of new file to open; if it exists, will overwrite it.

fill - if true, the data is first written with fill values. Leave false if you expect to write all data values, set to true if you want to be sure that unwritten data values have the fill value in it. (default is false)

setName

public void setName(java.lang.String filename)

Deprecated. use NetcdfFileWriteable(String filename);

Set the filename of a new file to be created: call before calling create().

Parameters:

filename - name of new file to create.

setFill

public void setFill(boolean fill)

Deprecated. use openExisting(String filename, boolean fill) or createNew(String filename, boolean fill)

Set the fill flag: call before calling create(). If true, the data is first written with fill values. Default is fill = false. Leave false if you expect to write all data values, set to true if you want to be sure that unwritten data values have the fill value in it.

Parameters:

fill - set fill mode true or false

addDimension

public Dimension addDimension(java.lang.String dimName,
                              int length)

Add a Dimension to the file. Must be in define mode.

Parameters:

dimName - name of dimension

length - size of dimension.

Returns:

the created dimension

addDimension

public Dimension addDimension(java.lang.String dimName,
                              int length,
                              boolean isShared,
                              boolean isUnlimited,
                              boolean isVariableLength)

Add a Dimension to the file. Must be in define mode.

Parameters:

dimName - name of dimension

length - size of dimension.

isShared - if dimension is shared

isUnlimited - if dimension is unlimited

isVariableLength - if dimension is variable length

Returns:

the created dimension

addUnlimitedDimension

public Dimension addUnlimitedDimension(java.lang.String dimName,
                                       int length)

Add an Uunlimited Dimension to the file. Must be in define mode.

Parameters:

dimName - name of unlimited dimension

Returns:

the created dimension

addGlobalAttribute

public void addGlobalAttribute(java.lang.String name,
                               java.lang.String value)

Add a Global attribute of type String to the file. Must be in define mode.

Parameters:

name - name of attribute.

value - value of atribute.

addGlobalAttribute

public void addGlobalAttribute(java.lang.String name,
                               java.lang.Number value)

Add a Global attribute of type Number to the file. Must be in define mode.

Parameters:

name - name of attribute.

value - must be of type Float, Double, Integer, Short or Byte

addGlobalAttribute

public void addGlobalAttribute(java.lang.String name,
                               Array values)

Add a Global attribute of type Array to the file. Must be in define mode.

Parameters:

name - name of attribute.

values - Array of values

addVariable

public void addVariable(java.lang.String varName,
                        java.lang.Class componentType,
                        Dimension[] dims)

Deprecated. use addVariable(String varName, DataType dataType, ArrayList dims);

Add a variable to the file. Must be in define mode.

Parameters:

varName - name of Variable, must be unique with the file.

componentType - type of underlying element: String, double or Double, etc.

dims - array of Dimensions for the variable, must already have been added.

addVariable

public void addVariable(java.lang.String varName,
                        DataType dataType,
                        Dimension[] dims)

Add a variable to the file. Must be in define mode.

Parameters:

varName - name of Variable, must be unique with the file.

dataType - type of underlying element

dims - array of Dimensions for the variable, must already have been added. Use an array of length 0 for a scalar variable.

addVariable

public void addVariable(java.lang.String varName,
                        DataType dataType,
                        java.util.List dims)

Add a variable to the file. Must be in define mode.

Parameters:

varName - name of Variable, must be unique with the file.

dataType - type of underlying element

dims - list of Dimensions for the variable, must already have been added. Use a list of length 0 for a scalar variable.

addVariableAttribute

public void addVariableAttribute(java.lang.String varName,
                                 Attribute att)

Add an attribute to the named Variable. Must be in define mode.

Parameters:

varName - name of variable. must already have been added to the file.

att - Attribute to add.

addVariableAttribute

public void addVariableAttribute(java.lang.String varName,
                                 java.lang.String attName,
                                 java.lang.String value)

Add an attribute of type String to the named Variable. Must be in define mode.

Parameters:

varName - name of variable. must already have been added to the file.

attName - name of attribute.

value - String value of atribute.

addVariableAttribute

public void addVariableAttribute(java.lang.String varName,
                                 java.lang.String attName,
                                 java.lang.Number value)

Add an attribute of type Number to the named Variable. Must be in define mode.

Parameters:

varName - name of attribute. IllegalArgumentException if not valid name.

attName - name of attribute.

value - must be of type Float, Double, Integer, Short or Byte

addVariableAttribute

public void addVariableAttribute(java.lang.String varName,
                                 java.lang.String attName,
                                 Array value)

Add an attribute of type Array to the named Variable. Must be in define mode.

Parameters:

varName - name of attribute. IllegalArgumentException if not valid name.

attName - name of attribute.

value - Array of valkues

create

public void create()
            throws java.io.IOException

After you have added all of the Dimensions, Variables, and Attributes, call create() to actually create the file. You must be in define mode. After this call, you are no longer in define mode, and cannot return to it.

Throws:

java.io.IOException

write

public void write(java.lang.String varName,
                  Array values)
           throws java.io.IOException,
                  InvalidRangeException

Write data to the named variable, origin assumed to be 0. Must not be in define mode.

Parameters:

varName - name of variable. IllegalArgumentException if variable name does not exist.

values - write this array; must be same type and rank as Variable

Throws:

java.io.IOException

InvalidRangeException

write

public void write(java.lang.String varName,
                  int[] origin,
                  Array values)
           throws java.io.IOException,
                  InvalidRangeException

Write data to the named variable. Must not be in define mode.

Parameters:

varName - name of variable. IllegalArgumentException if variable name does not exist.

origin - offset within the variable to start writing.

values - write this array; must be same type and rank as Variable

Throws:

java.io.IOException

InvalidRangeException

flush

public void flush()
           throws java.io.IOException

Flush anything written to disk.

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

close the file.

Overrides:

close in class NetcdfFile

Throws:

java.io.IOException