org.gridfour.gvrs

Class GvrsElement

java.lang.Object

org.gridfour.gvrs.GvrsElement

Direct Known Subclasses:

GvrsElementFloat, GvrsElementInt, GvrsElementIntCodedFloat, GvrsElementShort

public abstract class GvrsElement
extends Object

GVRS Element implementations provide the access point for reading from or writing to GVRS data stores. Elements are defined when the initial specification for a GVRS file is created. When a GVRS file is opened, one GvrsElement instance is created for each named element defined in the specification. The method getElements() in the GvrsFile class allows applications to obtain these instances and use them to exchange data with the file.

This abstract class serves as the base for a set of derived classes that are associated with each GVRS data type (Integer, Float, Short, and Integer-coded Float).

Method Summary

Modifier and Type	Method and Description
GvrsElementType	getDataType() Get the data type associated with this element.
String	getDescription() Gets the arbitrary description string.
String	getLabel() Gets the arbitrary label string.
String	getName() Gets the name associated with the element.
String	getUnitOfMeasure() Gets the arbitrary unit of measure string.
boolean	isContinuous() Indicates whether the data element can be treated as a continuous function over a surface or behaves in a non-continuous (discrete-valued) manner.
float[]	readBlock(int row, int column, int nRows, int nColumns) Reads a block (sub-grid) of floating-point values from the GVRS file based on the grid row, column, and block-size specifications.
int[]	readBlockInt(int row, int column, int nRows, int nColumns) Reads a block (sub-grid) of integer values from the GVRS file based on the grid row, column, and block-size specifications.
abstract float	readValue(GridPoint gridPoint) Reads a floating-point value from the GVRS raster file.
abstract float	readValue(int row, int column) Reads a floating-point value from the GVRS raster file.
abstract int	readValueInt(GridPoint gridPoint) Reads an integer value from the GVRS raster file.
abstract int	readValueInt(int row, int column) Read an integer value from the GvrsFile.
String	toString()
abstract void	writeValue(GridPoint gridPoint, float value) Write a floating-point value to the GVRS raster file.
abstract void	writeValue(int row, int col, float value) Write a floating-point value to the GVRS raster file.
abstract void	writeValueInt(GridPoint gridPoint, int value) Write an integer value in the GVRS raster file.
abstract void	writeValueInt(int row, int column, int value) Write an integer value in the GVRS raster file.

Methods inherited from class java.lang.Object

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

Method Detail

getName

public String getName()

Gets the name associated with the element.

Returns:

a valid, non-empty string

getDataType

public GvrsElementType getDataType()

Get the data type associated with this element.

Returns:

a valid instance

getDescription

public String getDescription()

Gets the arbitrary description string. Intended to allow applications to provide documentation for elements.

Returns:

a valid non-empty string, or a null if no description is to be supplied.

getLabel

public String getLabel()

Gets the arbitrary label string. Intended to provide applications with that ability to label elements using the full range of UTF-8 character sets. In particular, this method is useful for applications requiring specifications in non-western character sets.

Returns:

a valid non-empty string, or a null if no description is to be supplied.

getUnitOfMeasure

public String getUnitOfMeasure()

Gets the arbitrary unit of measure string. Intended to allow applications to provide documentation for elements.

Returns:

a valid non-empty string, or a null if no description is to be supplied.

readValueInt

public abstract int readValueInt(int row,
                                 int column)
                          throws IOException

Read an integer value from the GvrsFile. If no data exists for the specified row and column, the fill value will be returned.

Parameters:

row - a positive value in the range defined by the file specifications.

column - a positive value in the range defined by the file specifications.

Returns:

an integer value.

Throws:

IOException - in the event of a non-recoverable I/O exception.

readValueInt

public abstract int readValueInt(GridPoint gridPoint)
                          throws IOException

Reads an integer value from the GVRS raster file. If no data exists for the coordinates (row and column) specified by the GridPoint instance, the fill value will be returned.

Parameters:

gridPoint - a valid instance

Returns:

an integer value stored at the specified row and column

Throws:

IOException - in the event of a non-recoverable I/O exception.

writeValueInt

public abstract void writeValueInt(int row,
                                   int column,
                                   int value)
                            throws IOException

Write an integer value in the GVRS raster file. Because write operations are buffered, this data may be retained in memory for some time before actually being written to the file. However, any data lingering in memory will be recorded when the flush() or close() methods are called.

The value GvrsFileConstants.NULL_DATA_CODE is reserved for the representation of null data.

Parameters:

row - a positive value in the range defined by the file specifications.

column - a positive value in the range defined by the file specifications.

value - an integer value.

Throws:

IOException - in the event of an unrecoverable I/O exception.

writeValueInt

public abstract void writeValueInt(GridPoint gridPoint,
                                   int value)
                            throws IOException

Write an integer value in the GVRS raster file. Because write operations are buffered, this data may be retained in memory for some time before actually being written to the file. However, any data lingering in memory will be recorded when the flush() or close() methods are called.

The value GvrsFileConstants.NULL_DATA_CODE is reserved for the representation of null data.

Parameters:

gridPoint - a valid instance giving coordinates within the dimensions of the grid.

value - an integer value.

Throws:

IOException - in the event of an unrecoverable I/O exception.

readValue

public abstract float readValue(int row,
                                int column)
                         throws IOException

Reads a floating-point value from the GVRS raster file. If no data exists for the specified row and column, the fill value will be returned.

Parameters:

row - a positive value in the range defined by the file specifications.

column - a positive value in the range defined by the file specifications.

Returns:

an floating-point value or the fill value if there is no data stored at the specified row and column

Throws:

IOException - in the event of a non-recoverable I/O exception.

readValue

public abstract float readValue(GridPoint gridPoint)
                         throws IOException

Reads a floating-point value from the GVRS raster file. If no data exists for the coordinates (row and column) specified by the GridPoint instance, the fill value will be returned.

Parameters:

gridPoint - a valid instance

Returns:

an floating-point value or the fill value if there is no data stored at the specified row and column

Throws:

IOException - in the event of a non-recoverable I/O exception.

writeValue

public abstract void writeValue(int row,
                                int col,
                                float value)
                         throws IOException

Write a floating-point value to the GVRS raster file. Because write operations are buffered, this data may be retained in memory for some time before actually being written to the file. However, any data lingering in memory will be recorded when the flush() or close() methods are called.

The value Float.NaN is reserved for the representation of null data.

Parameters:

row - a positive value in the range defined by the file specifications.

col - a positive value in the range defined by the file specifications.

value - an floating-point value.

Throws:

IOException - in the event of an unrecoverable I/O exception.

writeValue

public abstract void writeValue(GridPoint gridPoint,
                                float value)
                         throws IOException

Write a floating-point value to the GVRS raster file. Because write operations are buffered, this data may be retained in memory for some time before actually being written to the file. However, any data lingering in memory will be recorded when the flush() or close() methods are called.

The value Float.NaN is reserved for the representation of null data.

Parameters:

gridPoint - a valid instance giving coordinates within the limits of the grid.

value - an floating-point value.

Throws:

IOException - in the event of an unrecoverable I/O exception.

readBlockInt

public int[] readBlockInt(int row,
                          int column,
                          int nRows,
                          int nColumns)
                   throws IOException

Reads a block (sub-grid) of integer values from the GVRS file based on the grid row, column, and block-size specifications. If successful, the return value from this method is an array giving a sub-grid of values in row-major order. The index into the array for a particular row and column within the sub-grid would be:

   index = row * nColumns + column
   where rows and columns are all numbered starting at zero.
 

Accessing data in a block is often more efficient that accessing data one grid-value-at-a-time.

Parameters:

row - the grid row index for the starting row of the block

column - the grid column index for the starting column of the block

nRows - the number of rows in the block to be retrieved

nColumns - the number of columns in the block to be retrieved

Returns:

if successful, a valid array of size nRow*nColumn in row-major order.

Throws:

IOException - in the event of an I/O error.

readBlock

public float[] readBlock(int row,
                         int column,
                         int nRows,
                         int nColumns)
                  throws IOException

Reads a block (sub-grid) of floating-point values from the GVRS file based on the grid row, column, and block-size specifications. If successful, the return value from this method is an array giving a sub-grid of values in row-major order. The index into the array for a particular row and column within the sub-grid would be:

   index = row * nColumns + column
   where rows and columns are all numbered starting at zero.
 

Accessing data in a block is often more efficient that accessing data one grid-value-at-a-time.

Parameters:

row - the grid row index for the starting row of the block

column - the grid column index for the starting column of the block

nRows - the number of rows in the block to be retrieved

nColumns - the number of columns in the block to be retrieved

Returns:

if successful, a valid array of size nRow*nColumn in row-major order.

Throws:

IOException - in the event of an I/O error.

isContinuous

public boolean isContinuous()

Indicates whether the data element can be treated as a continuous function over a surface or behaves in a non-continuous (discrete-valued) manner.

This method is intended to allow data providers to indicate to users how the information stored in this file can be used. Continuous data is suitable for interpolation, slope and tangent analysis, and similar applications. Discontinuous data cannot be interpolated and does not support calculus-based computations.

Returns:

true if the data can be treated as continuous; otherwise false.

toString

public String toString()

Overrides:

toString in class Object