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

Field Summary

Fields inherited from class ucar.nc2.NetcdfFile

addedRecordStructure, cacheName, cacheState, dimensions, gattributes, id, isClosed, location, rootGroup, spi, title, variables

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(Attribute att) Add a Global attribute 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.
Variable	addStringVariable(java.lang.String varName, java.util.List dims, int max_strlen) Add a variable with DataType = String to the file.
Dimension	addUnlimitedDimension(java.lang.String dimName) Add an unlimited Dimension to the file.
Variable	addVariable(java.lang.String varName, java.lang.Class componentType, Dimension[] dims) Deprecated. use addVariable(String varName, DataType dataType, ArrayList dims);
Variable	addVariable(java.lang.String varName, DataType dataType, Dimension[] dims) Add a variable to the file.
Variable	addVariable(java.lang.String varName, DataType dataType, java.util.List dims) Add a variable to the file.
Variable	addVariable(java.lang.String varName, DataType dataType, java.lang.String 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) Set the fill flag: call before calling create() or doing any data writing.
void	setLength(long size) Preallocate the file size, for efficiency.
void	setName(java.lang.String filename) Deprecated. use NetcdfFileWriteable(String filename);
void	updateAttribute(Variable v2, Attribute att) Update the value of an existing attribute.
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.
void	writeStringData(java.lang.String varName, Array values) Write String data to a CHAR variable, origin assumed to be 0.
void	writeStringData(java.lang.String varName, int[] origin, Array values) Write String data to a CHAR variable.

Methods inherited from class ucar.nc2.NetcdfFile

addAttribute, addDimension, addGroup, addMemberVariable, addRecordStructure, addVariable, addVariableAttribute, createValidNetcdfObjectName, empty, finalize, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findTopVariable, findVariable, finish, getCacheName, getCacheState, getDetailInfo, getDimensions, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getValidNetcdfObjectNamePattern, getVariables, hasRecordStructure, hasUnlimitedDimension, isClosed, isValidNetcdfObjectName, main, makeFullName, makeFullNameWithString, open, open, open, open, open, openInMemory, openInMemory, read, readArrays, readData, readMemberData, registerIOProvider, registerIOProvider, removeDimension, removeVariable, replaceDimension, replaceGroupVariables, replaceStructureMembers, setCacheName, setCacheState, setDebugFlags, setDebugOutputStream, setId, setLocation, setProperty, setTitle, sync, syncExtend, toString, toStringDebug, toStringEnd, toStringStart, writeCDL, writeNcML

Methods inherited from class java.lang.Object

clone, 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)

Set the fill flag: call before calling create() or doing any data writing. 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

setLength

public void setLength(long size)

Preallocate the file size, for efficiency. Must call before create() to have any affect.

Parameters:

size -

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)

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

Parameters:

dimName - name of unlimited dimension

Returns:

the created dimension

addGlobalAttribute

public void addGlobalAttribute(Attribute att)

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

Parameters:

att - the attribute.

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 Variable 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 Variable 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 Variable addVariable(java.lang.String varName,
                            DataType dataType,
                            java.lang.String 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 - names of Dimensions for the variable, blank seperated. Must already have been added. Use an empty string for a scalar variable.

addVariable

public Variable 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.

addStringVariable

public Variable addStringVariable(java.lang.String varName,
                                  java.util.List dims,
                                  int max_strlen)

Add a variable with DataType = String to the file. Must be in define mode. The variable will be stored in the file as a CHAR variable. A new dimension with name "varName_strlen" is automatically added, with length max_strlen.

Parameters:

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

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

max_strlen - maximum string length.

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

updateAttribute

public void updateAttribute(Variable v2,
                            Attribute att)
                     throws java.io.IOException

Update the value of an existing attribute. Attribute is found by name, which must match exactly. You cannot make an attribute longer, or change the number of values. For strings: truncate if longer, zero fill if shorter. Strings are padded to 4 byte boundaries, ok to use padding if it exists. For numerics: must have same number of values.

Parameters:

v2 - variable, or null for global attribute

att - replace with this value

Throws:

java.io.IOException

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

writeStringData

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

Write String data to a CHAR variable, origin assumed to be 0. Must not be in define mode.

Parameters:

varName - name of variable, must be of type CHAR.

values - write this array; must be ArrayObject of String

Throws:

java.io.IOException

InvalidRangeException

writeStringData

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

Write String data to a CHAR variable. Must not be in define mode.

Parameters:

varName - name of variable, must be of type CHAR.

origin - offset to start writing, ignore the strlen dimension.

values - write this array; must be ArrayObject of String

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 - if error closing