ucar.nc2
Class NetcdfFileWriteable

java.lang.Object
  extended by ucar.nc2.NetcdfFile
      extended by ucar.nc2.NetcdfFileWriteable
All Implemented Interfaces:
ucar.nc2.util.cache.FileCacheable

public class NetcdfFileWriteable
extends NetcdfFile

Create/Write netCDF-3 formatted files.

When a file is first created, it is in is "define mode", where the header objects (Dimensions, Attributes and Variables) may be added, deleted and modified, but no data may be written. Once create() is called, you can no longer modify the header, but you can now write data. An existing file is opened in write mode.

If setRedefine(true) is called, the file goes into define mode, and header objects can be changed. When setRedefine(false) is called, the new header is written, and the old file data is copied to the new file. This can be quite costly.

Author:
caron
See Also:
NetcdfFile

Field Summary
 
Fields inherited from class ucar.nc2.NetcdfFile
IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE, reserved
 
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.
 Attribute addGlobalAttribute(Attribute att)
          Add a Global attribute to the file.
 Attribute addGlobalAttribute(java.lang.String name, Array values)
          Add a Global attribute of type Array to the file.
 Attribute addGlobalAttribute(java.lang.String name, java.lang.Number value)
          Add a Global attribute of type Number to the file.
 Attribute 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<Dimension> 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<Dimension> 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.
 Attribute deleteGlobalAttribute(java.lang.String attName)
          Delete a global Attribute.
 Attribute deleteVariableAttribute(java.lang.String varName, java.lang.String attName)
          Delete a variable Attribute.
 void flush()
          Flush anything written to disk.
 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.
 boolean isDefineMode()
          Is the file in define mode, which allows objects to be added and changed?
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.
 Dimension renameDimension(java.lang.String oldName, java.lang.String newName)
          Rename a Dimension.
 Attribute renameGlobalAttribute(java.lang.String oldName, java.lang.String newName)
          Rename a global Attribute.
 Variable renameVariable(java.lang.String oldName, java.lang.String newName)
          Rename a Variable.
 Attribute renameVariableAttribute(java.lang.String varName, java.lang.String attName, java.lang.String newName)
          Rename a variable Attribute.
 void setExtraHeaderBytes(int extraHeaderBytes)
          Set extra bytes to reserve in the header.
 void setFill(boolean fill)
          Set the fill flag: call before calling create() or doing any data writing.
 void setLargeFile(boolean isLargeFile)
          Set if this should be a "large file" (64-bit offset) format.
 void setLength(long size)
          Preallocate the file size, for efficiency.
 void setName(java.lang.String filename)
          Deprecated. use NetcdfFileWriteable.createNew(String filename);
 boolean setRedefineMode(boolean redefineMode)
          Set the redefine mode.
 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, addStringVariable, addVariable, addVariable, addVariableAttribute, canOpen, empty, escapeName, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findTopVariable, findVariable, finish, getCacheName, getDetailInfo, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, isUnlocked, main, open, open, open, open, open, openInMemory, openInMemory, openInMemory, read, readArrays, readAttributeDouble, readAttributeInteger, readSection, registerIOProvider, registerIOProvider, removeDimension, removeVariable, sendIospMessage, setDebugFlags, setFileCache, setId, setImmutable, setLocation, setProperty, setTitle, sync, syncExtend, toString, unescapeName, writeCDL, writeCDL, writeNcML, 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.

Parameters:
location - open a new file at this location
fill - set fill 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.

Parameters:
location - open an existing file at this location
Throws:
java.io.IOException - on read error
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.
Returns:
existing file that can be written to
Throws:
java.io.IOException - on I/O error

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. Setting fill = false is more efficient, use when you know you will write all data.

Parameters:
location - name of existing file to open.
fill - if true, the data is first written with fill values.
Returns:
existing file that can be written to
Throws:
java.io.IOException - on I/O error

createNew

public static NetcdfFileWriteable createNew(java.lang.String location)
                                     throws java.io.IOException
Create a new Netcdf file, with fill mode true.

Parameters:
location - name of new file to open; if it exists, will overwrite it.
Returns:
new file that can be written to
Throws:
java.io.IOException - on I/O error

createNew

public static NetcdfFileWriteable createNew(java.lang.String location,
                                            boolean fill)
                                     throws java.io.IOException
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. Setting fill = false is more efficient, use when you know you will write all data.

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)
Returns:
new file that can be written to
Throws:
java.io.IOException - on I/O error

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 be in define mode Must call before create() to have any affect.

Parameters:
size - if set to > 0, set length of file to this upon creation - this (usually) pre-allocates contiguous storage.

setLargeFile

public void setLargeFile(boolean isLargeFile)
Set if this should be a "large file" (64-bit offset) format. Must be in define mode

Parameters:
isLargeFile - true if large file

setExtraHeaderBytes

public void setExtraHeaderBytes(int extraHeaderBytes)
Set extra bytes to reserve in the header. This can prevent rewriting the entire file on redefine. Must be in define mode

Parameters:
extraHeaderBytes - # bytes extra for the header

isDefineMode

public boolean isDefineMode()
Is the file in define mode, which allows objects to be added and changed?

Returns:
true if the file in define mode

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

renameDimension

public Dimension renameDimension(java.lang.String oldName,
                                 java.lang.String newName)
Rename a Dimension. Must be in define mode.

Parameters:
oldName - existing dimension has this name
newName - rename to this
Returns:
renamed dimension, or null if not found

addGlobalAttribute

public Attribute addGlobalAttribute(Attribute att)
Add a Global attribute to the file. Must be in define mode.

Parameters:
att - the attribute.
Returns:
the created attribute

addGlobalAttribute

public Attribute 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.
Returns:
the created attribute

addGlobalAttribute

public Attribute 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
Returns:
the created attribute

addGlobalAttribute

public Attribute 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
Returns:
the created attribute

deleteGlobalAttribute

public Attribute deleteGlobalAttribute(java.lang.String attName)
Delete a global Attribute. Must be in define mode.

Parameters:
attName - existing Attribute has this name
Returns:
deleted Attribute, or null if not found

renameGlobalAttribute

public Attribute renameGlobalAttribute(java.lang.String oldName,
                                       java.lang.String newName)
Rename a global Attribute. Must be in define mode.

Parameters:
oldName - existing Attribute has this name
newName - rename to this
Returns:
renamed Attribute, or null if not found

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.
Returns:
the Variable that has been added

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.
Returns:
the Variable that has been added

addVariable

public Variable addVariable(java.lang.String varName,
                            DataType dataType,
                            java.util.List<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 - list of Dimensions for the variable, must already have been added. Use a list of length 0 for a scalar variable.
Returns:
the Variable that has been added

addStringVariable

public Variable addStringVariable(java.lang.String varName,
                                  java.util.List<Dimension> 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.
Returns:
the Variable that has been added

renameVariable

public Variable renameVariable(java.lang.String oldName,
                               java.lang.String newName)
Rename a Variable. Must be in define mode.

Parameters:
oldName - existing Variable has this name
newName - rename to this
Returns:
renamed Variable, or null if not found

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 variable. 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 variable. IllegalArgumentException if not valid name.
attName - name of attribute.
value - Array of valkues

deleteVariableAttribute

public Attribute deleteVariableAttribute(java.lang.String varName,
                                         java.lang.String attName)
Delete a variable Attribute. Must be in define mode.

Parameters:
varName - existing Variable name
attName - existing Attribute has this name
Returns:
deleted Attribute, or null if not found

renameVariableAttribute

public Attribute renameVariableAttribute(java.lang.String varName,
                                         java.lang.String attName,
                                         java.lang.String newName)
Rename a variable Attribute. Must be in define mode.

Parameters:
varName - existing Variable name
attName - existing Attribute has this name
newName - rename to this
Returns:
renamed Attribute, or null if not found

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 - if I/O error

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.

Throws:
java.io.IOException - if I/O error

setRedefineMode

public boolean setRedefineMode(boolean redefineMode)
                        throws java.io.IOException
Set the redefine mode. Designed to emulate nc_redef (redefineMode = true) and nc_enddef (redefineMode = false)

Parameters:
redefineMode - start or end define mode
Returns:
true if it had to rewrite the entire file, false if it wrote the header in place
Throws:
java.io.IOException - on read/write error

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 - if I/O error
InvalidRangeException - if values Array has illegal shape

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 - if I/O error
InvalidRangeException - if values Array has illegal shape

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 - if I/O error
InvalidRangeException - if values Array has illegal shape

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 - if I/O error
InvalidRangeException - if values Array has illegal shape

flush

public void flush()
           throws java.io.IOException
Flush anything written to disk.

Throws:
java.io.IOException - if I/O error

close

public void close()
           throws java.io.IOException
close the file.

Specified by:
close in interface ucar.nc2.util.cache.FileCacheable
Overrides:
close in class NetcdfFile
Throws:
java.io.IOException - if I/O error

getFileTypeId

public java.lang.String getFileTypeId()
Description copied from class: NetcdfFile
Get the file type id for the underlying data source.

Overrides:
getFileTypeId in class NetcdfFile
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()
Description copied from class: NetcdfFile
Get a human-readable description for this file type.

Overrides:
getFileTypeDescription in class NetcdfFile
Returns:
description of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

setName

public void setName(java.lang.String filename)
Deprecated. use NetcdfFileWriteable.createNew(String filename);

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

Parameters:
filename - name of new file to create.

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.
Returns:
the Varible added