NetcdfFileWriter (All javadoc for netcdf-java version 4.6.22-SNAPSHOT)

java.lang.Object
- ucar.nc2.NetcdfFileWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
public class NetcdfFileWriter
extends java.lang.Object
implements java.io.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
Since:

7/25/12

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NetcdfFileWriter.Version
The kinds of netcdf file that can be written.

Nested Classes
Modifier and Type	Class and Description
`static class`	`NetcdfFileWriter.Version` The kinds of netcdf file that can be written.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`NetcdfFileWriter(NetcdfFileWriter.Version version, java.lang.String location, boolean isExisting, Nc4Chunking chunker)` Open an existing or create a new Netcdf file

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`abort()` Abort writing to this file.
`Dimension`	`addDimension(Group g, java.lang.String dimName, int length)` Add a shared Dimension to the file.
`Dimension`	`addDimension(Group g, java.lang.String dimName, int length, boolean isShared, boolean isUnlimited, boolean isVariableLength)` Add a Dimension to the file.
`Group`	`addGroup(Group parent, java.lang.String name)` Add a Group to the file.
`Attribute`	`addGroupAttribute(Group g, Attribute att)` Add a Global attribute to the file.
`Structure`	`addRecordStructure()` For netcdf3 only, take all unlimited variables and make them into a structure.
`Variable`	`addStringVariable(Group g, java.lang.String shortName, java.util.List<Dimension> dims, int max_strlen)` Add a variable with DataType = String to the file.
`Variable`	`addStringVariable(Group g, Variable stringVar, java.util.List<Dimension> dims)` Add a variable with DataType = String to a netCDF-3 file.
`Structure`	`addStructure(Group g, Structure org, java.lang.String shortName, java.util.List<Dimension> dims)` Add a structure to the file (netcdf4 only).
`Variable`	`addStructureMember(Structure s, java.lang.String shortName, DataType dtype, java.lang.String dims)`
`EnumTypedef`	`addTypedef(Group g, EnumTypedef td)` Add a EnumTypedef to the file.
`Dimension`	`addUnlimitedDimension(java.lang.String dimName)` Add single unlimited dimension (classic model)
`Variable`	`addVariable(Group g, java.lang.String shortName, DataType dataType, java.util.List<Dimension> dims)` Add a variable to the file.
`Variable`	`addVariable(Group g, java.lang.String shortName, DataType dataType, java.lang.String dimString)` Add a variable to the file.
`Variable`	`addVariable(Group g, Structure parent, java.lang.String shortName, DataType dataType, java.util.List<Dimension> dims)` Add a variable to the file.
`boolean`	`addVariableAttribute(Variable v, Attribute att)` Add an attribute to the named Variable.
`int`	`appendStructureData(Structure s, StructureData sdata)`
`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 NetcdfFileWriter`	`createNew(NetcdfFileWriter.Version version, java.lang.String location)`
`static NetcdfFileWriter`	`createNew(NetcdfFileWriter.Version version, java.lang.String location, Nc4Chunking chunker)` Create a new Netcdf file, with fill mode true.
`Attribute`	`deleteGroupAttribute(Group g, java.lang.String attName)` Delete a group Attribute.
`Attribute`	`deleteVariableAttribute(Variable v, java.lang.String attName)` Delete a variable Attribute.
`Attribute`	`findGlobalAttribute(java.lang.String attName)`
`Variable`	`findVariable(java.lang.String fullNameEscaped)`
`void`	`flush()` Flush anything written to disk.
`NetcdfFile`	`getNetcdfFile()`
`NetcdfFileWriter.Version`	`getVersion()`
`boolean`	`hasDimension(Group g, java.lang.String dimName)`
`boolean`	`isDefineMode()` Is the file in define mode, which allows objects to be added and changed?
`static NetcdfFileWriter`	`openExisting(java.lang.String location)` Open an existing Netcdf file for writing data.
`Dimension`	`renameDimension(Group g, java.lang.String oldName, java.lang.String newName)` Rename a Dimension.
`Attribute`	`renameGlobalAttribute(Group g, java.lang.String oldName, java.lang.String newName)` Rename a group Attribute.
`Variable`	`renameVariable(java.lang.String oldName, java.lang.String newName)` Rename a Variable.
`Attribute`	`renameVariableAttribute(Variable v, 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.
`boolean`	`setRedefineMode(boolean redefineMode)` Set the redefine mode.
`void`	`updateAttribute(Variable v2, Attribute att)` Update the value of an existing attribute.
`void`	`write(Variable v, Array values)` Write data to the named variable, origin assumed to be 0.
`void`	`write(Variable v, int[] origin, Array values)` Write data to the named variable.
`void`	`writeStringData(Variable v, Array values)` Write String data to a CHAR variable, origin assumed to be 0.
`void`	`writeStringData(Variable v, int[] origin, Array values)` Write String data to a CHAR variable.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - NetcdfFileWriter
```
protected NetcdfFileWriter(NetcdfFileWriter.Version version,
                           java.lang.String location,
                           boolean isExisting,
                           Nc4Chunking chunker)
                    throws java.io.IOException
```
    Open an existing or create a new Netcdf file
    
    Parameters:
    
    version - which kind of file to write, if null, use netcdf3 (isExisting= false) else open file and figure out the version
    
    location - open a new file at this location
    
    isExisting - true if file already exists
    
    chunker - used only for netcdf4, or null for used only for netcdf4, or null for default chunking algorithm
    
    Throws:
    
    java.io.IOException - on I/O error
- Method Detail
  - openExisting
```
public static NetcdfFileWriter 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
  - createNew
```
public static NetcdfFileWriter createNew(NetcdfFileWriter.Version version,
                                         java.lang.String location)
                                  throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - createNew
```
public static NetcdfFileWriter createNew(NetcdfFileWriter.Version version,
                                         java.lang.String location,
                                         Nc4Chunking chunker)
                                  throws java.io.IOException
```
    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:
    
    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. 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)
```
    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)
```
    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)
```
    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()
```
    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()
```
  - getVersion
```
public NetcdfFileWriter.Version getVersion()
```
  - findVariable
```
public Variable findVariable(java.lang.String fullNameEscaped)
```
  - findGlobalAttribute
```
public Attribute findGlobalAttribute(java.lang.String attName)
```
  - addDimension
```
public Dimension addDimension(Group g,
                              java.lang.String dimName,
                              int length)
```
    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(java.lang.String dimName)
```
    Add single unlimited dimension (classic model)
    
    Parameters:
    
    dimName - name of dimension
    
    Returns:
    
    Dimension object that was added
  - addDimension
```
public Dimension addDimension(Group g,
                              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 LOOK what does it mean if false ??
    
    isUnlimited - if dimension is unlimited
    
    isVariableLength - if dimension is variable length
    
    Returns:
    
    the created dimension
  - hasDimension
```
public boolean hasDimension(Group g,
                            java.lang.String dimName)
```
  - renameDimension
```
public Dimension renameDimension(Group g,
                                 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
  - addGroup
```
public Group addGroup(Group parent,
                      java.lang.String name)
```
    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
  - addGroupAttribute
```
public Attribute addGroupAttribute(Group g,
                                   Attribute att)
```
    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)
```
    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
  - deleteGroupAttribute
```
public Attribute deleteGroupAttribute(Group g,
                                      java.lang.String attName)
```
    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(Group g,
                                       java.lang.String oldName,
                                       java.lang.String newName)
```
    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(Group g,
                            java.lang.String shortName,
                            DataType dataType,
                            java.lang.String dimString)
```
    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(Group g,
                            java.lang.String shortName,
                            DataType dataType,
                            java.util.List<Dimension> dims)
```
    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,
                            java.lang.String shortName,
                            DataType dataType,
                            java.util.List<Dimension> dims)
```
    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
  - addStructure
```
public Structure addStructure(Group g,
                              Structure org,
                              java.lang.String shortName,
                              java.util.List<Dimension> dims)
```
    Add a structure to the file (netcdf4 only). DO NOT USE YET
    
    Parameters:
    
    g - add to this group in the new file
    
    org - rent Structure (netcdf4 only), or null if not a member of a Structure
    
    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 vaiable that has been added
  - addStructureMember
```
public Variable addStructureMember(Structure s,
                                   java.lang.String shortName,
                                   DataType dtype,
                                   java.lang.String dims)
```
  - addStringVariable
```
public Variable addStringVariable(Group g,
                                  Variable stringVar,
                                  java.util.List<Dimension> dims)
```
    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,
                                  java.lang.String shortName,
                                  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:
    
    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(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 boolean addVariableAttribute(Variable v,
                                    Attribute att)
```
    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,
                                         java.lang.String attName)
```
    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
  - renameVariableAttribute
```
public Attribute renameVariableAttribute(Variable v,
                                         java.lang.String attName,
                                         java.lang.String newName)
```
    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 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. 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:
    
    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
  - addRecordStructure
```
public Structure addRecordStructure()
```
    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(Variable v,
                  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:
    
    v - variable to write to
    
    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(Variable v,
                  int[] origin,
                  Array values)
           throws java.io.IOException,
                  InvalidRangeException
```
    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:
    
    java.io.IOException - if I/O error
    
    InvalidRangeException - if values Array has illegal shape
  - writeStringData
```
public void writeStringData(Variable v,
                            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:
    
    v - variable to write to
    
    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(Variable v,
                            int[] origin,
                            Array values)
                     throws java.io.IOException,
                            InvalidRangeException
```
    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:
    
    java.io.IOException - if I/O error
    
    InvalidRangeException - if values Array has illegal shape
  - appendStructureData
```
public int appendStructureData(Structure s,
                               StructureData sdata)
                        throws java.io.IOException,
                               InvalidRangeException
```
    Throws:
    
    java.io.IOException
    
    InvalidRangeException
  - 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 java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Throws:
    
    java.io.IOException - if I/O error
  - abort
```
public void abort()
           throws java.io.IOException
```
    Abort writing to this file. The file is closed.
    
    Throws:
    
    java.io.IOException

Class NetcdfFileWriter

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

NetcdfFileWriter

Method Detail

openExisting

createNew

createNew

setFill

setLength

setLargeFile

setExtraHeaderBytes

isDefineMode

getNetcdfFile

getVersion

findVariable

findGlobalAttribute

addDimension

addUnlimitedDimension

addDimension

hasDimension

renameDimension

addGroup

addGroupAttribute

addTypedef

deleteGroupAttribute

renameGlobalAttribute

addVariable

addVariable

addVariable

addStructure

addStructureMember

addStringVariable

addStringVariable

renameVariable

addVariableAttribute

deleteVariableAttribute

renameVariableAttribute

updateAttribute

create

setRedefineMode

addRecordStructure

write

write

writeStringData

writeStringData

appendStructureData

flush

close

abort