ewe.io
Class RewindableStream

java.lang.Object
  ewe.util.Errorable
      ewe.io.BasicStreamObject
          ewe.io.StreamObject
              ewe.io.RandomStreamObject
                  ewe.io.RewindableStream

All Implemented Interfaces:

BasicRandomAccessStream, BasicStream, RandomAccessStream, Stream, Streamable

public class RewindableStream

extends RandomStreamObject

A RewindableStream adapts a BasicStream so that a particular section of the stream (i.e. a set number of bytes, starting from the first byte) can be accessed randomly, while the remaining bytes can only be accessed sequentially.

Such a Stream can be used when you need to decode data from an Input stream, but some pre-processing of some number of starting bytes is needed - for example in image decoding.

As data is read from the stream it is copied into a buffer as well as being returned for consumption. A rewind() operation then causes the stream to seek to the start of the stream, and you can subsequently seek() up to that point.

Field Summary

Fields inherited from class ewe.io.StreamObject

napIterations, napTime, READWRITE_CLOSED, READWRITE_ERROR, READWRITE_WOULDBLOCK

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

RewindableStream(Stream stream)

Method Summary

boolean	canWrite() Tests if the RandomAccessStream was opened in read-write mode as opposed to read-ony mode.
boolean	closeStream() This is non-blocking.
boolean	flushStream() This is non-blocking.
boolean	isOpen() Returns if the stream is open or not.
int	nonBlockingRead(byte[] buffer, int start, int length) This is the non-blocking read operation.
int	nonBlockingWrite(byte[] buffer, int start, int length) This is the non-blocking write operation.
void	rewind()
static void	rewind(RandomAccessStream stream)
boolean	seekPosition(long pos) Tell the Stream to move to the specific position.
long	tellPosition() Retrieve the file position.
static RandomAccessStream	toRewindableStream(Stream stream)

Methods inherited from class ewe.io.RandomStreamObject

getFilePosition, getLength, getStreamLength, length, nonBlockingRead, nonBlockingWrite, seek, seek, setLength, setStreamLength, tell, toRandomStream

Methods inherited from class ewe.io.StreamObject

close, doRead, doWrite, flush, nap, nap, read, readAByte, readBytes, readBytes, write, writeAByte, writeBytes, writeBytes

Methods inherited from class ewe.io.BasicStreamObject

getException, getName, read, read, throwIOException, toInputStream, toOutputStream, toStream, write, write

Methods inherited from class ewe.util.Errorable

returnError, returnError, returnError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Methods inherited from interface ewe.io.BasicStream

close

Methods inherited from interface ewe.io.Stream

flush, read, read, read, readBytes, readBytes, toInputStream, toOutputStream, write, write, write, writeBytes, writeBytes

Constructor Detail

RewindableStream

public RewindableStream(Stream stream)

Method Detail

toRewindableStream

public static RandomAccessStream toRewindableStream(Stream stream)

rewind

public static void rewind(RandomAccessStream stream)
                   throws IOException

Throws:

IOException

canWrite

public boolean canWrite()

Description copied from interface: BasicRandomAccessStream

Tests if the RandomAccessStream was opened in read-write mode as opposed to read-ony mode.

flushStream

public boolean flushStream()
                    throws IOException

Description copied from interface: BasicStream

This is non-blocking. It returns true if the flush completed, false if it did not, or throws an exception on error.

Throws:

IOException

closeStream

public boolean closeStream()
                    throws IOException

Description copied from interface: BasicStream

This is non-blocking. It returns true if the close completed, false if it did not, or throws an exception on error.

Specified by:

closeStream in interface BasicStream

Overrides:

closeStream in class StreamObject

Throws:

IOException

isOpen

public boolean isOpen()

Description copied from interface: BasicStream

Returns if the stream is open or not.

Specified by:

isOpen in interface BasicStream

Overrides:

isOpen in class StreamObject

nonBlockingRead

public int nonBlockingRead(byte[] buffer,
                           int start,
                           int length)

Description copied from interface: BasicStream

This is the non-blocking read operation. It should never attempt to wait() or sleep() in a Coroutine. It should return as quickly as possible. This makes it safe to be called from within a native method. Note that this should NEVER be called with a count of zero.

Specified by:

nonBlockingRead in interface BasicStream

Overrides:

nonBlockingRead in class StreamObject

Parameters:

buffer - Destination byte array to hold incoming data.

start - Starting index in buff for incoming data.

length - Maximum number of bytes to read - should never be zero.

Returns:

greater than 0 = Number of bytes read.
0 = No bytes available to read at this time.
-1 = Stream end reached no further bytes to read.
-2 = IO Error.
Note that these values are different to the Stream.readBytes method.

nonBlockingWrite

public int nonBlockingWrite(byte[] buffer,
                            int start,
                            int length)

Description copied from interface: BasicStream

This is the non-blocking write operation. It should never attempt to wait() or sleep() in a Coroutine. It should return as quickly as possible. This makes it safe to be called from within a native method.

Specified by:

nonBlockingWrite in interface BasicStream

Overrides:

nonBlockingWrite in class StreamObject

Parameters:

buffer - Source byte array holding data to be written.

start - Starting index in buff for data to be written.

length - Number of bytes to write - should never be zero.

Returns:

greater than 0 = Number of bytes actually written.
0 = No bytes could be written yet - but the stream is still open.
-1 = Stream has been closed - no further writes are possible.
-2 = IO error - something went wrong.
Note that these values are different to the Stream.writeBytes method.

seekPosition

public boolean seekPosition(long pos)
                     throws IOException

Tell the Stream to move to the specific position. This is a non-blocking call.

Specified by:

seekPosition in interface BasicRandomAccessStream

Overrides:

seekPosition in class RandomStreamObject

Parameters:

pos - The position to seek to.

Returns:

true if the seek completed successfully, false if the seek did not complete yet.

Throws:

IOException - if an error occured during the seek.

tellPosition

public long tellPosition()
                  throws IOException

Retrieve the file position. This is non-blocking

Specified by:

tellPosition in interface BasicRandomAccessStream

Overrides:

tellPosition in class RandomStreamObject

Returns:

the position of the stream or -1 if the position is not known yet.

Throws:

IOException - if an error occured while getting the position.

rewind

public void rewind()
            throws IOException

Throws:

IOException