ucar.nc2

Class NetcdfFileWriteable

java.lang.Object

ucar.nc2.NetcdfFile

ucar.nc2.NetcdfFileWriteable

All Implemented Interfaces:

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

cache, cacheName, debugCompress, debugSPI, dimensions, gattributes, id, IOSP_MESSAGE_ADD_RECORD_STRUCTURE, IOSP_MESSAGE_CONVERT_RECORD_STRUCTURE, IOSP_MESSAGE_RANDOM_ACCESS_FILE, IOSP_MESSAGE_REMOVE_RECORD_STRUCTURE, location, reserved, reservedCdl, reservedSectionSpec, rootGroup, showRequest, spi, title, unlocked, variables

Constructor Summary

Constructors

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

Methods

Modifier and Type	Method and Description
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 shortName, 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 fullNameEsc, Array values) Write data to the named variable, origin assumed to be 0.
void	write(java.lang.String fullNameEsc, 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 fullNameEsc, 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, escapeNameCDL, escapeNameSectionSpec, findAttValueIgnoreCase, findDimension, findGlobalAttribute, findGlobalAttributeIgnoreCase, findGroup, findVariable, finish, getCacheName, getDetailInfo, getDetailInfo, getDimensions, getFileTypeVersion, getGlobalAttributes, getId, getIosp, getLocation, getRootGroup, getStructureIterator, getTitle, getUnlimitedDimension, getVariables, hasUnlimitedDimension, isUnlocked, main, makeFullName, makeFullName, makeFullNameEscaped, makeFullNameEscapedSectionSpec, makeFullNameWithString, makeRecordStructure, makeRootGroup, makeValidCdmObjectName, open, open, open, open, open, openInMemory, openInMemory, openInMemory, openInMemory, read, readArrays, readAttributeDouble, readAttributeInteger, readData, readSection, readToByteChannel, registerIOProvider, registerIOProvider, removeDimension, removeRecordStructure, removeVariable, sendIospMessage, setCacheName, setDebugFlags, setFileCache, setId, setImmutable, setLocation, setProperty, setTitle, showCached, showProxies, sync, syncExtend, toString, toStringDebug, toStringEnd, toStringStart, unescapeName, writeCDL, writeCDL, writeNcML, writeNcML

Methods inherited from class java.lang.Object

clone, equals, finalize, 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 shortName,
                   DataType dataType,
                   java.util.List<Dimension> dims)

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

Parameters:

shortName - 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 fullNameEsc,
         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:

fullNameEsc - 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 fullNameEsc,
         int[] origin,
         Array values)
           throws java.io.IOException,
                  InvalidRangeException

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

Parameters:

fullNameEsc - full, escaped 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 fullNameEsc,
                   int[] origin,
                   Array values)
                     throws java.io.IOException,
                            InvalidRangeException

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

Parameters:

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