ewe.io
Class BlockingStreamObject

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

All Implemented Interfaces:

BasicStream, Stream, Streamable

Direct Known Subclasses:

DatabaseObject.MetaData

public class BlockingStreamObject

extends BasicStreamObject

A BlockingStreamObject is a full implementation of a Stream but where there are no actual non-blocking methods. That is, the nonBlocking() methods will still be there but they actually will block the calling thread.

The only methods you need to override are:
int read(byte[] buffer,int offset,int length) throws IOException;
void write(byte[] buffer,int offset,int length) throws IOException;
boolean closeStream() throws IOException;
boolean flushStream() throws IOException;

Field Summary

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

BlockingStreamObject()

Method Summary

boolean	close() Closes the stream.
boolean	closeStream() This is non-blocking.
void	flush() Flush all buffered bytes out to the destination.
boolean	flushStream() This is non-blocking.
boolean	isOpen() Returns if the stream is open or not.
int	nonBlockingRead(byte[] data, int offset, int length) This is the non-blocking read operation.
int	nonBlockingWrite(byte[] data, int offset, int length) This is the non-blocking write operation.
int	read(byte[] data, int offset, int length) Reads bytes into a buffer.
int	readBytes(byte[] data, int offset, int length) Reads bytes from the stream.
IOHandle	readBytes(byte[] data, int offset, int length, IOHandle h, boolean readAll) This reads bytes from the stream asynchronously.
void	write(byte[] data, int offset, int length) Writes bytes from a buffer to the Stream.
int	writeBytes(byte[] data, int offset, int length) Writes bytes to the the stream.
IOHandle	writeBytes(byte[] data, int offset, int length, IOHandle h) 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

Constructor Detail

BlockingStreamObject

public BlockingStreamObject()

Method Detail

read

public int read(byte[] data,
                int offset,
                int length)
         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.

length - 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[] data,
                  int offset,
                  int length)
           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.

length - The number of bytes to write.

Throws:

IOException - if an error occurs writing to the stream.

close

public final boolean close()

Description copied from interface: BasicStream

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

flush

public final 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.

nonBlockingRead

public final int nonBlockingRead(byte[] data,
                                 int offset,
                                 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.

Parameters:

data - Destination byte array to hold incoming data.

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

nonBlockingWrite

public final int nonBlockingWrite(byte[] data,
                                  int offset,
                                  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.

Parameters:

data - Source byte array holding data to be written.

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

isOpen

public boolean isOpen()

Description copied from interface: BasicStream

Returns if the stream is open or not.

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.

Throws:

IOException

readBytes

public final int readBytes(byte[] data,
                           int offset,
                           int length)

Description copied from interface: Stream

Reads bytes from the stream. This blocks until some bytes have been read. If this blocks within a Coroutine - it will allow other Coroutines to operate. NEVER call this with a count of zero.

Parameters:

data - Destination byte array to hold incoming data.

offset - Starting index in buff for incoming data.

length - Maximum number of bytes to read.

Returns:

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

writeBytes

public final int writeBytes(byte[] data,
                            int offset,
                            int length)

Description copied from interface: Stream

Writes bytes to the the stream. This blocks until all bytes have been written. If this blocks within a Coroutine - it will allow other Coroutines to operate.

Parameters:

data - Source byte array holding data to be written.

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

length - 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 final IOHandle readBytes(byte[] data,
                                int offset,
                                int length,
                                IOHandle h,
                                boolean readAll)

Description copied from interface: Stream

This reads bytes from the stream asynchronously. It returns an IOHandle immediately 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:

data - Destination byte array to hold incoming data.

offset - Starting index in buff for incoming data.

length - Maximum number of bytes to read.

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

readAll - 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 final IOHandle writeBytes(byte[] data,
                                 int offset,
                                 int length,
                                 IOHandle h)

Description copied from interface: Stream

This writes bytes to the stream asynchronously. It returns an IOHandle immediately 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:

data - Source byte array holding data to be written.

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

length - Number of bytes to write.

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