org.gridfour.gvrs

Class GvrsFile

java.lang.Object

org.gridfour.gvrs.GvrsFile

All Implemented Interfaces:

Closeable, AutoCloseable

public class GvrsFile
extends Object
implements Closeable, AutoCloseable

Provides methods and data elements for managing raster data in a file.

A Caution Regarding Thread Safety

GvrsFile and its related classes are not thread safe. While a file may be opened on a read-only basis using multiple instances of GvrsFile, the individual objects implement state-variables and data caches that are not protected for concurrent access. Application requiring multi-threaded access to a single GvrsFile object must manage concurrency issues themselves.

Constructor Summary

Constructors

Constructor and Description
GvrsFile(File file, GvrsFileSpecification specification) Creates a new raster file using the specified file and specifications.
GvrsFile(File file, String access) Open an existing raster file for read or write access.
GvrsFile(GvrsFileSpecification specification) Constructs a raster store backed by a temporary file that will be deleted when the close() method is called or the program terminates successfully.
GvrsFile(int nRowsInRaster, int nColumnsInRaster, GvrsElementType elementType) Constructs a raster store backed by a temporary file that will be deleted when the close() method is called or the program terminates successfully.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the file and releases all associated resources.
void	deleteMetadata(String name, int recordID) Delete a metadata element from the file.
void	flush() Write any in-memory data to the file.
ICompressionDecoder	getCompressionDecoder(String name) Gets an instance of the compression decoder that matches the specified CODEC name, if any.
ICompressionEncoder	getCompressionEncoder(String name) Gets an instance of the compression encoder that matches the specified CODEC name, if any.
long	getCreationTimeMillis() Gets the time that the GVRS file was created..
GvrsElement	getElement(int index) Gets the GVRS element by index (order created).
GvrsElement	getElement(String name) Gets the GVRS element (if any) that matches the specified name.
List<GvrsElement>	getElements() Gets a list of all the elements that were specified for the GVRS file when it was created.
File	getFile() Gets a file reference to the file in which the data for this raster is stored.
long	getModificationTimeMillis() Gets the time that the content of the GVRS file was last modified.
GvrsFileSpecification	getSpecification() Gets a safe copy of the gvrs raster specification associated with this file.
UUID	getUUID() Gets the UUID assigned to this specification (and any GVRS files derived from it).
boolean	isClosed() Indicates whether the raster is closed.
boolean	isOpenedForWriting() Indicates whether the file is opened for writing.
double[]	mapCartesianToGrid(double x, double y) Deprecated.
double[]	mapGeographicToGrid(double latitude, double longitude) Deprecated.
GridPoint	mapGeographicToGridPoint(double latitude, double longitude) Map geographic coordinates to grid coordinates storing the row and column in an array in that order.
GridPoint	mapGeographicToGridPoint(IGeoPoint geoPoint) Map geographic coordinates to grid coordinates storing the row and column in an instance of the GridPoint class.
double[]	mapGridToCartesian(double row, double column) Deprecated.
double[]	mapGridToGeographic(double row, double column) Deprecated.
GeoPoint	mapGridToGeoPoint(double row, double column) Map grid coordinates to geographic coordinates storing the resulting latitude and longitude in an instance of GvrsGeoPoint.
ModelPoint	mapGridToModelPoint(double row, double column) Map grid coordinates to model coordinates storing the resulting x and y values in a GvrsModelPoint instance.
GridPoint	mapModelToGridPoint(double x, double y) Map model coordinates to grid coordinates storing the computed row and column in an instance of GvrsGridPoint.
GridPoint	mapModelToGridPoint(IModelPoint modelPoint) Maps a model point to a grid point.
List<GvrsMetadata>	readMetadata() Reads the complete set of metadata records stored in the file.
List<GvrsMetadata>	readMetadata(GvrsMnc gmConstant) Reads a set of metadata objects that match the name of the specified enumeration.If no such metadata objects exist, the resulting list will be empty.
List<GvrsMetadata>	readMetadata(String name) Reads a set of metadata objects that match the specified name from the GVRS file.
GvrsMetadata	readMetadata(String name, int recordID) Reads the unique metadata object identified by name and record ID from the GVRS file.
void	setMultiThreadingEnabled(boolean multiThreadingEnabled) Sets multi-threading enabled.
void	setTileCacheSize(GvrsCacheSize cacheSize) Sets the tile cache size to one of the standard sizes defined by the specified enumeration.
void	setTileCacheSize(int tileCacheSize) Sets the tile cache size.
void	summarize(PrintStream ps, boolean analyze) Scans the file and writes a summary of its content to the specified PrintStream.
boolean	wasFileDeletedOnClose() Indicates if the backing file associated with this instance was successfully deleted on close.
void	writeMetadata(GvrsMetadata metadata) Store a GvrsMetadata instance providing metadata in the file.
void	writeMetadata(GvrsMnc gmConstant, String content) A convenience method for storing a GVRS metadata object with string content.
void	writeMetadata(String name, String content) A convenience method for storing a GVRS metadata object with string content.

Methods inherited from class java.lang.Object

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

Constructor Detail

GvrsFile

public GvrsFile(GvrsFileSpecification specification)
         throws IOException

Constructs a raster store backed by a temporary file that will be deleted when the close() method is called or the program terminates successfully. Note that the Java Virtual Machine will not be able to remove the file in the event of improper termination.

Parameters:

specification - a valid specification

Throws:

IOException - when an unhandled I/O exception occurs.

GvrsFile

public GvrsFile(int nRowsInRaster,
                int nColumnsInRaster,
                GvrsElementType elementType)
         throws IOException

Constructs a raster store backed by a temporary file that will be deleted when the close() method is called or the program terminates successfully. Note that the Java Virtual Machine will not be able to remove the file in the event of improper termination.

Parameters:

nRowsInRaster - an integer value greater than zero

nColumnsInRaster - an integer value greater than zero

elementType - a valid instance

Throws:

IOException - when an unhandled I/O exception occurs.

GvrsFile

public GvrsFile(File file,
                GvrsFileSpecification specification)
         throws IOException

Creates a new raster file using the specified file and specifications. If the file reference points to an existing file, the old file will be deleted and replaced. The dimensions and structure of the raster file will be taken from the specification argument.

When a new instance of GvrsFile is constructed, the specification object will be copied. Therefore, any subsequent changes to the specification object supplied by the application will not affect the internal elements in the GvrsFile element.

Parameters:

file - a valid file reference giving the path to a new output file in a location with write access.

specification - a valid GVRS raster specification

Throws:

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

GvrsFile

public GvrsFile(File file,
                String access)
         throws IOException

Open an existing raster file for read or write access.

Only one application may write to a file at once. If the existing file was previously opened for writing and not properly closed, it may not be accessible.

Parameters:

file - a valid file

access - a valid access control following the general contract of the Java RandomAccessFile class (valid values, "r", "rw", etc.)

Throws:

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

Method Detail

getFile

public File getFile()

Gets a file reference to the file in which the data for this raster is stored.

Returns:

a valid file reference.

isClosed

public boolean isClosed()

Indicates whether the raster is closed.

Returns:

true if the file is closed; otherwise, false

flush

public void flush()
           throws IOException

Write any in-memory data to the file. This call is required to ensure that any data not yet written to the file is properly recorded.

Note that the close() method calls flush() before closing a file.

Throws:

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

close

public void close()
           throws IOException

Closes the file and releases all associated resources. If the file is open for writing, any data in the internal buffers will be written to the file before it is closed.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

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

wasFileDeletedOnClose

public boolean wasFileDeletedOnClose()

Indicates if the backing file associated with this instance was successfully deleted on close. This method will return true if and only if the file is configured to be deleted on close, the file has been closed, and the delete operation was successful.

Returns:

true if the file was deleted on close.

isOpenedForWriting

public boolean isOpenedForWriting()

Indicates whether the file is opened for writing.

Returns:

true if the file is accepting data for storage; otherwise, false.

summarize

public void summarize(PrintStream ps,
                      boolean analyze)

Scans the file and writes a summary of its content to the specified PrintStream.

The analyze option will allow an application to print a report of statistics related to data compression. This process requires accessing the content of tiles and may be somewhat time consuming.

Parameters:

ps - a valid print-stream

analyze - performs an analysis of compressed data

setTileCacheSize

public void setTileCacheSize(int tileCacheSize)
                      throws IOException

Sets the tile cache size. Tile cache can have a significant effect on both performance and memory use for raster file operations.

Parameters:

tileCacheSize - a positive integer greater than zero.

Throws:

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

setTileCacheSize

public void setTileCacheSize(GvrsCacheSize cacheSize)
                      throws IOException

Sets the tile cache size to one of the standard sizes defined by the specified enumeration. This method will attempt to set tile cache size in terms of the number of tiles that can fit within the memory limit specified by the GvrsCacheSize enumeration. the following lists the target number of tiles for each specification. If the enumeration specifies enough memory for these target values, they will be used. Otherwise, they will be limited by memory.

• Small 9 tiles.
• Medium Enough tiles to fill an entire row.
• Large Enough tiles to fill two rows.

In general, the Large size should be used when creating new data products. Size should be based on the anticipated pattern of access for the file.

If the sizes specified using the enumeration are inadequate for the needs of an application, an application can set the specific number of tiles in the cache by using the alternate version of this method.

Parameters:

cacheSize - a valid instance

Throws:

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

getSpecification

public GvrsFileSpecification getSpecification()

Gets a safe copy of the gvrs raster specification associated with this file.

Returns:

a valid instance.

mapGridToModelPoint

public ModelPoint mapGridToModelPoint(double row,
                                      double column)

Map grid coordinates to model coordinates storing the resulting x and y values in a GvrsModelPoint instance. If the row or column values are outside the ranges defined for those parameters, the resulting x and y values may be outside the bounds of the standard Cartesian coordinates.

The transformation performed by this method is based on the parameters established through a call to the setCartesianCoordinates{} method.

Parameters:

row - a row (may be a non-integral value)

column - a column (may be a non-integral value)

Returns:

a valid instance

mapModelToGridPoint

public GridPoint mapModelToGridPoint(double x,
                                     double y)

Map model coordinates to grid coordinates storing the computed row and column in an instance of GvrsGridPoint. If the x or y coordinate is outside the ranges defined for these parameters, the resulting rows and columns may be outside the range of the valid grid coordinates.

The transformation performed by this method is based on the parameters established through a call to the setCartesianCoordinates() method.

Parameters:

x - a valid floating-point coordinate

y - a valid floating-point coordinate

Returns:

an array giving row and column in that order; the results may be non-integral values.

mapModelToGridPoint

public GridPoint mapModelToGridPoint(IModelPoint modelPoint)

Maps a model point to a grid point. If the coordinates specified by the model point do not map to the domain of the grid coordinate system, this method will still compute grid values. Therefore, it is the responsibility of the calling application to perform whatever range checking is appropriate.

Parameters:

modelPoint - a valid instance

Returns:

a matching grid point.

mapGeographicToGridPoint

public GridPoint mapGeographicToGridPoint(double latitude,
                                          double longitude)

Map geographic coordinates to grid coordinates storing the row and column in an array in that order. If the latitude or longitude is outside the ranges defined for these parameters, the resulting rows and columns may be outside the range of the valid grid coordinates

The transformation performed by this method is based on the parameters established through a call to the setGeographicCoordinates{} method. Longitudes may be adjusted according to the bounds established by the specification and in recognition of the cyclic nature of longitude coordinates (i.e. 450 degrees is equivalent to 90 degrees, etc.).

Parameters:

latitude - a valid floating-point coordinate

longitude - a valid floating-point coordinate

Returns:

a valid instance.

mapGeographicToGridPoint

public GridPoint mapGeographicToGridPoint(IGeoPoint geoPoint)

Map geographic coordinates to grid coordinates storing the row and column in an instance of the GridPoint class. If the latitude or longitude is outside the ranges defined for these parameters, the resulting row and column may be outside the range of the valid grid coordinates

The transformation performed by this method is based on the parameters established through a call to the setGeographicCoordinates{} method. Longitudes may be adjusted according to the bounds established by the specification and in recognition of the cyclic nature of longitude coordinates (i.e. 450 degrees is equivalent to 90 degrees, etc.).

Parameters:

geoPoint - a valid instance.

Returns:

a valid instance of a GridPoint.

mapGridToGeoPoint

public GeoPoint mapGridToGeoPoint(double row,
                                  double column)

Map grid coordinates to geographic coordinates storing the resulting latitude and longitude in an instance of GvrsGeoPoint. If the specified row or column values are outside the ranges defined for those parameters, the resulting latitude and longitude values may be outside the bounds of the standard Geographic coordinates.

The transformation performed by this method is based on the parameters established through a call to the setCartesianCoordinates{} method.

Parameters:

row - the row coordinate (may be non-integral)

column - the column coordinate (may be non-integral)

Returns:

a valid instance.

readMetadata

public final List<GvrsMetadata> readMetadata()
                                      throws IOException

Reads the complete set of metadata records stored in the file.

Returns:

a valid, potentially empty, list instance.

Throws:

IOException - in the event of unrecoverable I/O exception

readMetadata

public final GvrsMetadata readMetadata(String name,
                                       int recordID)
                                throws IOException

Reads the unique metadata object identified by name and record ID from the GVRS file. If the file does not contain a matching object, a null reference is returned.

Parameters:

name - a valid string giving a GVRS identifier

recordID - the record ID for the specified metadata

Returns:

if found, a safe copy of the metadata from the GVRS file; if no match is found, a null.

Throws:

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

readMetadata

public List<GvrsMetadata> readMetadata(String name)
                                throws IOException

Reads a set of metadata objects that match the specified name from the GVRS file. If no such metadata objects exist, the resulting list will be empty. Because no record ID is specified, it is possible that the list may contain multiple entries.

Parameters:

name - a valid string giving a GVRS identifier

Returns:

a valid, potentially empty list.

Throws:

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

readMetadata

public List<GvrsMetadata> readMetadata(GvrsMnc gmConstant)
                                throws IOException

Reads a set of metadata objects that match the name of the specified enumeration.If no such metadata objects exist, the resulting list will be empty. Because no record ID is specified, it is possible that the list may contain multiple entries.

Parameters:

gmConstant - a valid, non-null enumeration instance

Returns:

a valid, potentially empty list

Throws:

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

writeMetadata

public final void writeMetadata(GvrsMetadata metadata)
                         throws IOException

Store a GvrsMetadata instance providing metadata in the file.

Parameters:

metadata - a valid instance

Throws:

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

writeMetadata

public void writeMetadata(String name,
                          String content)
                   throws IOException

A convenience method for storing a GVRS metadata object with string content.

Parameters:

name - a valid string conforming to the GVRS identifier syntax.

content - the string to be stored.

Throws:

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

writeMetadata

public void writeMetadata(GvrsMnc gmConstant,
                          String content)
                   throws IOException

A convenience method for storing a GVRS metadata object with string content. This method will interpret a metadata-constant. While it provides a more compact way of writing metadata, it requires that the constant specifies a string type.

Parameters:

gmConstant - valid instance.

content - the string to be stored.

Throws:

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

deleteMetadata

public void deleteMetadata(String name,
                           int recordID)
                    throws IOException

Delete a metadata element from the file. If no metadata element can be matched to the specified name and record ID, no action is performed.

Parameters:

name - The name of the metadata to be deleted.

recordID - The record ID of the metadata to be deleted.

Throws:

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

getElement

public GvrsElement getElement(String name)

Gets the GVRS element (if any) that matches the specified name. Note that element names are case sensitive. Note: There is one, and only one, element for each name in a GVRS file. So multiple calls to this method that use the same name will obtain the same object.

Parameters:

name - The name of the desired element.

Returns:

if matched, a valid instance; otherwise a null.

getElement

public GvrsElement getElement(int index)

Gets the GVRS element by index (order created).

Parameters:

index - A value of zero or greater

Returns:

if defined, a valid instance; otherwise a null.

getElements

public List<GvrsElement> getElements()

Gets a list of all the elements that were specified for the GVRS file when it was created.

Returns:

a valid, potentially empty list.

getUUID

public UUID getUUID()

Gets the UUID assigned to this specification (and any GVRS files derived from it). The UUID is an arbitrary value automatically assigned to the specification. Its intended use it to allow GVRS to correlate files of different types (such as the main GVRS file and its associated index file).

The UUID is established by the GvrsFile constructor when a GVRS file is first created. One set, it is never modified.

Internally, the UUID is an arbitrary set of 16 bytes. Non-Java language implementations in languages/environments that do not have built-in support for UUIDs are free to implement this feature as they see fit.

Returns:

a valid UUID

getModificationTimeMillis

public long getModificationTimeMillis()

Gets the time that the content of the GVRS file was last modified. Note that this value is based on the time of internal operations on a GVRS file and will not necessarily match the information obtained by operating on the underlying file using the Java API.

Returns:

a value in milliseconds from the epoch January 1, 1970.

getCreationTimeMillis

public long getCreationTimeMillis()

Gets the time that the GVRS file was created..

Returns:

a value in milliseconds from the epoch January 1, 1970.

mapCartesianToGrid

@Deprecated
public double[] mapCartesianToGrid(double x,
                                                double y)

Deprecated.

Map Cartesian coordinates to grid coordinates storing the row and column in an array in that order.

This method is deprecated. Please use mapModelToGridPoint() instead.

Parameters:

x - a valid floating-point coordinate

y - a valid floating-point coordinate

Returns:

an array giving row and column in that order; the results may be non-integral values.

mapGridToCartesian

@Deprecated
public double[] mapGridToCartesian(double row,
                                                double column)

Deprecated.

Map grid coordinates to Cartesian coordinates storing the resulting x and y values in an array in that order.

This method is deprecated. Please use mapGridToModelPoint() instead.

Parameters:

row - a row (may be a non-integral value)

column - a column (may be a non-integral value)

Returns:

a valid array giving the Cartesian x and y coordinates in that order.

mapGeographicToGrid

@Deprecated
public double[] mapGeographicToGrid(double latitude,
                                                 double longitude)

Deprecated.

Map geographic coordinates to grid coordinates storing the row and column in an array in that order.

This method is deprecated. Please use mapGeographicToGridPoint() instead.

Parameters:

latitude - a valid floating-point coordinate

longitude - a valid floating-point coordinate

Returns:

an array giving row and column in that order; the results may be non-integral values.

mapGridToGeographic

@Deprecated
public double[] mapGridToGeographic(double row,
                                                 double column)

Deprecated.

Map grid coordinates to Geographic coordinates storing the resulting latitude and longitude values in an array in that order.

This method is deprecated. Please use mapModelToGridPoint() instead.

Parameters:

row - the row coordinate (may be non-integral)

column - the column coordinate (may be non-integral)

Returns:

a valid array giving row and column in that order.

getCompressionEncoder

public ICompressionEncoder getCompressionEncoder(String name)

Gets an instance of the compression encoder that matches the specified CODEC name, if any. In practice, a GvrsFile object will create only one instance of a particular compression encoder. Thus multiple calls to this method will return the same instance of a compression encoder.

The purpose of this method is to provide encoder instances to application code to support operations such as statistics and analysis reporting, and post-compression logging. It may be particularly useful to developers implementing their own compression classes.

Parameters:

name - a valid, non-empty string.

Returns:

if matched, a valid instance; otherwise, a null

getCompressionDecoder

public ICompressionDecoder getCompressionDecoder(String name)

Gets an instance of the compression decoder that matches the specified CODEC name, if any. In practice, a GvrsFile object will create only one instance of a particular compression decoder. Thus multiple calls to this method will return the same instance of a compression decoder.

The purpose of this method is to provide decoder instances to application code to support operations such as statistics and analysis reporting, and post-compression logging. It may be particularly useful to developers implementing their own compression classes.

Parameters:

name - a valid, non-empty string.

Returns:

if matched, a valid instance; otherwise, a null

setMultiThreadingEnabled

public void setMultiThreadingEnabled(boolean multiThreadingEnabled)

Sets multi-threading enabled. At this time, multi-threaded processing is only supported in the compressing of data. If an application is not compressing data, this setting will be ignored.

Future development for the GVRS API may expand the use of multi-threaded processing.

Multi-threading can expedite processing, but is sometimes inconvenient when developing, profiling, or debugging an application. Multi-threaded applications may also consume more resources than single threaded processes. Therefore, the default setting for this class is to treat multi-threading as disabled.

Parameters:

multiThreadingEnabled - true if multiple threads are enabled; otherwise, false (default false).