ucar.nc2.iosp.netcdf3

Class N3iosp

java.lang.Object

ucar.nc2.iosp.AbstractIOServiceProvider

ucar.nc2.iosp.netcdf3.N3iosp

All Implemented Interfaces:

IOServiceProvider, IOServiceProviderWriter

Direct Known Subclasses:

N3raf

Deprecated.

do not use

@Deprecated
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.

See Also:

concrete class

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	debug Deprecated.
protected boolean	debugRead Deprecated.
protected boolean	debugRecord Deprecated.
protected boolean	debugSize Deprecated.
protected boolean	debugSPIO Deprecated.
protected boolean	fill Deprecated.
protected N3header	header Deprecated.
protected long	lastModified Deprecated.
static int	MAX_NUMRECS Deprecated. The maximum number of records is 2^32-1.
static long	MAX_VARSIZE Deprecated. 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 Deprecated.
static char	NC_FILL_CHAR Deprecated.
static double	NC_FILL_DOUBLE Deprecated.
static float	NC_FILL_FLOAT Deprecated.
static int	NC_FILL_INT Deprecated.
static long	NC_FILL_INT64 Deprecated.
static short	NC_FILL_SHORT Deprecated.
static java.lang.String	NC_FILL_STRING Deprecated.
static byte	NC_FILL_UBYTE Deprecated.
static int	NC_FILL_UINT Deprecated.
static long	NC_FILL_UINT64 Deprecated.
static short	NC_FILL_USHORT Deprecated.
protected boolean	readonly Deprecated.
protected boolean	showHeaderBytes Deprecated.
protected boolean	useRecordStructure Deprecated.

Fields inherited from class ucar.nc2.iosp.AbstractIOServiceProvider

location, ncfile, raf, rafOrder

Constructor Summary

Constructors

Constructor and Description
N3iosp() Deprecated.

Method Summary

Modifier and Type	Method and Description
protected abstract void	_create(RandomAccessFile raf) Deprecated.
protected abstract void	_open(RandomAccessFile raf) Deprecated.
int	appendStructureData(Structure s, StructureData sdata) Deprecated. Append a structureData along the unlimited dimension
void	close() Deprecated. Close the file.
void	create(java.lang.String filename, NetcdfFile ncfile, int extra, long preallocateSize, boolean largeFile) Deprecated. Create new file, populate it from the objects in ncfile.
static java.lang.String	createValidNetcdf3ObjectName(java.lang.String name) Deprecated. use makeValidNetcdfObjectName
protected void	fillNonRecordVariables() Deprecated.
protected void	fillRecordVariables(int recStart, int recEnd) Deprecated.
void	flush() Deprecated. Flush all data buffers to disk.
java.lang.String	getDetailInfo() Deprecated. Show debug / underlying implementation details
java.lang.String	getFileTypeDescription() Deprecated. Get a human-readable description for this file type.
java.lang.String	getFileTypeId() Deprecated. Get a unique id for this file type.
java.lang.String	getFileTypeVersion() Deprecated. Get the version of this file type.
static java.lang.Number	getFillValueDefault(DataType dtype) Deprecated.
static com.google.re2j.Pattern	getValidNetcdf3ObjectNamePattern() Deprecated. Valid Netcdf Object name as a regular expression.
boolean	isValidFile(RandomAccessFile raf) Deprecated. Check if this is a valid file for this IOServiceProvider.
static boolean	isValidNetcdf3ObjectName(java.lang.String name) Deprecated. use isValidNetcdfObjectName
static boolean	isValidNetcdfObjectName(java.lang.String name) Deprecated. Determine if the given name can be used for a NetCDF object, i.e.
static java.lang.String	makeValidNetcdf3ObjectName(java.lang.String name) Deprecated. use makeValidNetcdfObjectName
static java.lang.String	makeValidNetcdfObjectName(java.lang.String name) Deprecated. Convert a name to a legal netcdf-3 name.
void	open(RandomAccessFile raf, NetcdfFile ncfile, CancelTask cancelTask) Deprecated. Open existing file, and populate ncfile with it.
void	openForWriting(RandomAccessFile raf, NetcdfFile ncfile, CancelTask cancelTask) Deprecated. Open existing file and allow writing.
void	reacquire() Deprecated. Reacquire any resources like file handles Used when reactivating in cache.
protected abstract java.lang.Object	readData(Layout index, DataType dataType) Deprecated. Read data subset from file for a variable, create primitive array.
protected abstract long	readData(Layout index, DataType dataType, java.nio.channels.WritableByteChannel out) Deprecated.
Array	readData(Variable v2, Section section) Deprecated. Read data from a top level Variable and return a memory resident Array.
long	readToByteChannel(Variable v2, Section section, java.nio.channels.WritableByteChannel channel) Deprecated. Read data from a top level Variable and send data to a WritableByteChannel.
boolean	rewriteHeader(boolean largeFile) Deprecated. if theres room before data, rewrite header without moving the data.
java.lang.Object	sendIospMessage(java.lang.Object message) Deprecated. A way to communicate arbitrary information to and from an iosp.
void	setFill(boolean fill) Deprecated. Set the fill flag.
protected void	setNumrecs(int n) Deprecated.
static void	setProperty(java.lang.String name, java.lang.String value) Deprecated. Set a static property.
boolean	syncExtend() Deprecated. Extend the NetcdfFile if the underlying dataset has changed in a way that is compatible with the current metadata.
java.lang.String	toStringDebug(java.lang.Object o) Deprecated. Debug info for this object.
void	updateAttribute(Variable v2, Attribute att) Deprecated. Update the value of an existing attribute.
protected abstract void	writeData(Array aa, Layout index, DataType dataType) Deprecated. Write data subset to file for a variable, create primitive array.
void	writeData(Variable v2, Section section, Array values) Deprecated. Write data into a variable.

Methods inherited from class ucar.nc2.iosp.AbstractIOServiceProvider

build, buildFinish, getLastModified, getStructureIterator, isBuilder, readSection, readToOutputStream, release, setNetcdfFile, streamToByteChannel

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

build, buildFinish, getStructureIterator, isBuilder, readSection, readToOutputStream, release, streamToByteChannel

Field Detail

NC_FILL_BYTE

public static final byte NC_FILL_BYTE

Deprecated.

See Also:

Constant Field Values

NC_FILL_CHAR

public static final char NC_FILL_CHAR

Deprecated.

See Also:

Constant Field Values

NC_FILL_SHORT

public static final short NC_FILL_SHORT

Deprecated.

See Also:

Constant Field Values

NC_FILL_INT

public static final int NC_FILL_INT

Deprecated.

See Also:

Constant Field Values

NC_FILL_FLOAT

public static final float NC_FILL_FLOAT

Deprecated.

See Also:

Constant Field Values

NC_FILL_DOUBLE

public static final double NC_FILL_DOUBLE

Deprecated.

See Also:

Constant Field Values

NC_FILL_UBYTE

public static final byte NC_FILL_UBYTE

Deprecated.

See Also:

Constant Field Values

NC_FILL_USHORT

public static final short NC_FILL_USHORT

Deprecated.

See Also:

Constant Field Values

NC_FILL_UINT

public static final int NC_FILL_UINT

Deprecated.

See Also:

Constant Field Values

NC_FILL_INT64

public static final long NC_FILL_INT64

Deprecated.

See Also:

Constant Field Values

NC_FILL_UINT64

public static final long NC_FILL_UINT64

Deprecated.

See Also:

Constant Field Values

NC_FILL_STRING

public static final java.lang.String NC_FILL_STRING

Deprecated.

See Also:

Constant Field Values

MAX_VARSIZE

public static final long MAX_VARSIZE

Deprecated.

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

Deprecated.

The maximum number of records is 2^32-1.

See Also:

Constant Field Values

readonly

protected boolean readonly

Deprecated.

header

protected N3header header

Deprecated.

lastModified

protected long lastModified

Deprecated.

debug

protected boolean debug

Deprecated.

debugSize

protected boolean debugSize

Deprecated.

debugSPIO

protected boolean debugSPIO

Deprecated.

debugRecord

protected boolean debugRecord

Deprecated.

debugRead

protected boolean debugRead

Deprecated.

showHeaderBytes

protected boolean showHeaderBytes

Deprecated.

useRecordStructure

protected boolean useRecordStructure

Deprecated.

fill

protected boolean fill

Deprecated.

Constructor Detail

N3iosp

public N3iosp()

Deprecated.

Method Detail

getFillValueDefault

public static java.lang.Number getFillValueDefault(DataType dtype)

Deprecated.

setProperty

public static void setProperty(java.lang.String name,
                               java.lang.String value)

Deprecated.

Set a static property. Supported static properties:

• syncExtendOnly = "true" : assume all file changes are syncExtend only.

Parameters:

name - property name

value - property value

isValidNetcdfObjectName

public static boolean isValidNetcdfObjectName(java.lang.String name)

Deprecated.

Determine if the given name can be used for a NetCDF object, i.e. a Dimension, Attribute, or Variable. The allowed name syntax (in RE form) is:

 ([a-zA-Z0-9_]|{UTF8})([^\x00-\x1F\x7F/]|{UTF8})*
 

where UTF8 represents a multi-byte UTF-8 encoding. Also, no trailing spaces are permitted in names. We do not allow '/' because HDF5 does not permit slashes in names as slash is used as a group separator. If UTF-8 is supported, then a multi-byte UTF-8 character can occur anywhere within an identifier.

Parameters:

name - the name to validate.

Returns:

true if the name is valid.

makeValidNetcdfObjectName

public static java.lang.String makeValidNetcdfObjectName(java.lang.String name)

Deprecated.

Convert a name to a legal netcdf-3 name.

Parameters:

name - the name to convert.

Returns:

the converted name.

See Also:

isValidNetcdfObjectName(String)

makeValidNetcdf3ObjectName

public static java.lang.String makeValidNetcdf3ObjectName(java.lang.String name)

Deprecated. use makeValidNetcdfObjectName

isValidNetcdf3ObjectName

public static boolean isValidNetcdf3ObjectName(java.lang.String name)

Deprecated. use isValidNetcdfObjectName

Determine if the given name can be used for a Dimension, Attribute, or Variable name. Should match makeValidNetcdf3ObjectName.

Parameters:

name - test this.

Returns:

true if valid name.

getValidNetcdf3ObjectNamePattern

public static com.google.re2j.Pattern getValidNetcdf3ObjectNamePattern()

Deprecated.

Valid Netcdf Object name as a regular expression.

Returns:

regular expression pattern describing valid Netcdf Object names.

createValidNetcdf3ObjectName

public static java.lang.String createValidNetcdf3ObjectName(java.lang.String name)

Deprecated. use makeValidNetcdfObjectName

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 java.io.IOException

Deprecated.

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:

java.io.IOException - if read error

getDetailInfo

public java.lang.String getDetailInfo()

Deprecated.

Description copied from interface: IOServiceProvider

Show debug / underlying implementation details

Specified by:

getDetailInfo in interface IOServiceProvider

Overrides:

getDetailInfo in class AbstractIOServiceProvider

Returns:

debug info

openForWriting

public void openForWriting(RandomAccessFile raf,
                           NetcdfFile ncfile,
                           CancelTask cancelTask)
                    throws java.io.IOException

Deprecated.

Description copied from interface: IOServiceProviderWriter

Open existing file and allow writing. Netcdf-4 writing is general. Netcdf-3 writing is restricted to writing data into existing variables.

Specified by:

openForWriting in interface IOServiceProviderWriter

Parameters:

raf - the file to work on.

ncfile - add objects to this empty NetcdfFile

cancelTask - used to monitor user cancellation; may be null.

Throws:

java.io.IOException - if I/O error

open

public void open(RandomAccessFile raf,
                 NetcdfFile ncfile,
                 CancelTask cancelTask)
          throws java.io.IOException

Deprecated.

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:

java.io.IOException - if read error

setFill

public void setFill(boolean fill)

Deprecated.

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. Set to 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 java.io.IOException,
                      InvalidRangeException

Deprecated.

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:

java.io.IOException - if read error

InvalidRangeException - if invalid section

See Also:

Range

readToByteChannel

public long readToByteChannel(Variable v2,
                              Section section,
                              java.nio.channels.WritableByteChannel channel)
                       throws java.io.IOException,
                              InvalidRangeException

Deprecated.

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:

java.io.IOException - if read error

InvalidRangeException - if invalid section

create

public void create(java.lang.String filename,
                   NetcdfFile ncfile,
                   int extra,
                   long preallocateSize,
                   boolean largeFile)
            throws java.io.IOException

Deprecated.

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 everything but data 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:

java.io.IOException - if I/O error

rewriteHeader

public boolean rewriteHeader(boolean largeFile)
                      throws java.io.IOException

Deprecated.

Description copied from interface: IOServiceProviderWriter

if theres room before data, rewrite header without moving the data. netcdf3 only

Specified by:

rewriteHeader in interface IOServiceProviderWriter

Returns:

true if it worked

Throws:

java.io.IOException

writeData

public void writeData(Variable v2,
                      Section section,
                      Array values)
               throws java.io.IOException,
                      InvalidRangeException

Deprecated.

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:

java.io.IOException - if I/O error

InvalidRangeException - if invalid section

appendStructureData

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

Deprecated.

Description copied from interface: IOServiceProviderWriter

Append a structureData along the unlimited dimension

Specified by:

appendStructureData in interface IOServiceProviderWriter

Parameters:

s - belongs to this structure

sdata - the stuctureData to append

Returns:

the recnum where it was written

Throws:

java.io.IOException

InvalidRangeException

setNumrecs

protected void setNumrecs(int n)
                   throws java.io.IOException,
                          InvalidRangeException

Deprecated.

Throws:

java.io.IOException

InvalidRangeException

updateAttribute

public void updateAttribute(Variable v2,
                            Attribute att)
                     throws java.io.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.

Specified by:

updateAttribute in interface IOServiceProviderWriter

Parameters:

v2 - variable, or null for fglobal attribute

att - replace with this value

Throws:

java.io.IOException

fillNonRecordVariables

protected void fillNonRecordVariables()
                               throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

fillRecordVariables

protected void fillRecordVariables(int recStart,
                                   int recEnd)
                            throws java.io.IOException,
                                   InvalidRangeException

Deprecated.

Throws:

java.io.IOException

InvalidRangeException

syncExtend

public boolean syncExtend()
                   throws java.io.IOException

Deprecated.

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:

java.io.IOException - if a read error occured when accessing the underlying dataset.

flush

public void flush()
           throws java.io.IOException

Deprecated.

Description copied from interface: IOServiceProviderWriter

Flush all data buffers to disk.

Specified by:

flush in interface IOServiceProviderWriter

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Deprecated.

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:

java.io.IOException - if read error

reacquire

public void reacquire()
               throws java.io.IOException

Deprecated.

Description copied from interface: IOServiceProvider

Reacquire any resources like file handles Used when reactivating in cache.

Specified by:

reacquire in interface IOServiceProvider

Overrides:

reacquire in class AbstractIOServiceProvider

Throws:

java.io.IOException

toStringDebug

public java.lang.String toStringDebug(java.lang.Object o)

Deprecated.

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 java.lang.Object sendIospMessage(java.lang.Object message)

Deprecated.

Description copied from interface: IOServiceProvider

A way to communicate arbitrary information to and from an iosp.

Specified by:

sendIospMessage in interface IOServiceProvider

Overrides:

sendIospMessage in class AbstractIOServiceProvider

Parameters:

message - opaque message sent to the IOSP object when its opened (not when isValidFile() is called)

Returns:

opaque Object, may be null.

getFileTypeId

public java.lang.String getFileTypeId()

Deprecated.

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:

"https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getFileTypeDescription

public java.lang.String getFileTypeDescription()

Deprecated.

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:

"https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

getFileTypeVersion

public java.lang.String getFileTypeVersion()

Deprecated.

Description copied from interface: IOServiceProvider

Get the version of this file type.

Specified by:

getFileTypeVersion in interface IOServiceProvider

Overrides:

getFileTypeVersion in class AbstractIOServiceProvider

Returns:

version of the file type

See Also:

"https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

readData

protected abstract java.lang.Object readData(Layout index,
                                             DataType dataType)
                                      throws java.io.IOException

Deprecated.

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:

java.io.IOException - on error

readData

protected abstract long readData(Layout index,
                                 DataType dataType,
                                 java.nio.channels.WritableByteChannel out)
                          throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

writeData

protected abstract void writeData(Array aa,
                                  Layout index,
                                  DataType dataType)
                           throws java.io.IOException

Deprecated.

Write data subset to file for a variable, create primitive array.

Parameters:

aa - write data from this Array.

index - handles skipping around in the file.

dataType - dataType of the variable

Throws:

java.io.IOException - on error

_open

protected abstract void _open(RandomAccessFile raf)

Deprecated.

_create

protected abstract void _create(RandomAccessFile raf)

Deprecated.