Package ucar.nc2

Class NetcdfFileWriter

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    @Deprecated
public class NetcdfFileWriter
extends Object
implements Closeable
    Deprecated.
    use ucar.nc2.write.NetcdfFormatWriter or ucar.nc2.write.NetcdfCopier
    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

    • Constructor Detail

      • NetcdfFileWriter

        protected NetcdfFileWriter​(NetcdfFileWriter.Version version,
                           String location,
                           boolean isExisting,
                           Nc4Chunking chunker)
                    throws IOException
        Deprecated.
        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:
        IOException - on I/O error

    • 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,
                                         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.

      • 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

      • 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​(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​(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

      • 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​(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​(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

      • flush

        public void flush()
           throws IOException
        Deprecated.
        Flush anything written to disk.
        Throws:
        IOException - if I/O error

      • abort

        public void abort()
           throws IOException
        Deprecated.
        Abort writing to this file. The file is closed.
        Throws:
        IOException