appl.parallel.data.xulugridfile
Class XuluGridFile

java.lang.Object
  extended by appl.parallel.data.xulugridfile.XuluGridFile

public class XuluGridFile
extends Object

A XuluGridfile is a memory- and 2D-access optimized file format which can be used for parallel programming. All data is accessed on disk only (and not loaded into memory). For this the data is stored in a special uncompressed format.

The values are stored line by line in the GridFile. The result is, that every value is stored at a well known position in the file, so that the position of the value in the file can be calculated. Because of this it is not necessary to search the file for a value of a given coordinate.
If a partition is requested it is possible to read the data directly from the file.

The filename of the XuluGridFile must end with ".xgrid" The metadata of the gird is stored in a separate file with the same name in the same directory ending with ".xworld".

The XuluGridFile is buffered, it can handle Float, Double and Int values. To create a XuluGridFile you can use this constructor, or you can convert an existing Grid into the XuluGridFile format using the XuluGridFileConverter.

A monitor is used to guarantee that only one XuluGridFile is accessed at a time. This guarantees a high disk performance.

For use in the XuluPlatform you can use the XuluWritableGridFile, which implements the WritableGrid interface.

Author:
Dominik Appl

Field Summary
protected  RandomAccessFile gridFile
           
protected  RasterMetaData metaData
           
 
Constructor Summary
XuluGridFile(File file)
          Opens an existing gridfile in read/write mode.
XuluGridFile(File targetFile, RasterMetaData metaData)
          Creates a NEW File with the sample given as RasterMetaData
XuluGridFile(File file, String mode)
          Opens an existing Xulu Grid File.
XuluGridFile(WritableGrid grid, File output)
          Creates a new XuluGridFile out of an existing Writable Grid and opens it in read-write mode.
 
Method Summary
 void close()
          Closes all used Filehandles.
 RasterMetaData getMetaData()
           
 File getOutputFile()
           
 WritableGridPartition getPartitialGrid2D(Rectangle partitionBounds)
          Returns a partition of a WritableGrid as a WritableGridArray.
 int getRootID()
           
 WritableGrid getWholeGrid()
          gives back the whole grid as a WritableGridArray in memory!
static void readIntoGridFromXuluGridFile(WritableGrid grid, File input)
          Writes data out of a XuluGridFile into a WritableGrid.
 RasterMetaData readXuluGridWorldFile(File worldFile)
          The Xulu world file ist just a serialized RasterMetaData-Object!
 void setPartition(WritableGrid gridPartition, Rectangle partitionBounds)
          Overwrites the data at the location specified by the Rectangle with the given partition-data.
static void writeToXuluGridFile(WritableGrid grid, File output)
          Writes the given Grid to a XuluGridFile.
static void writeWorldFileForMetaData(File XuluGridFile, RasterMetaData meta)
          This File simply serializes the given appl.util.RasterMetaData Object to the given file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

gridFile

protected RandomAccessFile gridFile

metaData

protected RasterMetaData metaData
Constructor Detail

XuluGridFile

public XuluGridFile(File file,
                    String mode)
             throws FileNotFoundException,
                    XuluGridFileException
Opens an existing Xulu Grid File. The File must have the ending ".xgrid" and there must be a xuluGrid world file in the same directory with the ending ".xworld"

Parameters:
file - the filename to read from and write to
mode - the input mode as specified at RandomAccessFile.RandomAccessFile(java.lang.String, java.lang.String)

Value

Meaning

"r" Open for reading only. Invoking any of the write methods of the resulting object will cause an IOException to be thrown.
"rw" Open for reading and writing. If the file does not already exist then an attempt will be made to create it.
"rws" Open for reading and writing, as with "rw", and also require that every update to the file's content or metadata be written synchronously to the underlying storage device.
"rwd"   Open for reading and writing, as with "rw", and also require that every update to the file's content be written synchronously to the underlying storage device.
Throws:
FileNotFoundException
XuluGridFileException
See Also:
RandomAccessFile

XuluGridFile

public XuluGridFile(File file)
             throws FileNotFoundException,
                    XuluGridFileException
Opens an existing gridfile in read/write mode.

Parameters:
file - the existing XuluGridFile to be opened
Throws:
FileNotFoundException
XuluGridFileException

XuluGridFile

public XuluGridFile(File targetFile,
                    RasterMetaData metaData)
             throws XuluGridFileException
Creates a NEW File with the sample given as RasterMetaData

Parameters:
targetFile - the file the new grid will be written to. Has to end with ".xgrid"!
metaData - the metadata of the new grid. Width and height are used to allocate the space for the new XGrid.
Throws:
XuluGridFileException

XuluGridFile

public XuluGridFile(WritableGrid grid,
                    File output)
             throws XuluGridFileException
Creates a new XuluGridFile out of an existing Writable Grid and opens it in read-write mode. The WritableGrid-Method getSampleType is used to determine the type and the bytelength (4 bytes for Float/Int and 8 bytes for doubleValues);

Parameters:
grid -
output -
Throws:
XuluGridFileException
Method Detail

getPartitialGrid2D

public WritableGridPartition getPartitialGrid2D(Rectangle partitionBounds)
                                         throws XuluGridFileException
Returns a partition of a WritableGrid as a WritableGridArray. Notice, that the minX and minY values are ignored and will be set to 0 (see WritableGrid for more information about minX and minY). If the given WritableGrid is not an instance of WritableGridPartition it is assumed that the topLeft corner of the source grid is (0,0). If it is a WritableGridPartition it is assumed that the the bounds of the two Partition refer to the same coordinate system. Real coordinates are supposed to reference the South(!)-West Corner.

Parameters:
partitionBounds - the rectangle describing the partition
Returns:
the new partition including the given corners
Throws:
XuluGridFileException - if the reading goes wrong

getRootID

public int getRootID()
Returns:
the hashcode of this object
See Also:
SplittableResource.getRootID()

setPartition

public void setPartition(WritableGrid gridPartition,
                         Rectangle partitionBounds)
                  throws XuluGridFileException
Overwrites the data at the location specified by the Rectangle with the given partition-data. It is assumed that the topLeft corner is (0,0). The method is synchronized over a static variable to ensure that only one XuluGridFile is read/write at a time. This reduces (hopefully) harddisk seek times and increases the overall performance.

Parameters:
gridPartition - the grid to be inserted
partitionBounds - the excact location in coordinates of the baseGrid
Throws:
XuluGridFileException - if the writing goes wrong

close

public void close()
Closes all used Filehandles. Should be called before destroying the object.


getMetaData

public RasterMetaData getMetaData()
Returns:
the metadata for this object

readXuluGridWorldFile

public RasterMetaData readXuluGridWorldFile(File worldFile)
                                     throws XuluGridFileException
The Xulu world file ist just a serialized RasterMetaData-Object!

Parameters:
worldFile - the world file
Returns:
a RasterMetaData Object, that contains all the raster meta data
Throws:
XuluGridFileException - if an error occures

writeToXuluGridFile

public static void writeToXuluGridFile(WritableGrid grid,
                                       File output)
                                throws XuluGridFileException
Writes the given Grid to a XuluGridFile. Warning: unbuffered write.

Parameters:
grid - the input grid
output - the output file
Throws:
XuluGridFileException - if something goes wrong

readIntoGridFromXuluGridFile

public static void readIntoGridFromXuluGridFile(WritableGrid grid,
                                                File input)
                                         throws XuluGridFileException
Writes data out of a XuluGridFile into a WritableGrid. Warning: unbuffered. May be slow. For buffered read use getWholeGrid() instead.

Parameters:
grid - the Grid in which the data should be written
input - the File with the XuluGridFile
Throws:
XuluGridFileException

writeWorldFileForMetaData

public static void writeWorldFileForMetaData(File XuluGridFile,
                                             RasterMetaData meta)
                                      throws XuluGridFileException
This File simply serializes the given appl.util.RasterMetaData Object to the given file.

Throws:
XuluGridFileException

getWholeGrid

public WritableGrid getWholeGrid()
                          throws XuluGridFileException
gives back the whole grid as a WritableGridArray in memory! Notice that this destroys all memory advantages of the GridFile. Is used e.g. by visualisation classes

Throws:
XuluGridFileException

getOutputFile

public File getOutputFile()
Returns:
the underlying file