org.gillius.realdb.io
Class RandomAccessBlockFile

java.lang.Object
  org.gillius.realdb.io.RandomAccessBlockFile

All Implemented Interfaces:

java.io.Closeable, BlockFile

public class RandomAccessBlockFile
extends java.lang.Object
implements BlockFile

RandomAccessBlockFile implements the BlockFile interface through a given RandomAccessFile, which should be opened in "rwd" or "rws" mode as appropriate. If the JVM and operating system do not implement these modes properly, it is possible that RandomAccessBlockFile cannot completely make the write behavior guarantees. On Windows XP and Linux using the Sun J2SE 1.6, this does appear to work based on my research.

An instance of this class cannot be shared between threads.

TODO: this class may need an "offset" attribute to fully guarantee the writeBlock behavior

Author:

Jason Winnebeck

Constructor Summary

RandomAccessBlockFile(java.io.RandomAccessFile file, int blockSize)
Constructs a new RandomAccessBlockFile to work with the given file and block size.

RandomAccessBlockFile(java.io.RandomAccessFile file, int blockSize, int numBlocks)
Constructs a new RandomAccessBlockFile to work with the given parameters.

Method Summary

void	close()
int	getBlockSize() Returns the size of a block, in bytes.
int	getSize() Returns the size of the file, in blocks.
void	readBlock(int num, byte[] data) Read a block of data into the given buffer, which is of the size returned by BlockFile.getBlockSize().
int	readBlocks(int startBlock, byte[] data) Reads one or more blocks from the file into the given buffer.
void	writeBlock(int num, byte[] data) Write a block of data from the given buffer, which is of the size returned by BlockFile.getBlockSize().
int	writeBlocks(int startBlock, byte[] data) Works identically to BlockFile.writeBlocks(int, byte[], int, int) with start=0 and len=data.length.
int	writeBlocks(int startBlock, byte[] data, int start, int len) Write multiple blocks of data from the given buffer, which is of any size that will fit within the file.

Methods inherited from class java.lang.Object

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

Constructor Detail

RandomAccessBlockFile

public RandomAccessBlockFile(java.io.RandomAccessFile file,
                             int blockSize)
                      throws java.io.IOException

Constructs a new RandomAccessBlockFile to work with the given file and block size. The file must be preallocated, as the number of blocks is determined by the file length divided by the block size. The partial remaining block, if it exists, is not accessible from this BlockFile.

Throws:

java.io.IOException

RandomAccessBlockFile

public RandomAccessBlockFile(java.io.RandomAccessFile file,
                             int blockSize,
                             int numBlocks)
                      throws java.io.IOException

Constructs a new RandomAccessBlockFile to work with the given parameters. The file must be preallocated, and large enough to hold 'numBlocks' blocks. Any leftover space will be unaccessible.

Throws:

java.io.IOException

Method Detail

getSize

public int getSize()

Description copied from interface: BlockFile

Returns the size of the file, in blocks.

Specified by:

getSize in interface BlockFile

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

getBlockSize

public int getBlockSize()

Description copied from interface: BlockFile

Returns the size of a block, in bytes.

Specified by:

getBlockSize in interface BlockFile

readBlock

public void readBlock(int num,
                      byte[] data)
               throws java.io.IOException

Description copied from interface: BlockFile

Read a block of data into the given buffer, which is of the size returned by BlockFile.getBlockSize().

Specified by:

readBlock in interface BlockFile

Throws:

java.io.IOException

readBlocks

public int readBlocks(int startBlock,
                      byte[] data)
               throws java.io.IOException

Description copied from interface: BlockFile

Reads one or more blocks from the file into the given buffer. The number of blocks read is the data array length divided by the block size, rounded up. If the data buffer does not have enough space to fully fit the last block, the content is truncated.

Specified by:

readBlocks in interface BlockFile

Parameters:

startBlock - starting block address, from 0 to BlockFile.getSize() - 1

data - non-null data buffer that is fully populated

Returns:

the number of blocks actually read (includes the possibly truncated block)

Throws:

java.io.IOException - if an error occurs reading the data

java.io.EOFException - if there are not enough blocks to fill the buffer

writeBlock

public void writeBlock(int num,
                       byte[] data)
                throws java.io.IOException

Description copied from interface: BlockFile

Write a block of data from the given buffer, which is of the size returned by BlockFile.getBlockSize(). When this method suceeds, the block has been safely committed to the disk. If it fails, then the block will have undefined content.

Specified by:

writeBlock in interface BlockFile

Throws:

java.io.IOException

writeBlocks

public int writeBlocks(int startBlock,
                       byte[] data)
                throws java.io.IOException

Description copied from interface: BlockFile

Works identically to BlockFile.writeBlocks(int, byte[], int, int) with start=0 and len=data.length.

Specified by:

writeBlocks in interface BlockFile

Parameters:

startBlock - starting block address, from 0 to BlockFile.getSize() - 1

data - non-null data block that is not too large (see main comment)

Returns:

The number of blocks actually written

Throws:

java.io.IOException - if an error occurs while writing the data

java.io.EOFException - if there are not enough blocks to write

writeBlocks

public int writeBlocks(int startBlock,
                       byte[] data,
                       int start,
                       int len)
                throws java.io.IOException

Description copied from interface: BlockFile

Write multiple blocks of data from the given buffer, which is of any size that will fit within the file. The block will fit if (BlockFile.getSize() - startBlock) * BlockFile.getBlockSize() is greater than the length of data. If the size of data is not an exact multiple of the block size, extra 0 bytes are padded at the end of the block. When this method suceeds, the block has been safely committed to the disk. If it fails, then all of the affected blocks have an undefined content.

The primary purpose of this method is for performance, when writing a larger logical block than the minimum physical block size supported, when it is acceptable to entirely commit or entirely lose the logical block in one operation.

Specified by:

writeBlocks in interface BlockFile

Parameters:

startBlock - starting block address, from 0 to BlockFile.getSize() - 1

data - non-null data block that is not too large (see main comment)

Returns:

The number of blocks actually written

Throws:

java.io.IOException - if an error occurs while writing the data

java.io.EOFException - if there are not enough blocks to write