ewe.io
Class StreamObject

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

All Implemented Interfaces:

BasicStream, Stream, Streamable

Direct Known Subclasses:

Catalog, DeflaterOutputStream, InflaterInputStream, MemoryStream, RandomStreamObject, SerialPort, SocketBase, StreamAdapter, ZipInputStream, ZipOutputStream

public abstract class StreamObject

extends BasicStreamObject

A StreamObject is the base object for implementing a Stream. Since Streams provide an asynchronous operation you must provide non-blocking I/O operations for the stream.

To extend this you must:

For Reading - EITHER override the single byte readAByte() OR extend the nonBlockingRead();
For Writing - EITHER override the single byte writeAByte() OR extend the nonBlockingWrite();
For Flushing - override the flushStream() method.
For Closing - override the closeStream() method.

All these methods MUST be non-blocking. They must not call a mThread wait() or sleep() method and they should block the calling thread for as little time as possible. This makes these operations safe to call from native methods.

Field Summary

static int	napIterations
static int	napTime
protected static int	READWRITE_CLOSED
protected static int	READWRITE_ERROR
protected static int	READWRITE_WOULDBLOCK

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

StreamObject()

Method Summary

boolean	close() Closes the stream.
boolean	closeStream() This is non-blocking.
protected int	doRead(byte[] buf, int start, int count, IOHandle handle, boolean readCompletely) This returns: 0 - Stream end reached.
protected int	doWrite(byte[] buf, int start, int count, IOHandle handle) This returns: 0 - Stream closed.
void	flush() Flush all buffered bytes out to the destination.
boolean	isOpen() Returns if the stream is open or not.
protected void	nap()
protected void	nap(boolean forReading)
int	nonBlockingRead(byte[] buff, int start, int count) This is the non-blocking read operation.
int	nonBlockingWrite(byte[] buff, int start, int count) This is the non-blocking write operation.
int	read(byte[] buff, int offset, int count) Reads bytes into a buffer.
protected int	readAByte() This reads one byte of data.
int	readBytes(byte[] buf, int start, int count) This returns: 0 - Stream end reached.
IOHandle	readBytes(byte[] buf, int start, int count, IOHandle handle, boolean readCompletely) This reads bytes from the stream asynchronously.
void	write(byte[] buff, int offset, int count) Writes bytes from a buffer to the Stream.
protected int	writeAByte(byte val) This writes one byte of data.
int	writeBytes(byte[] buf, int start, int count) This returns: 0 - Stream closed.
IOHandle	writeBytes(byte[] buf, int start, int count, IOHandle handle) This writes bytes to the stream asynchronously.

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

flushStream

Field Detail

napIterations

public static int napIterations

napTime

public static int napTime

READWRITE_CLOSED

protected static final int READWRITE_CLOSED

See Also:

Constant Field Values

READWRITE_ERROR

protected static final int READWRITE_ERROR

See Also:

Constant Field Values

READWRITE_WOULDBLOCK

protected static final int READWRITE_WOULDBLOCK

See Also:

Constant Field Values

Constructor Detail

StreamObject

public StreamObject()

Method Detail

nap

protected void nap(boolean forReading)

nap

protected void nap()

readAByte

protected int readAByte()

This reads one byte of data. Overriding this method is optional if you override the nonBlockingRead() method. This is the least efficient way of implementing a readable stream but in cases where the Stream is very slow, it may be OK.

The default implementation simply returns -2 (i.e. read operations are not allowed).

Return values:

If a byte has been read successfully, the byte value should appear in the last 8-bits of the return value.

If the stream is closed or end of stream has been reached, it should return -1 (READWRITE_CLOSED)

If there is an IO error it should return -2 (READWRITE_ERROR)

If there are no available bytes to read yet, but the stream is still open and OK, it should return -3 (READWRITE_WOULDBLOCK) These return values never get to the end user - they are only used by the StreamObject implementation of nonBlockingRead() - which you can override yourself and therefore ignore this method.

writeAByte

protected int writeAByte(byte val)

This writes one byte of data. Overriding this method is optional if you override the nonBlockingWrite() method. This is the least efficient way of implementing a writeable stream but in cases where the Stream is very slow, it may be OK.

The default implementation simply returns -2 (i.e. write operations are not allowed).

Return values:

If a byte has been written successfully, it should return the byte written.

If the stream is closed for writing it should return -1 (READWRITE_CLOSED)

If there is an IO error it should return -2 (READWRITE_ERROR)

If the byte could not be written yet, but the stream is still open and OK, it should return -3 (READWRITE_WOULDBLOCK) These return values never get to the end user - they are only used by the StreamObject implementation of nonBlockingWrite() - which you can override yourself and therefore ignore this method.

doRead

protected int doRead(byte[] buf,
                     int start,
                     int count,
                     IOHandle handle,
                     boolean readCompletely)

This returns: 0 - Stream end reached. -1 - Error. > 0 - Number of bytes read.

doWrite

protected int doWrite(byte[] buf,
                      int start,
                      int count,
                      IOHandle handle)

This returns: 0 - Stream closed. -1 - Error. > 0 - Number of bytes read.

readBytes

public int readBytes(byte[] buf,
                     int start,
                     int count)

This returns: 0 - Stream end reached. -1 - Error. >0 - Number of bytes read.

Parameters:

buf - Destination byte array to hold incoming data.

start - Starting index in buff for incoming data.

count - Maximum number of bytes to read.

Returns:

0 = Stream end reached.
-1 = IO Error.
>0 = Number of bytes read.

writeBytes

public int writeBytes(byte[] buf,
                      int start,
                      int count)

This returns: 0 - Stream closed. -1 - Error. > 0 - Number of bytes written.

Parameters:

buf - Source byte array holding data to be written.

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

count - Number of bytes to write.

Returns:

0 = Stream end reached - no more bytes can be written.
-1 = IO Error.
>0 = Number of bytes written (always equal to count).

readBytes

public IOHandle readBytes(byte[] buf,
                          int start,
                          int count,
                          IOHandle handle,
                          boolean readCompletely)

This reads bytes from the stream asynchronously. It returns an IOHandle which you can use to check the status of the operation. When the operation is complete you should check the errorCode and byteTransferred members of the IOHandle.

Parameters:

buf - Destination byte array to hold incoming data.

start - Starting index in buff for incoming data.

count - Maximum number of bytes to read.

handle - An existing IOHandle for the operation to use and return. If this is null then a new one will be created and returned.

readCompletely - Set this to be true if you require the full number of count bytes to be read.

Returns:

An IOHandle to be used for monitoring the progress of the operation.

writeBytes

public IOHandle writeBytes(byte[] buf,
                           int start,
                           int count,
                           IOHandle handle)

This writes bytes to the stream asynchronously. It returns an IOHandle which you can use to check the status of the operation. When the operation is complete you should check the errorCode and byteTransferred members of the IOHandle.

Parameters:

buf - Source byte array holding data to be written.

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

count - Number of bytes to write.

handle - An existing IOHandle for the operation to use and return. If this is null then a new one will be created and returned.

Returns:

An IOHandle to be used for monitoring the progress of the operation.

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.

Throws:

IOException

isOpen

public boolean isOpen()

Description copied from interface: BasicStream

Returns if the stream is open or not.

nonBlockingRead

public int nonBlockingRead(byte[] buff,
                           int start,
                           int count)

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.

The default StreamObject implementation of this uses the single byte read() method.

Parameters:

buff - Destination byte array to hold incoming data.

start - Starting index in buff for incoming data.

count - 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[] buff,
                            int start,
                            int count)

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.

The default StreamObject implementation of this uses the single byte write() method.

Parameters:

buff - Source byte array holding data to be written.

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

count - 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.

read

public int read(byte[] buff,
                int offset,
                int count)
         throws IOException

Description copied from interface: Stream

Reads bytes into a buffer. This method blocks the current Coroutine, but allows others to continue executing.

Parameters:

offset - The offset index in the destination array to accept the data.

count - The maximum number of bytes to read.

Returns:

The actual number of bytes read, or -1 if the stream has ended.

Throws:

IOException - if an error occurs reading the stream.

write

public void write(byte[] buff,
                  int offset,
                  int count)
           throws IOException

Description copied from interface: Stream

Writes bytes from a buffer to the Stream. This method blocks the current Coroutine until all bytes are written, but allows others to continue executing.

Parameters:

offset - The start index in the array of the data bytes.

count - The number of bytes to write.

Throws:

IOException - if an error occurs writing to the stream.

flush

public void flush()
           throws IOException

Description copied from interface: Stream

Flush all buffered bytes out to the destination. This is call blocks the current mThread, but allows others to execute.

Throws:

IOException - if an error occured.

close

public boolean close()

Description copied from interface: BasicStream

Closes the stream. Returns true if the operation is successful and false otherwise.