ucar.nc2

Class NetcdfFileWriter

java.lang.Object

ucar.nc2.NetcdfFileWriter

All Implemented Interfaces:

Closeable, AutoCloseable

Deprecated.

TODO use ucar.nc2.writer.NetcdfFileWriter

public class NetcdfFileWriter
extends Object
implements Closeable

Writes Netcdf 3 or 4 formatted files to disk. To write new files:

1. createNew()
2. Add objects with addXXX() deleteXXX() renameXXX() calls
3. create file and write metadata with create()
4. write data with writeXXX()
5. close()

To write data to existing files:

1. openExisting()
2. write data with writeXXX()
3. close()

NetcdfFileWriter is a low level wrap of IOServiceProviderWriter, if possible better to use:

• ucar.nc2.FileWriter2()
• ucar.nc2.dt.grid.CFGridWriter
• ucar.nc2.ft.point.writer.CFPointWriter
• ucar.nc2.ft2.coverage.grid.CFGridCoverageWriter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NetcdfFileWriter.Version Deprecated. TODO use ucar.nc2.writer.NetcdfFileWriter

Method Summary

Modifier and Type	Method and Description
void	abort() Deprecated. Abort writing to this file.
Structure	addCopyOfStructure(Group g, Structure original, String shortName, List<Dimension> dims) Deprecated. Adds a copy of the specified structure to the file (netcdf4 only).
Dimension	addDimension(Group g, String dimName, int length) Deprecated. Add a shared Dimension to the file.
Dimension	addDimension(Group g, String dimName, int length, boolean isUnlimited, boolean isVariableLength) Deprecated. Add a shared Dimension to the file.
Dimension	addDimension(String dimName, int length) Deprecated.
Dimension	addDimension(String dimName, int length, boolean isUnlimited, boolean isVariableLength) Deprecated.
Attribute	addGlobalAttribute(Attribute att) Deprecated.
Attribute	addGlobalAttribute(String name, Number value) Deprecated.
Attribute	addGlobalAttribute(String name, String value) Deprecated.
Group	addGroup(Group parent, String name) Deprecated. Add a Group to the file.
Attribute	addGroupAttribute(Group g, Attribute att) Deprecated. Add a Global attribute to the file.
Structure	addRecordStructure() Deprecated. For netcdf3 only, take all unlimited variables and make them into a structure.
Variable	addStringVariable(Group g, String shortName, List<Dimension> dims, int max_strlen) Deprecated. Add a variable with DataType = String to the file.
Variable	addStringVariable(Group g, Variable stringVar, List<Dimension> dims) Deprecated. Add a variable with DataType = String to a netCDF-3 file.
Variable	addStructureMember(Structure s, String shortName, DataType dtype, String dims) Deprecated.
EnumTypedef	addTypedef(Group g, EnumTypedef td) Deprecated. Add a EnumTypedef to the file.
Dimension	addUnlimitedDimension(String dimName) Deprecated. Add single unlimited, shared dimension (classic model)
Variable	addVariable(Group g, String shortName, DataType dataType, List<Dimension> dims) Deprecated. Add a variable to the file.
Variable	addVariable(Group g, String shortName, DataType dataType, String dimString) Deprecated. Add a variable to the file.
Variable	addVariable(Group g, Structure parent, String shortName, DataType dataType, List<Dimension> dims) Deprecated. Add a variable to the file.
Variable	addVariable(String shortName, DataType dataType, List<Dimension> dims) Deprecated.
Variable	addVariable(String shortName, DataType dataType, String dimString) Deprecated.
boolean	addVariableAttribute(String varName, Attribute att) Deprecated.
boolean	addVariableAttribute(String varName, String name, Number value) Deprecated.
boolean	addVariableAttribute(String varName, String name, String value) Deprecated.
boolean	addVariableAttribute(Variable v, Attribute att) Deprecated. Add an attribute to the named Variable.
int	appendStructureData(Structure s, StructureData sdata) Deprecated.
void	close() Deprecated. close the file.
void	create() Deprecated. After you have added all of the Dimensions, Variables, and Attributes, call create() to actually create the file.
static NetcdfFileWriter	createNew(NetcdfFileWriter.Version version, String location) Deprecated.
static NetcdfFileWriter	createNew(NetcdfFileWriter.Version version, String location, ucar.nc2.write.Nc4Chunking chunker) Deprecated. Create a new Netcdf file, with fill mode true.
static NetcdfFileWriter	createNew(String location, boolean fill) Deprecated.
Attribute	deleteGlobalAttribute(String attName) Deprecated.
Attribute	deleteGroupAttribute(Group g, String attName) Deprecated. Delete a group Attribute.
Variable	deleteVariable(String fullName) Deprecated.
Attribute	deleteVariableAttribute(Variable v, String attName) Deprecated. Delete a variable Attribute.
Dimension	findDimension(String dimName) Deprecated.
Attribute	findGlobalAttribute(String attName) Deprecated.
Variable	findVariable(String fullNameEscaped) Deprecated.
void	flush() Deprecated. Flush anything written to disk.
NetcdfFile	getNetcdfFile() Deprecated.
NetcdfFileWriter.Version	getVersion() Deprecated.
boolean	hasDimension(Group g, String dimName) Deprecated.
boolean	isDefineMode() Deprecated. Is the file in define mode, which allows objects to be added and changed?
static NetcdfFileWriter	openExisting(String location) Deprecated. Open an existing Netcdf file for writing data.
Dimension	renameDimension(Group g, String oldName, String newName) Deprecated. Rename a Dimension.
Attribute	renameGlobalAttribute(String oldName, String newName) Deprecated.
Attribute	renameGroupAttribute(Group g, String oldName, String newName) Deprecated. Rename a group Attribute.
Variable	renameVariable(String oldName, String newName) Deprecated. Rename a Variable.
Attribute	renameVariableAttribute(Variable v, String attName, String newName) Deprecated. Rename a variable Attribute.
void	setExtraHeaderBytes(int extraHeaderBytes) Deprecated. Set extra bytes to reserve in the header.
void	setFill(boolean fill) Deprecated. Set the fill flag: call before calling create() or doing any data writing.
void	setLargeFile(boolean isLargeFile) Deprecated. Set if this should be a "large file" (64-bit offset) format.
void	setLength(long size) Deprecated. Preallocate the file size, for efficiency.
boolean	setRedefineMode(boolean redefineMode) Deprecated. Set the redefine mode.
void	updateAttribute(Variable v2, Attribute att) Deprecated. Update the value of an existing attribute.
void	write(String varname, Array values) Deprecated.
void	write(String varName, int[] origin, Array values) Deprecated.
void	write(Variable v, Array values) Deprecated. Write data to the named variable, origin assumed to be 0.
void	write(Variable v, int[] origin, Array values) Deprecated. Write data to the named variable.
void	writeStringData(Variable v, Array values) Deprecated. Write String data to a CHAR variable, origin assumed to be 0.
void	writeStringData(Variable v, int[] origin, Array values) Deprecated. Write String data to a CHAR variable.

Methods inherited from class java.lang.Object

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

Method Detail

openExisting

public static NetcdfFileWriter openExisting(String location)
                                     throws IOException

Deprecated.

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:

IOException - on I/O error

createNew

public static NetcdfFileWriter createNew(NetcdfFileWriter.Version version,
                                         String location)
                                  throws IOException

Deprecated.

Throws:

IOException

createNew

public static NetcdfFileWriter createNew(String location,
                                         boolean fill)
                                  throws IOException

Deprecated.

Throws:

IOException

createNew

public static NetcdfFileWriter createNew(NetcdfFileWriter.Version version,
                                         String location,
                                         ucar.nc2.write.Nc4Chunking chunker)
                                  throws IOException

Deprecated.

Create a new Netcdf file, with fill mode true.

Parameters:

version - netcdf-3 or 4

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

chunker - used only for netcdf4, or null for default chunking algorithm

Returns:

new NetcdfFileWriter

Throws:

IOException - on I/O error

setFill

public void setFill(boolean fill)

Deprecated.

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

Deprecated.

Preallocate the file size, for efficiency. Only used by netcdf-3. 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)

Deprecated.

Set if this should be a "large file" (64-bit offset) format. Only used by netcdf-3. Must be in define mode

Parameters:

isLargeFile - true if large file

setExtraHeaderBytes

public void setExtraHeaderBytes(int extraHeaderBytes)

Deprecated.

Set extra bytes to reserve in the header. Only used by netcdf-3. 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()

Deprecated.

Is the file in define mode, which allows objects to be added and changed?

Returns:

true if the file in define mode

getNetcdfFile

public NetcdfFile getNetcdfFile()

Deprecated.

getVersion

public NetcdfFileWriter.Version getVersion()

Deprecated.

findVariable

public Variable findVariable(String fullNameEscaped)

Deprecated.

findDimension

public Dimension findDimension(String dimName)

Deprecated.

findGlobalAttribute

public Attribute findGlobalAttribute(String attName)

Deprecated.

addDimension

public Dimension addDimension(String dimName,
                              int length)

Deprecated.

addDimension

public Dimension addDimension(Group g,
                              String dimName,
                              int length)

Deprecated.

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

Parameters:

dimName - name of dimension

length - size of dimension.

Returns:

the created dimension

addUnlimitedDimension

public Dimension addUnlimitedDimension(String dimName)

Deprecated.

Add single unlimited, shared dimension (classic model)

Parameters:

dimName - name of dimension

Returns:

Dimension object that was added

addDimension

public Dimension addDimension(String dimName,
                              int length,
                              boolean isUnlimited,
                              boolean isVariableLength)

Deprecated.

addDimension

public Dimension addDimension(Group g,
                              String dimName,
                              int length,
                              boolean isUnlimited,
                              boolean isVariableLength)

Deprecated.

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

Parameters:

dimName - name of dimension

length - size of dimension.

isUnlimited - if dimension is unlimited

isVariableLength - if dimension is variable length

Returns:

the created dimension

hasDimension

public boolean hasDimension(Group g,
                            String dimName)

Deprecated.

renameDimension

public Dimension renameDimension(Group g,
                                 String oldName,
                                 String newName)

Deprecated.

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

addGroup

public Group addGroup(Group parent,
                      String name)

Deprecated.

Add a Group to the file. Must be in define mode. If pass in null as the parent then the root group is returned and the name is ignored. This is how you get the root group. Note this is different from other uses of parent group.

Parameters:

parent - the parent of this group, if null then returns the root group.

name - the name of this group, unique within parent

Returns:

the created group

addGlobalAttribute

public Attribute addGlobalAttribute(Attribute att)

Deprecated.

addGlobalAttribute

public Attribute addGlobalAttribute(String name,
                                    String value)

Deprecated.

addGlobalAttribute

public Attribute addGlobalAttribute(String name,
                                    Number value)

Deprecated.

addGroupAttribute

public Attribute addGroupAttribute(Group g,
                                   Attribute att)

Deprecated.

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

Parameters:

g - the group to add to. if null, use root group

att - the attribute.

Returns:

the created attribute

addTypedef

public EnumTypedef addTypedef(Group g,
                              EnumTypedef td)

Deprecated.

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

Parameters:

g - the group to add to. if null, use root group

td - the EnumTypedef.

Returns:

the created attribute

deleteGlobalAttribute

public Attribute deleteGlobalAttribute(String attName)

Deprecated.

deleteGroupAttribute

public Attribute deleteGroupAttribute(Group g,
                                      String attName)

Deprecated.

Delete a group Attribute. Must be in define mode.

Parameters:

g - the group to add to. if null, use root group

attName - existing Attribute has this name

Returns:

deleted Attribute, or null if not found

renameGlobalAttribute

public Attribute renameGlobalAttribute(String oldName,
                                       String newName)

Deprecated.

renameGroupAttribute

public Attribute renameGroupAttribute(Group g,
                                      String oldName,
                                      String newName)

Deprecated.

Rename a group Attribute. Must be in define mode.

Parameters:

g - the group to add to. if null, use root group

oldName - existing Attribute has this name

newName - rename to this

Returns:

renamed Attribute, or null if not found

addVariable

public Variable addVariable(String shortName,
                            DataType dataType,
                            String dimString)

Deprecated.

addVariable

public Variable addVariable(Group g,
                            String shortName,
                            DataType dataType,
                            String dimString)

Deprecated.

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

Parameters:

g - the group to add to. if null, use root group

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

dataType - type of underlying element

dimString - names of Dimensions for the variable, blank separated. Must already have been added. Use an empty string for a scalar variable.

Returns:

the Variable that has been added

addVariable

public Variable addVariable(String shortName,
                            DataType dataType,
                            List<Dimension> dims)

Deprecated.

addVariable

public Variable addVariable(Group g,
                            String shortName,
                            DataType dataType,
                            List<Dimension> dims)

Deprecated.

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

Parameters:

g - add to this group in the new file

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

dataType - type of underlying element

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

Returns:

the Variable that has been added, or null if a Variable with shortName already exists in the group

addVariable

public Variable addVariable(Group g,
                            Structure parent,
                            String shortName,
                            DataType dataType,
                            List<Dimension> dims)

Deprecated.

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

Parameters:

g - add to this group in the new file

parent - parent Structure (netcdf4 only), or null if not a member of a Structure

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

dataType - type of underlying element

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

Returns:

the Variable that has been added

addCopyOfStructure

public Structure addCopyOfStructure(Group g,
                                    @Nonnull
                                    Structure original,
                                    String shortName,
                                    List<Dimension> dims)

Deprecated.

Adds a copy of the specified structure to the file (netcdf4 only). DO NOT USE YET

Parameters:

g - add to this group in the new file

original - the structure to make a copy of in the new file.

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

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

Returns:

the Structure variable that has been added

addStructureMember

public Variable addStructureMember(Structure s,
                                   String shortName,
                                   DataType dtype,
                                   String dims)

Deprecated.

addStringVariable

public Variable addStringVariable(Group g,
                                  Variable stringVar,
                                  List<Dimension> dims)

Deprecated.

Add a variable with DataType = String to a netCDF-3 file. Must be in define mode. The variable will be stored in the file as a CHAR variable. A new dimension with name "stringVar.getShortName()_strlen" is automatically added, with length max_strlen, as determined from the data contained in the stringVar.

Parameters:

g - add to this group in the new file

stringVar - string variable.

dims - list of Dimensions for the string variable.

Returns:

the CHAR variable generated from stringVar

addStringVariable

public Variable addStringVariable(Group g,
                                  String shortName,
                                  List<Dimension> dims,
                                  int max_strlen)

Deprecated.

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:

shortName - 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(String oldName,
                               String newName)

Deprecated.

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 boolean addVariableAttribute(String varName,
                                    String name,
                                    String value)

Deprecated.

addVariableAttribute

public boolean addVariableAttribute(String varName,
                                    String name,
                                    Number value)

Deprecated.

addVariableAttribute

public boolean addVariableAttribute(String varName,
                                    Attribute att)

Deprecated.

addVariableAttribute

public boolean addVariableAttribute(Variable v,
                                    Attribute att)

Deprecated.

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

Parameters:

v - Variable to add attribute to

att - Attribute to add.

Returns:

true if attribute was added, false if not allowed by CDM.

deleteVariableAttribute

public Attribute deleteVariableAttribute(Variable v,
                                         String attName)

Deprecated.

Delete a variable Attribute. Must be in define mode.

Parameters:

v - Variable to delete attribute to

attName - existing Attribute has this name

Returns:

deleted Attribute, or null if not found

deleteVariable

public Variable deleteVariable(String fullName)

Deprecated.

renameVariableAttribute

public Attribute renameVariableAttribute(Variable v,
                                         String attName,
                                         String newName)

Deprecated.

Rename a variable Attribute. Must be in define mode.

Parameters:

v - Variable to modify attribute

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 IOException

Deprecated.

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. This is really a netcdf-3 writing only. netcdf-4 attributes can be changed without rewriting.

Parameters:

v2 - variable, or null for global attribute

att - replace with this value

Throws:

IOException - if I/O error

create

public void create()
            throws IOException

Deprecated.

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:

IOException - if I/O error

setRedefineMode

public boolean setRedefineMode(boolean redefineMode)
                        throws IOException

Deprecated.

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:

IOException - on read/write error

addRecordStructure

public Structure addRecordStructure()

Deprecated.

For netcdf3 only, take all unlimited variables and make them into a structure.

Returns:

the record Structure, or null if not done.

write

public void write(String varname,
                  Array values)
           throws IOException,
                  InvalidRangeException

Deprecated.

Throws:

IOException

InvalidRangeException

write

public void write(Variable v,
                  Array values)
           throws IOException,
                  InvalidRangeException

Deprecated.

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

Parameters:

v - variable to write to

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

Throws:

IOException - if I/O error

InvalidRangeException - if values Array has illegal shape

write

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

Deprecated.

Throws:

IOException

InvalidRangeException

write

public void write(Variable v,
                  int[] origin,
                  Array values)
           throws IOException,
                  InvalidRangeException

Deprecated.

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

Parameters:

v - variable to write to

origin - offset within the variable to start writing.

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

Throws:

IOException - if I/O error

InvalidRangeException - if values Array has illegal shape

writeStringData

public void writeStringData(Variable v,
                            Array values)
                     throws IOException,
                            InvalidRangeException

Deprecated.

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

Parameters:

v - variable to write to

values - write this array; must be ArrayObject of String

Throws:

IOException - if I/O error

InvalidRangeException - if values Array has illegal shape

writeStringData

public void writeStringData(Variable v,
                            int[] origin,
                            Array values)
                     throws IOException,
                            InvalidRangeException

Deprecated.

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

Parameters:

v - variable to write to

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

values - write this array; must be ArrayObject of String

Throws:

IOException - if I/O error

InvalidRangeException - if values Array has illegal shape

appendStructureData

public int appendStructureData(Structure s,
                               StructureData sdata)
                        throws IOException,
                               InvalidRangeException

Deprecated.

Throws:

IOException

InvalidRangeException

flush

public void flush()
           throws IOException

Deprecated.

Flush anything written to disk.

Throws:

IOException - if I/O error

close

public void close()
           throws IOException

Deprecated.

close the file.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if I/O error

abort

public void abort()
           throws IOException

Deprecated.

Abort writing to this file. The file is closed.

Throws:

IOException