ucar.nc2.write

Class NetcdfFormatWriter

java.lang.Object

ucar.nc2.write.NetcdfFormatWriter

All Implemented Interfaces:

Closeable, AutoCloseable

public class NetcdfFormatWriter
extends Object
implements Closeable

Creates new Netcdf 3/4 format files. Writes data to new or existing files.

LOOK in ver7, netcdf3 and netcdf4 will be seperate, so they can have different functionality.

 NetcdfFormatWriter.Builder writerb = NetcdfFormatWriter.createNewNetcdf3(testFile.getPath());
 writerb.addDimension(Dimension.builder().setName("vdim").setIsUnlimited(true).build());
 writerb.addVariable("v", DataType.BYTE, "vdim");
 try (NetcdfFormatWriter writer = writerb.build()) {
   writer.config().forVariable("v").withArray(dataArray).write();
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NetcdfFormatWriter.Builder<T extends NetcdfFormatWriter.Builder<T>>
class	NetcdfFormatWriter.WriteConfig Fluid API for writing.

Method Summary

Modifier and Type	Method and Description
void	abort() Abort writing to this file.
int	appendStructureData(Structure s, StructureData sdata) Write StructureData along the unlimited dimension.
int	appendStructureData(Structure s, StructureData sdata) Deprecated. use appendStructureData(Structure, ucar.array.StructureData)
static NetcdfFormatWriter.Builder<?>	builder() Obtain a mutable Builder to create or modify the file metadata.
long	calcSize() An estimate of the size of the file when written to disk.
void	close() Close the file.
NetcdfFormatWriter.WriteConfig	config() Obtain a WriteConfig to configure data writing.
static NetcdfFormatWriter.Builder<?>	createNewNetcdf3(String location) Create a new Netcdf3 file.
static NetcdfFormatWriter.Builder<?>	createNewNetcdf4(NetcdfFileFormat format, String location, Nc4Chunking chunker) Create a new Netcdf4 file.
static NetcdfFormatWriter.Builder<?>	createNewNetcdf4(String location) Create a new NetcdfFileFormat.NETCDF4 file, with default chunker.
Dimension	findDimension(String dimName) Find the named Dimension in the output file.
Attribute	findGlobalAttribute(String attName) Find the named global attribute in the output file.
Variable	findVariable(String fullNameEscaped) Find the named Variable in the output file.
NetcdfFileFormat	getFormat() The output file's format.
Group	getRootGroup() The output file's root group.
static NetcdfFormatWriter.Builder<?>	openExisting(String location) Open an existing Netcdf format file for writing data.
void	updateAttribute(Variable v2, Attribute att) Update the value of an existing attribute.
void	write(String varName, Array values) Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)
void	write(String varName, int[] origin, Array values) Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)
void	write(Variable v, Array values) Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)
void	write(Variable v, Index origin, Array<?> values) Write to Variable with an ucar.array.Array.
void	write(Variable v, int[] origin, Array values) Deprecated. use write(Variable, Index, ucar.array.Array)
void	writeStringData(Variable v, Index origin, String data) Write String value to a CHAR Variable.
void	writeStringDataToChar(Variable v, Array values) Deprecated. use writeStringData(Variable, Index, String)
void	writeStringDataToChar(Variable v, int[] origin, Array values) Deprecated. use writeStringData(Variable, Index, String)

Methods inherited from class java.lang.Object

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

Method Detail

createNewNetcdf3

public static NetcdfFormatWriter.Builder<?> createNewNetcdf3(String location)

Create a new Netcdf3 file.

Parameters:

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

createNewNetcdf4

public static NetcdfFormatWriter.Builder<?> createNewNetcdf4(String location)

Create a new NetcdfFileFormat.NETCDF4 file, with default chunker.

Parameters:

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

createNewNetcdf4

public static NetcdfFormatWriter.Builder<?> createNewNetcdf4(NetcdfFileFormat format,
                                                             String location,
                                                             @Nullable
                                                             Nc4Chunking chunker)

Create a new Netcdf4 file.

Parameters:

format - One of the netcdf-4 NetcdfFileFormat.

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

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

openExisting

public static NetcdfFormatWriter.Builder<?> openExisting(String location)
                                                  throws IOException

Open an existing Netcdf format file for writing data. Cannot add new objects, you can only read/write data to existing Variables. TODO: allow changes to Netcdf-4 format.

Parameters:

location - name of existing NetCDF file to open.

Returns:

existing file that can be written to

Throws:

IOException

getRootGroup

public Group getRootGroup()

The output file's root group.

getFormat

public NetcdfFileFormat getFormat()

The output file's format.

findVariable

@Nullable
public Variable findVariable(String fullNameEscaped)

Find the named Variable in the output file.

findDimension

@Nullable
public Dimension findDimension(String dimName)

Find the named Dimension in the output file.

findGlobalAttribute

@Nullable
public Attribute findGlobalAttribute(String attName)

Find the named global attribute in the output file.

calcSize

public long calcSize()

An estimate of the size of the file when written to disk. Ignores compression for netcdf4.

Returns:

estimated file size in bytes.

write

public void write(Variable v,
                  Index origin,
                  Array<?> values)
           throws IOException,
                  InvalidRangeException

Write to Variable with an ucar.array.Array.

Parameters:

v - variable to write to

origin - offset within the variable to start writing.

values - write this array; must have compatible type and shape with Variable

Throws:

IOException

InvalidRangeException

writeStringData

public void writeStringData(Variable v,
                            Index origin,
                            String data)
                     throws IOException,
                            InvalidRangeException

Write String value to a CHAR Variable. Truncated or zero extended as needed to fit into last dimension of v.

 Index index = Index.ofRank(v.getRank());
 writer.writeStringData(v, index, "This is the first string.");
 writer.writeStringData(v, index, "Shorty");
 writer.writeStringData(v, index, "This is too long so it will get truncated");
 

Parameters:

v - write to this variable, must be of type CHAR.

origin - offset within the variable to start writing.

data - The String to write.

Throws:

IOException

InvalidRangeException

appendStructureData

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

Write StructureData along the unlimited dimension.

Returns:

the recnum where it was written.

Throws:

IOException

InvalidRangeException

write

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

Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)

Write data to the given variable, origin assumed to be 0.

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

@Deprecated
public void write(String varName,
                               Array values)
                        throws IOException,
                               InvalidRangeException

Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)

Write data to the named variable, origin assumed to be 0.

Throws:

IOException

InvalidRangeException

write

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

Deprecated. use write(Variable, Index, ucar.array.Array)

Write data to the given variable.

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

write

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

Deprecated. use write(Variable, ucar.array.Index, ucar.array.Array)

Write data to the named variable.

Parameters:

varName - name of 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

writeStringDataToChar

@Deprecated
public void writeStringDataToChar(Variable v,
                                               Array values)
                                        throws IOException,
                                               InvalidRangeException

Deprecated. use writeStringData(Variable, Index, String)

Write String data to a CHAR variable, origin assumed to be 0.

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

writeStringDataToChar

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

Deprecated. use writeStringData(Variable, Index, String)

Write String data to a CHAR variable.

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

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

Deprecated. use appendStructureData(Structure, ucar.array.StructureData)

Throws:

IOException

InvalidRangeException

updateAttribute

public void updateAttribute(Variable v2,
                            Attribute att)
                     throws 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, in particular supporting point feature writing. 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

close

public void close()
           throws IOException

Close the file.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

abort

public void abort()
           throws IOException

Abort writing to this file. The file is closed.

Throws:

IOException

builder

public static NetcdfFormatWriter.Builder<?> builder()

Obtain a mutable Builder to create or modify the file metadata.

config

public NetcdfFormatWriter.WriteConfig config()

Obtain a WriteConfig to configure data writing.