ewe.io
Interface Stream

All Superinterfaces:

BasicStream

All Known Subinterfaces:

BufferedStream, RandomAccessStream

All Known Implementing Classes:

BasicStreamObject, RandomStreamAdapter, RandomStreamObject, StreamAdapter

public interface Stream

extends BasicStream

Stream is used for all streaming I/O operations. This includes File I/O, Socket I/O and Serial I/O. The Stream interface provides two sets on methods. One fully non-blocking and one semi-blocking (i.e. blocks the current thread).

The semi-blocking methods are listed below. They work in exactly the same way as java.io.InputStream and java.io.OutputStream

 
 public int read(byte buf[], int start, int count) throws IOException;
 public int read(byte buf[]) throws IOException;
 public int read() throws IOException;
 public int write(byte buf[], int start, int count) throws IOException;
 public int write(byte buf[]) throws IOException;
 public int write(int aByte) throws IOException;

 

These methods will block the current mThread thread (but allow others to execute). If you call them from within a non-Coroutine thread then they will block the entire program!

The non-blocking methods are:

 
 public IOHandle readBytes(byte []buf,int start,int count,IOHandle handle,boolean readFully);
 public IOHandle writeBytes(byte []buf,int start,int count,IOHandle handle);
 
 

These always return immediately and you can use the returned IOHandle to check on the progress of the operation.

The correct way to use a handle to wait for the operation to complete is as follows:

 // First attempt a read operation.
 IOHandle readOp = stream.readBytes(buf,0,1024,null,false);
 // At any time from this point I can check the handle.
 // If I want to wait for 5 seconds and if it is not successfull abort I can do this:
 ...
 if (readOp.waitOnFlags(readOp.Success,new TimeOut(5000))){
 	//If the waitOnFlags returns true, then the Success bit was set and so the read has
 	//succeeded.
 	int bytesGot = readOp.bytesTransferred;
 	processBytes(buff,bytesGot);
 }else{
 	//If the waitOnFlags returns false, then either it timed out before Success was set OR
 	//the Stopped bit was set (implying that the operation has stopped) and Success was not set.
 	if ((readOp.check() & readOp.Stopped) != 0){
 		// If the Stopped bit is set, then an error must have occured if Success was not set.
 		int error = readOp.errorCode;
 		if (error == readOp.STREAM_END_REACHED)
 			doEndOfStreamProcessing();
 		else
 			doStreamErrorProcessing(error);
 		stream.close();
 	}else{
 		// At this point, the Stopped bit was not set, implying that the read operation is still
 		// in progress. I can choose to do something else and wait for it to complete later using
 		// the same procedure - or I can abort the read operation, assuming that something has gone
 		// wrong.
 		readOp.stop(0);
 		stream.close();
 	}
 }
 

Method Summary

void	flush() Flush all buffered bytes out to the destination.
int	read() Read in a single byte from the stream.
int	read(byte[] buff) Read bytes into a buffer.
int	read(byte[] buff, int offset, int count) Reads bytes into a buffer.
int	readBytes(byte[] buff, int start, int count) Deprecated. use the read(byte [],int,int) method instead.
IOHandle	readBytes(byte[] buff, int start, int count, IOHandle handle, boolean readFully) This reads bytes from the stream asynchronously.
InputStream	toInputStream()
OutputStream	toOutputStream()
void	write(byte[] buff) Writes bytes from a buffer to the Stream.
void	write(byte[] buff, int offset, int count) Writes bytes from a buffer to the Stream.
void	write(int aByte) Write out a single byte to the stream.
int	writeBytes(byte[] buff, int start, int count) Deprecated. use the write(byte [],int,int) method instead.
IOHandle	writeBytes(byte[] buff, int start, int count, IOHandle handle) This writes bytes to the stream asynchronously.

Methods inherited from interface ewe.io.BasicStream

close, closeStream, flushStream, isOpen, nonBlockingRead, nonBlockingWrite

Method Detail

read

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

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.

read

public int read(byte[] buff)
         throws IOException

Read bytes into a buffer. Reads up to buff.length bytes starting at index 0. This method blocks the current Coroutine, but allows others to continue executing.

Returns:

The number of bytes actually 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

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.

write

public void write(byte[] buff)
           throws IOException

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

Throws:

IOException - if an error occurs writing to the stream.

readBytes

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

Deprecated. use the read(byte [],int,int) method instead.

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:

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

Deprecated. use the write(byte [],int,int) method instead.

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:

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.

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

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:

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

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

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:

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.

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.

read

public int read()
         throws IOException

Read in a single byte from the stream.

Returns:

The byte read in the low 8 bits of the returned value, or -1 if the stream has closed.

Throws:

IOException - if an error occurs reading from the stream.

write

public void write(int aByte)
           throws IOException

Write out a single byte to the stream.

Throws:

IOException - if an error occurs writing to the stream.

flush

public void flush()
           throws IOException

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.

toInputStream

public InputStream toInputStream()
                          throws IllegalStateException

Throws:

IllegalStateException

toOutputStream

public OutputStream toOutputStream()
                            throws IllegalStateException

Throws:

IllegalStateException