org.jdtaus.core.io
Interface StructuredFile

public interface StructuredFile

Block oriented I/O operations.

Version:

$Id: StructuredFile.java 8044 2009-07-02 01:29:05Z schulte2005 $

Author:

Christian Schulte

Method Summary

void	addStructuredFileListener(StructuredFileListener listener) Adds a StructuredFileListener to the listener list.
void	close() Releases any system resources associated with an instance.
void	deleteBlocks(long index, long count) Removes blocks.
long	getBlockCount() Reads the total amount of existing blocks.
int	getBlockSize() Reads the length of one block in byte.
StructuredFileListener[]	getStructuredFileListeners() Gets all currently registered StructuredFileListeners.
void	insertBlocks(long index, long count) Inserts new blocks.
void	readBlock(long block, int off, byte[] buf) Reads buf.length byte starting at position off in block.
void	readBlock(long block, int off, byte[] buf, int index, int length) Reads length byte starting at position off in block into buf starting at index inclusive.
void	removeStructuredFileListener(StructuredFileListener listener) Removes a StructuredFileListener from the listener list.
void	writeBlock(long block, int off, byte[] buf) Writes buf.length byte from buf into block starting at off inclusive.
void	writeBlock(long block, int off, byte[] buf, int index, int length) Writes length byte from buf starting at index inclusive into block starting at off inclusive.

Method Detail

addStructuredFileListener

void addStructuredFileListener(StructuredFileListener listener)

Adds a StructuredFileListener to the listener list.

Parameters:

listener - The listener to be added to the listener list.

Throws:

NullPointerException - if listener is null.

close

void close()
           throws IOException

Releases any system resources associated with an instance. A closed instance cannot perform input or output operations and cannot be reopened.

Throws:

IOException - if releasing system resources fails.

deleteBlocks

void deleteBlocks(long index,
                  long count)
                  throws IOException

Removes blocks. The new index of the block previously at index + count will be at index.

Parameters:

index - index of the first block to start removing count blocks.

count - number of blocks to remove.

Throws:

IndexOutOfBoundsException - if index is negative or count is negative or zero or index is greater than getBlockCount() - count.

IOException - if deleting blocks fails.

getBlockCount

long getBlockCount()
                   throws IOException

Reads the total amount of existing blocks.

Returns:

total amount of existing blocks.

Throws:

IOException - if getting the block count fails.

getBlockSize

int getBlockSize()
                 throws IOException

Reads the length of one block in byte.

Returns:

length of one block in byte.

Throws:

IOException - if getting the block size fails.

getStructuredFileListeners

StructuredFileListener[] getStructuredFileListeners()

Gets all currently registered StructuredFileListeners.

Returns:

all currently registered StructuredFileListeners.

insertBlocks

void insertBlocks(long index,
                  long count)
                  throws IOException

Inserts new blocks. The content of the new blocks is not further specified. The new index of the block previously at index will be at index + count.

Parameters:

index - index of the first new block.

count - number of blocks to insert starting at index.

Throws:

IndexOutOfBoundsException - if index or count is negativ or index is greater than getBlockCount() or count is zero or greater than Long.MAX_VALUE - getBlockCount().

IOException - if inserting blocks fails.

readBlock

void readBlock(long block,
               int off,
               byte[] buf)
               throws IOException

Reads buf.length byte starting at position off in block. Same as readBlock(block, off, buf, 0, buf.length).

Parameters:

block - index of the block to read data from.

off - starting offset to the data to read from block.

buf - array to store the data in.

Throws:

NullPointerException - if buf is null.

IndexOutOfBoundsException - if block is negative, greater than or equal to getBlockCount(), or off is negative, greater than or equal to getBlockSize(), or the length of buf is greater than getBlockSize() - off.

IOException - if reading fails.

readBlock

void readBlock(long block,
               int off,
               byte[] buf,
               int index,
               int length)
               throws IOException

Reads length byte starting at position off in block into buf starting at index inclusive.

Parameters:

block - index of the block to read data from.

off - starting offset of the data to read from block.

buf - array to store the data in.

index - offset to start writing data into buf.

length - number of byte to read.

Throws:

NullPointerException - if buf is null.

IndexOutOfBoundsException - if block is negative, greater than or equal to getBlockCount(), or off is negative, greater than or equal to getBlockSize(), or index is negative, greater than or equal to the length of buf, or length is negative or greater than the length of buf minus index or greater than getBlockSize() - off.

IOException - if reading fails.

removeStructuredFileListener

void removeStructuredFileListener(StructuredFileListener listener)

Removes a StructuredFileListener from the listener list.

Parameters:

listener - The listener to be removed from the listener list.

Throws:

NullPointerException - if listener is null.

writeBlock

void writeBlock(long block,
                int off,
                byte[] buf)
                throws IOException

Writes buf.length byte from buf into block starting at off inclusive. Same as writeBlock(block, off, buf, 0, buf.length).

Parameters:

block - index of the block to write into.

off - inclusive offset to start writing into block.

buf - data to write into block beginning at offset.

Throws:

NullPointerException - if buf is null.

IndexOutOfBoundsException - if block is negative, greater than or equal to getBlockCount(), or off is greater than or equal to getBlockSize(), or the length of buf is greater than getBlockSize() - off.

IOException - if writing fails.

writeBlock

void writeBlock(long block,
                int off,
                byte[] buf,
                int index,
                int length)
                throws IOException

Writes length byte from buf starting at index inclusive into block starting at off inclusive.

Parameters:

block - index of the block to write into.

off - inclusive offset to start writing into block.

buf - data to write into block beginning at offset.

index - inclusive offset to start reading data from buf.

length - number of byte to read from buf starting at index.

Throws:

NullPointerException - if buf is null.

IndexOutOfBoundsException - if block is negative, greater than or equal to getBlockCount(), or off is negative, greater than or equal to getBlockSize(), or index is negative, greater than or equal to the length of buf, or length is negative or greater than the length of buf minus index or greater than getBlockSize() - off.

IOException - if writing fails.