ucar.nc2.iosp.netcdf3
Class N3iosp

java.lang.Object
  extended by ucar.nc2.iosp.AbstractIOServiceProvider
      extended by ucar.nc2.iosp.netcdf3.N3iosp
All Implemented Interfaces:
IOServiceProvider, IOServiceProviderWriter
Direct Known Subclasses:
N3raf

public abstract class N3iosp
extends AbstractIOServiceProvider
implements IOServiceProviderWriter

IOServiceProvider implementation abstract base class to read/write "version 3" netcdf files. AKA "file format version 1" files.

Author:
caron
See Also:
concrete class

Field Summary
protected  boolean debug
           
protected  boolean debugRecord
           
protected  boolean debugSize
           
protected  boolean debugSPIO
           
protected  boolean debugSync
           
protected  HashMap dimHash
           
protected  boolean fill
           
static String FillValue
           
protected  N3header header
           
protected  long lastModified
           
static int MAX_NUMRECS
          The maximum number of records is 2^32-1.
static long MAX_VARSIZE
          Each fixed-size variable and the data for one record's worth of a single record variable are limited to a little less than 4 GiB.
static byte NC_FILL_BYTE
           
static char NC_FILL_CHAR
           
static double NC_FILL_DOUBLE
           
static float NC_FILL_FLOAT
           
static int NC_FILL_INT
           
static long NC_FILL_LONG
           
static short NC_FILL_SHORT
           
protected  NetcdfFile ncfile
           
protected  boolean readonly
           
protected  boolean showHeaderBytes
           
protected  boolean useRecordStructure
           
 
Fields inherited from class ucar.nc2.iosp.AbstractIOServiceProvider
raf
 
Constructor Summary
N3iosp()
           
 
Method Summary
protected abstract  void _create(RandomAccessFile raf)
           
protected abstract  void _open(RandomAccessFile raf)
           
 void close()
          Close the file.
protected static char[] convertByteToCharUTF(byte[] byteArray)
           
protected static byte[] convertCharToByteUTF(char[] from)
           
 void create(String filename, NetcdfFile ncfile, int extra, long preallocateSize, boolean largeFile)
          Create new file, populate it from the objects in ncfile.
static String createValidNetcdf3ObjectName(String name)
          Convert a name to a legal netcdf name.
protected  void fillNonRecordVariables()
           
protected  void fillRecordVariables(int recStart, int recEnd)
           
 void flush()
          Flush all data buffers to disk.
 String getDetailInfo()
          Show debug / underlying implementation details
 String getFileTypeDescription()
          Get a human-readable description for this file type.
 String getFileTypeId()
          Get a unique id for this file type.
static Pattern getValidNetcdf3ObjectNamePattern()
          Valid Netcdf Object name as a regular expression.
 boolean isValidFile(RandomAccessFile raf)
          Check if this is a valid file for this IOServiceProvider.
static boolean isValidNetcdf3ObjectName(String name)
          Determine if the given name can be used for a Dimension, Attribute, or Variable name.
static String makeValidNetcdfObjectName(String name)
          Convert a name to a legal netcdf-3 name.
static String makeValidNetcdfObjectNameOld(String name)
           
 void open(RandomAccessFile raf, NetcdfFile ncfile, CancelTask cancelTask)
          Open existing file, and populate ncfile with it.
protected abstract  Object readData(Layout index, DataType dataType)
          Read data subset from file for a variable, create primitive array.
protected abstract  long readData(Layout index, DataType dataType, WritableByteChannel out)
           
 Array readData(Variable v2, Section section)
          Read data from a top level Variable and return a memory resident Array.
 Array readNestedData(Variable v2, Section section)
           
 long readToByteChannel(Variable v2, Section section, WritableByteChannel channel)
          Read data from a top level Variable and send data to a WritableByteChannel.
 boolean rewriteHeader(boolean largeFile)
           
 Object sendIospMessage(Object message)
          A way to communicate arbitrary information to an iosp.
 void setFill(boolean fill)
          Set the fill flag.
protected  void setNumrecs(int n)
           
static void setProperty(String name, String value)
          Set a static property.
 boolean sync()
          Update the metadata in the NetcdfFile if the underlying dataset has changed.
 boolean syncExtend()
          Extend the NetcdfFile if the underlying dataset has changed in a way that is compatible with the current metadata.
 String toStringDebug(Object o)
          Debug info for this object.
 void updateAttribute(Variable v2, Attribute att)
          Update the value of an existing attribute.
protected abstract  void writeData(Array aa, Layout index, DataType dataType)
          Write data subset to file for a variable, create primitive array.
 void writeData(Variable v2, Section section, Array values)
          Write data into a variable.
 
Methods inherited from class ucar.nc2.iosp.AbstractIOServiceProvider
getFileTypeVersion, getStructureIterator, readSection
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface ucar.nc2.iosp.IOServiceProvider
getFileTypeVersion, getStructureIterator, readSection
 

Field Detail

NC_FILL_BYTE

public static final byte NC_FILL_BYTE
See Also:
Constant Field Values

NC_FILL_CHAR

public static final char NC_FILL_CHAR
See Also:
Constant Field Values

NC_FILL_SHORT

public static final short NC_FILL_SHORT
See Also:
Constant Field Values

NC_FILL_INT

public static final int NC_FILL_INT
See Also:
Constant Field Values

NC_FILL_LONG

public static final long NC_FILL_LONG
See Also:
Constant Field Values

NC_FILL_FLOAT

public static final float NC_FILL_FLOAT
See Also:
Constant Field Values

NC_FILL_DOUBLE

public static final double NC_FILL_DOUBLE
See Also:
Constant Field Values

FillValue

public static final String FillValue
See Also:
Constant Field Values

MAX_VARSIZE

public static final long MAX_VARSIZE
Each fixed-size variable and the data for one record's worth of a single record variable are limited to a little less than 4 GiB.

See Also:
Constant Field Values

MAX_NUMRECS

public static final int MAX_NUMRECS
The maximum number of records is 2^32-1.

See Also:
Constant Field Values

ncfile

protected NetcdfFile ncfile

readonly

protected boolean readonly

header

protected N3header header

lastModified

protected long lastModified

debug

protected boolean debug

debugSize

protected boolean debugSize

debugSPIO

protected boolean debugSPIO

debugRecord

protected boolean debugRecord

debugSync

protected boolean debugSync

showHeaderBytes

protected boolean showHeaderBytes

useRecordStructure

protected boolean useRecordStructure

fill

protected boolean fill

dimHash

protected HashMap dimHash
Constructor Detail

N3iosp

public N3iosp()
Method Detail

setProperty

public static void setProperty(String name,
                               String value)
Set a static property. Supported static properties:

Parameters:
name - property name
value - property value

makeValidNetcdfObjectName

public static String makeValidNetcdfObjectName(String name)
Convert a name to a legal netcdf-3 name. ([a-zA-Z0-9_]|{UTF8})([^\x00-\x1F\x7F/]|{UTF8})*

Parameters:
name - convert this name
Returns:
converted name

makeValidNetcdfObjectNameOld

public static String makeValidNetcdfObjectNameOld(String name)

isValidNetcdf3ObjectName

public static boolean isValidNetcdf3ObjectName(String name)
Determine if the given name can be used for a Dimension, Attribute, or Variable name.

Parameters:
name - test this.
Returns:
true if valid name.

getValidNetcdf3ObjectNamePattern

public static Pattern getValidNetcdf3ObjectNamePattern()
Valid Netcdf Object name as a regular expression.

Returns:
regular expression pattern describing valid Netcdf Object names.

createValidNetcdf3ObjectName

public static String createValidNetcdf3ObjectName(String name)
Convert a name to a legal netcdf name. From the user manual: "The names of dimensions, variables and attributes consist of arbitrary sequences of alphanumeric characters (as well as underscore '_' and hyphen '-'), beginning with a letter or underscore. (However names commencing with underscore are reserved for system use.) Case is significant in netCDF names."

Algorithm:

  1. leading character: if alpha or underscore, ok; if digit, prepend "N"; otherwise discard
  2. other characters: if space, change to underscore; other delete.

Parameters:
name - convert this name
Returns:
converted name

isValidFile

public boolean isValidFile(RandomAccessFile raf)
                    throws IOException
Description copied from interface: IOServiceProvider
Check if this is a valid file for this IOServiceProvider. You must make this method thread safe, ie dont keep any state.

Specified by:
isValidFile in interface IOServiceProvider
Parameters:
raf - RandomAccessFile
Returns:
true if valid.
Throws:
IOException - if read error

getDetailInfo

public String getDetailInfo()
Description copied from interface: IOServiceProvider
Show debug / underlying implementation details

Specified by:
getDetailInfo in interface IOServiceProvider
Overrides:
getDetailInfo in class AbstractIOServiceProvider
Returns:
debug info

open

public void open(RandomAccessFile raf,
                 NetcdfFile ncfile,
                 CancelTask cancelTask)
          throws IOException
Description copied from interface: IOServiceProvider
Open existing file, and populate ncfile with it. This method is only called by the NetcdfFile constructor on itself. The provided NetcdfFile object will be empty except for the location String and the IOServiceProvider associated with this NetcdfFile object.

Specified by:
open in interface IOServiceProvider
Overrides:
open in class AbstractIOServiceProvider
Parameters:
raf - the file to work on, it has already passed the isValidFile() test.
ncfile - add objects to this empty NetcdfFile
cancelTask - used to monitor user cancellation; may be null.
Throws:
IOException - if read error

setFill

public void setFill(boolean fill)
Description copied from interface: IOServiceProviderWriter
Set the fill flag. For new files, set in the create() method. This method is to set fill for existing files that you want to write. 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.

Specified by:
setFill in interface IOServiceProviderWriter
Parameters:
fill - set fill mode true or false

readData

public Array readData(Variable v2,
                      Section section)
               throws IOException,
                      InvalidRangeException
Description copied from interface: IOServiceProvider
Read data from a top level Variable and return a memory resident Array. This Array has the same element type as the Variable, and the requested shape.

Specified by:
readData in interface IOServiceProvider
Parameters:
v2 - a top-level Variable
section - the section of data to read. There must be a Range for each Dimension in the variable, in order. Note: no nulls allowed. IOSP may not modify.
Returns:
the requested data in a memory-resident Array
Throws:
IOException - if read error
InvalidRangeException - if invalid section
See Also:
Range

readNestedData

public Array readNestedData(Variable v2,
                            Section section)
                     throws IOException,
                            InvalidRangeException
Throws:
IOException
InvalidRangeException

readToByteChannel

public long readToByteChannel(Variable v2,
                              Section section,
                              WritableByteChannel channel)
                       throws IOException,
                              InvalidRangeException
Description copied from interface: IOServiceProvider
Read data from a top level Variable and send data to a WritableByteChannel. Must be in big-endian order.

Specified by:
readToByteChannel in interface IOServiceProvider
Overrides:
readToByteChannel in class AbstractIOServiceProvider
Parameters:
v2 - a top-level Variable
section - the section of data to read. There must be a Range for each Dimension in the variable, in order. Note: no nulls allowed. IOSP may not modify.
channel - write data to this WritableByteChannel
Returns:
the number of bytes written to the channel
Throws:
IOException - if read error
InvalidRangeException - if invalid section

convertByteToCharUTF

protected static char[] convertByteToCharUTF(byte[] byteArray)

convertCharToByteUTF

protected static byte[] convertCharToByteUTF(char[] from)

create

public void create(String filename,
                   NetcdfFile ncfile,
                   int extra,
                   long preallocateSize,
                   boolean largeFile)
            throws IOException
Description copied from interface: IOServiceProviderWriter
Create new file, populate it from the objects in ncfile.

Specified by:
create in interface IOServiceProviderWriter
Parameters:
filename - name of file to create.
ncfile - get dimensions, attributes, and variables from here.
extra - if > 0, pad header with extra bytes
preallocateSize - if > 0, set length of file to this upon creation - this (usually) pre-allocates contiguous storage.
largeFile - if want large file format
Throws:
IOException - if I/O error

rewriteHeader

public boolean rewriteHeader(boolean largeFile)
                      throws IOException
Specified by:
rewriteHeader in interface IOServiceProviderWriter
Throws:
IOException

writeData

public void writeData(Variable v2,
                      Section section,
                      Array values)
               throws IOException,
                      InvalidRangeException
Description copied from interface: IOServiceProviderWriter
Write data into a variable.

Specified by:
writeData in interface IOServiceProviderWriter
Parameters:
v2 - variable to write; must already exist.
section - the section of data to write. There must be a Range for each Dimension in the variable, in order. The shape must match the shape of values. The origin and stride indicate where the data is placed into the stored Variable array.
values - data to write. The shape must match section.getShape().
Throws:
IOException - if I/O error
InvalidRangeException - if invalid section

setNumrecs

protected void setNumrecs(int n)
                   throws IOException,
                          InvalidRangeException
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.

Specified by:
updateAttribute in interface IOServiceProviderWriter
Parameters:
v2 - variable, or null for fglobal attribute
att - replace with this value
Throws:
IOException

fillNonRecordVariables

protected void fillNonRecordVariables()
                               throws IOException
Throws:
IOException

fillRecordVariables

protected void fillRecordVariables(int recStart,
                                   int recEnd)
                            throws IOException,
                                   InvalidRangeException
Throws:
IOException
InvalidRangeException

syncExtend

public boolean syncExtend()
                   throws IOException
Description copied from interface: IOServiceProvider
Extend the NetcdfFile if the underlying dataset has changed in a way that is compatible with the current metadata. For example, if the unlimited dimension has grown.

Specified by:
syncExtend in interface IOServiceProvider
Overrides:
syncExtend in class AbstractIOServiceProvider
Returns:
true if the NetcdfFile was extended.
Throws:
IOException - if a read error occured when accessing the underlying dataset.

sync

public boolean sync()
             throws IOException
Description copied from interface: IOServiceProvider
Update the metadata in the NetcdfFile if the underlying dataset has changed.

Specified by:
sync in interface IOServiceProvider
Overrides:
sync in class AbstractIOServiceProvider
Returns:
true if the NetcdfFile was changed.
Throws:
IOException - if a read error occured when accessing the underlying dataset.

flush

public void flush()
           throws IOException
Description copied from interface: IOServiceProviderWriter
Flush all data buffers to disk.

Specified by:
flush in interface IOServiceProviderWriter
Throws:
IOException - if I/O error

close

public void close()
           throws IOException
Description copied from interface: IOServiceProvider
Close the file. It is the IOServiceProvider's job to close the file (even though it didnt open it), and to free any other resources it has used.

Specified by:
close in interface IOServiceProvider
Overrides:
close in class AbstractIOServiceProvider
Throws:
IOException - if read error

toStringDebug

public String toStringDebug(Object o)
Debug info for this object.

Specified by:
toStringDebug in interface IOServiceProvider
Overrides:
toStringDebug in class AbstractIOServiceProvider
Parameters:
o - which object
Returns:
debug info for this object

sendIospMessage

public Object sendIospMessage(Object message)
Description copied from interface: IOServiceProvider
A way to communicate arbitrary information to an iosp.

Specified by:
sendIospMessage in interface IOServiceProvider
Overrides:
sendIospMessage in class AbstractIOServiceProvider
Parameters:
message - opaque message.
Returns:
opaque return, may be null.

getFileTypeId

public String getFileTypeId()
Description copied from interface: IOServiceProvider
Get a unique id for this file type.

Specified by:
getFileTypeId in interface IOServiceProvider
Returns:
registered id of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getFileTypeDescription

public String getFileTypeDescription()
Description copied from interface: IOServiceProvider
Get a human-readable description for this file type.

Specified by:
getFileTypeDescription in interface IOServiceProvider
Returns:
description of the file type
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

readData

protected abstract Object readData(Layout index,
                                   DataType dataType)
                            throws IOException
Read data subset from file for a variable, create primitive array.

Parameters:
index - handles skipping around in the file.
dataType - dataType of the variable
Returns:
primitive array with data read in
Throws:
IOException - on error

readData

protected abstract long readData(Layout index,
                                 DataType dataType,
                                 WritableByteChannel out)
                          throws IOException
Throws:
IOException

writeData

protected abstract void writeData(Array aa,
                                  Layout index,
                                  DataType dataType)
                           throws IOException
Write data subset to file for a variable, create primitive array.

Parameters:
aa - write data in this Array.
index - handles skipping around in the file.
dataType - dataType of the variable
Throws:
IOException - on error

_open

protected abstract void _open(RandomAccessFile raf)
                       throws IOException
Throws:
IOException

_create

protected abstract void _create(RandomAccessFile raf)
                         throws IOException
Throws:
IOException


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.