org.gillius.realdb.model
Class ReliableSequencedBlock<T extends org.gillius.realdb.model.SequencedBlock>

java.lang.Object
  org.gillius.realdb.model.ReliableSequencedBlock<T>

All Implemented Interfaces:

Formattable

public class ReliableSequencedBlock<T extends org.gillius.realdb.model.SequencedBlock>
extends java.lang.Object
implements Formattable

ReliableSequencedBlock persists a SequencedBlock in a fail-safe manner such that every write to the block either succeeds entirely, or if it fails, it reverts back to its previous state. This is achieved by writing two alternating copies of the block in the BlockFile.

Author:

Jason Winnebeck

Method Summary

static <T extends org.gillius.realdb.model.SequencedBlock> ReliableSequencedBlock<T>	createNew(BlockFile file, int firstBlock, int secondBlock, int size) Creates a new ReliableSequencedBlock by ignoring existing data on disk and formatting both allocated spaces to all 0's, based on 'size'.
void	format() Formats both primary and secondary block space by writing all NUL bytes.
T	getBlock() Returns the cached block; either that which was last written, or the block loaded if just loaded, or null if just created.
int	getNextSeqNum() Returns the sequence number for the next block to be written.
static <T extends org.gillius.realdb.model.SequencedBlock> ReliableSequencedBlock<T>	load(BlockFile file, int firstBlock, int secondBlock, int size, org.gillius.realdb.model.SequencedBlockLoader<T> loader) Creates a new ReliableSequencedBlock by loading the most recent and valid block.
void	writeBlock(T block) Writes the given block to the file.

Methods inherited from class java.lang.Object

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

Method Detail

createNew

public static <T extends org.gillius.realdb.model.SequencedBlock> ReliableSequencedBlock<T> createNew(BlockFile file,
                                                                                                      int firstBlock,
                                                                                                      int secondBlock,
                                                                                                      int size)
                                                                                           throws java.io.IOException

Creates a new ReliableSequencedBlock by ignoring existing data on disk and formatting both allocated spaces to all 0's, based on 'size'. Per the contract of SequencedBlock, data consisting of all NUL bytes must not be a valid serialized form on disk, and this class uses that assumption to perform the format.

This means that a newly created/formatted ReliableSequencedBlock will throw an exception when reloading it, unless writeBlock(SequencedBlock) is called.

Parameters:

file - non-null BlockFile

firstBlock - block index of start of primary space

secondBlock - block index of start of secondary space

size - maximum size of serialized block, in bytes

Throws:

java.io.IOException

load

public static <T extends org.gillius.realdb.model.SequencedBlock> ReliableSequencedBlock<T> load(BlockFile file,
                                                                                                 int firstBlock,
                                                                                                 int secondBlock,
                                                                                                 int size,
                                                                                                 org.gillius.realdb.model.SequencedBlockLoader<T> loader)
                                                                                      throws java.io.IOException,
                                                                                             BadFileException

Creates a new ReliableSequencedBlock by loading the most recent and valid block.

Parameters:

file - non-null BlockFile

firstBlock - block index of start of primary space

secondBlock - block index of start of secondary space

size - maximum size of serialized block, in bytes

loader - loader to deserialize the data

Throws:

java.io.IOException - if the file could not be read

BadFileException - if neither block is valid

getBlock

public T getBlock()

Returns the cached block; either that which was last written, or the block loaded if just loaded, or null if just created. If this ReliableSequencedBlock was created by load, or if writeBlock(T) has ever been called, this method will never return null.

getNextSeqNum

public int getNextSeqNum()

Returns the sequence number for the next block to be written.

format

public void format()
            throws java.io.IOException

Formats both primary and secondary block space by writing all NUL bytes. Per the contract of SequencedBlock, data consisting of all NUL bytes must not be a valid serialized form on disk, and this class uses that assumption to perform the format.

Specified by:

format in interface Formattable

Throws:

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

writeBlock

public void writeBlock(T block)
                throws java.io.IOException

Writes the given block to the file. If an exception occurs, there is NO change in state of this object, however, one or both of the portions of the underlying file may be corrupted.

Throws:

java.io.IOException