com.mucommander.io
Class BlockRandomInputStream

java.lang.Object
  java.io.InputStream
      com.mucommander.io.RandomAccessInputStream
          com.mucommander.io.BlockRandomInputStream

All Implemented Interfaces:

RandomAccess, java.io.Closeable

public abstract class BlockRandomInputStream
extends RandomAccessInputStream

BlockRandomInputStream is a specialized-yet-still-abstract RandomAccessInputStream that is geared towards resources that are read block by block, either because of a particular constrain or for performance reasons. This class typically comes in handy for network resources such as HTTP which have to request a block range for reading the resource.

Seeking inside the file is implemented transparently by reading a block starting at the seek offset. If seek(long) is called with an offset that is within the current block, no read occurs. The block size should be carefully chosen as it affects seek performance and thus overall performance greatly: the larger the block size, the more data is fetched when seeking outside the current block and consequently the longer it takes to reposition the stream. On the other hand, a larger block size will yield better performance when reading the resource sequentially, as it lessens the overhead of requesting a particular block.

Author:

Maxence Bernard

Field Summary

protected int

blockSize Block size, i.e.

Constructor Summary

protected

BlockRandomInputStream(int blockSize) Creates a new BlockRandomInputStream using the specified block size.

Method Summary

long	getOffset() Returns the offset (in bytes) from the beginning of the file at which the next read or write occurs.
int	read()
int	read(byte[] b, int off, int len) Reads up to len bytes of data from this file into an array of bytes.
protected abstract int	readBlock(long fileOffset, byte[] block, int blockLen) Reads a block, that spawns from fileOffset to fileOffset+blockLen, an returns the number of bytes that could be read, normally blockLen but can be less.
void	seek(long newOffset) Sets the offset, measured from the beginning of the file, at which the next read or write occurs.

Methods inherited from class com.mucommander.io.RandomAccessInputStream

available, close, mark, markSupported, readFully, readFully, reset, skip

Methods inherited from class java.io.InputStream

read

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.mucommander.io.RandomAccess

getLength

Field Detail

blockSize

protected final int blockSize

Block size, i.e. length of the block array

Constructor Detail

BlockRandomInputStream

protected BlockRandomInputStream(int blockSize)

Creates a new BlockRandomInputStream using the specified block size.

The block size should be carefully chosen as it affects seek performance and thus overall performance greatly: the larger the block size, the more data is fetched when seeking outside the current block and consequently the longer it takes to reposition the stream. On the other hand, a larger block size will yield better performance when reading the resource sequentially, as it lessens the overhead of requesting a particular block.

Parameters:

blockSize - controls the amount of data requested when reading a block

Method Detail

read

public int read()
         throws java.io.IOException

Specified by:

read in class java.io.InputStream

Throws:

java.io.IOException

read

public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException

Description copied from class: RandomAccessInputStream

Reads up to len bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Specified by:

read in class RandomAccessInputStream

Parameters:

b - the buffer into which the data is read

off - the start offset of the data

len - the maximum number of bytes read

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.

Throws:

java.io.IOException - if an I/O error occurs

getOffset

public long getOffset()
               throws java.io.IOException

Description copied from interface: RandomAccess

Returns the offset (in bytes) from the beginning of the file at which the next read or write occurs.

Returns:

the offset (in bytes) from the beginning of the file at which the next read or write occurs

Throws:

java.io.IOException - if an I/O error occurs.

seek

public void seek(long newOffset)
          throws java.io.IOException

Description copied from interface: RandomAccess

Sets the offset, measured from the beginning of the file, at which the next read or write occurs. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.

Parameters:

newOffset - the new offset position, measured in bytes from the beginning of the file

Throws:

java.io.IOException - if an I/O error occurs

readBlock

protected abstract int readBlock(long fileOffset,
                                 byte[] block,
                                 int blockLen)
                          throws java.io.IOException

Reads a block, that spawns from fileOffset to fileOffset+blockLen, an returns the number of bytes that could be read, normally blockLen but can be less.

Note that blockLen may be smaller than blockSize if the end of file is near, to prevent EOF from being reached. In other words, fileOffset+blockLen should theorically not exceed the file's length, but this could happen in the unlikely event that the file just shrinked after RandomAccess.getLength() was last called. So this method's implementation should handle the case where EOF is reached prematurely and return the number of bytes that were actually read.

Parameters:

fileOffset - global file offset that marks the beginning of the block

block - the array to fill with data, starting at 0

blockLen - number of bytes to read

Returns:

the number of bytes that were actually read, normally blockLen unless

Throws:

java.io.IOException - if an I/O error occurred