superwaba.ext.xplat.io
Class BufferStream

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--superwaba.ext.xplat.io.BufferStream

public class BufferStream
extends Stream

BufferStream is actually several classes in one. It can serve as a buffer to another stream, packaging up several read or write operations into a single one to make them more efficient. It can act as a sink, collecting any number of writes, returning the result as a byte array. It can do offstream processing, taking a byte array that may have been read from another stream and treating it as a stream itself, or filling in an array so it can be sent off on another stream. It is of most use when used in conjunction with DataStream. Here's some examples:

Here we write a new record to a Catalog and read it back in.

   BufferStream outBuffer=new BufferStream();
   DataStream ds=new DataStream(outBuffer);
   ds.writeInt(12);
   ds.writeString("Hello");
   ds.writeFloat(3.14);
   byte[] buf=bs.getBuffer();

   Catalog c=new Catalog("crtr.TYPE",Catalog.WRITE_ONLY);
   c.addRecord(buf.length);
   c.writeBytes(buf,0,buf.length);
   c.close();

   ...

   Catalog c=new Catalog("crtr.TYPE",Catalog.READ_ONLY);
   c.setRecordPos(c.getRecordCount()-1);
   int size=c.getRecordSize();
   byte[] b=new byte[size];
   c.readBytes(buf,0,buf.length);
   c.close();

   BufferStream inBuffer=new BufferStream(buf);
   DataStream ds=new DataStream(inBuffer);
   int i=ds.readInt();       // 12
   String s=ds.readString(); // Hello
   float f=ds.readFloat();   // 3.14
 

In this example we are buffering the output to a SerialPort. In this case any data we write to the BufferStream is not sent to the SerialPort until the buffer is full or flush() is called. In this case the input is still being handled through the SerialPort but the same bufferPort object could be used to read too. One point to note if you do it this way is that when it's buffer is empty, the BufferStream will attempt to read as many bytes as will fit in it's buffer, regardless of how many are asked for. This could cause problems if you want to access the underlying stream without using the BufferStream.

   SerialPort port = new SerialPort(0, 9600);
   if (!port.isOpen())
     return;

   BufferStream bufferPort=new BufferStream(port);
   byte buf[] = new byte[10];
   buf[0] = 3;
   buf[1] = 7;
   bufferPort.writeBytes(buf, 0, 2);
   buf[0] = 4;
   buf[1] = 1;
   bufferPort.writeBytes(buf, 0, 2);
   bufferPort.flush();
   int count = port.readBytes(buf, 0, 10);
   if (count == 10)
   ...
   port.close();
 


Field Summary
protected  boolean closed
          is this stream closed?
protected  boolean haveRead
          have we read bytes from this BufferStream?
protected  boolean haveWritten
          have we written bytes to this BufferStream?
protected  int initCount
          the number of bytes available to read or write to initially (used by reset())
protected  int initStart
          the index of the array indicating the start point (used by reset())
protected  boolean isGrowable
          is the buffer growable (empty constructor)?
protected  byte[] rbuffer
          the read buffer
protected  int readAvailable
          the number of bytes available to read in the buffer
protected  int readPos
          the array position where the next byte will be read from
protected  Stream stream
          the underlying stream
protected  byte[] wbuffer
          the write buffer (often points the the same array as rbuffer)
protected  int writeAvailable
          the number of bytes of space available in the buffer to write
protected  int writePos
          the array position where the next byte will be written to
 
Constructor Summary
BufferStream()
          Constructs a new BufferStream for writing to.
BufferStream(byte[] buffer)
          Constructs a new BufferStream for reading from or writing to a given byte array.
BufferStream(byte[] buffer, int start, int count)
          Constructs a new BufferStream for reading from or writing to a segment of a given byte array.
BufferStream(Stream stream)
          Constructs a new BufferStream for buffering input and output from a given stream.
BufferStream(Stream stream, int size)
          Constructs a new BufferStream for buffering input and output from a given stream.
 
Method Summary
 boolean close()
          Closes the stream.
 int flush()
          For stream based buffers, sends any remaining data in the buffer.
 byte[] getBuffer()
          Gets the buffer.
 boolean isOpen()
          Returns true if this Stream is open and false otherwise
 int readBytes(byte[] buf, int start, int count)
          Reads bytes from the stream.
 byte[] readBytesUntil(byte b)
          Reads bytes from the stream until the stream finishes or the given byte is found.
 void reset()
          For non stream based buffers, resets the read and write positions to their initial location.
 void setBuffer(byte[] buffer)
          Sets the buffer used by this BufferStream.
 void setBuffer(byte[] buffer, int start, int count)
          Sets the buffer slice used by this BufferStream.
 int writeBytes(byte[] buf, int start, int count)
          Writes bytes to the the stream.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, toString, wait, wait
 

Field Detail

stream

protected Stream stream
the underlying stream

rbuffer

protected byte[] rbuffer
the read buffer

wbuffer

protected byte[] wbuffer
the write buffer (often points the the same array as rbuffer)

readAvailable

protected int readAvailable
the number of bytes available to read in the buffer

writeAvailable

protected int writeAvailable
the number of bytes of space available in the buffer to write

initStart

protected int initStart
the index of the array indicating the start point (used by reset())

initCount

protected int initCount
the number of bytes available to read or write to initially (used by reset())

readPos

protected int readPos
the array position where the next byte will be read from

writePos

protected int writePos
the array position where the next byte will be written to

isGrowable

protected boolean isGrowable
is the buffer growable (empty constructor)?

haveRead

protected boolean haveRead
have we read bytes from this BufferStream?

haveWritten

protected boolean haveWritten
have we written bytes to this BufferStream?

closed

protected boolean closed
is this stream closed?
Constructor Detail

BufferStream

public BufferStream()
Constructs a new BufferStream for writing to. When all the data has been written, use getBuffer() to get the completed byte array.

BufferStream

public BufferStream(byte[] buffer)
Constructs a new BufferStream for reading from or writing to a given byte array. The array will not be grown if more bytes are attempted to be written than the size of the buffer.

BufferStream

public BufferStream(byte[] buffer,
                    int start,
                    int count)
Constructs a new BufferStream for reading from or writing to a segment of a given byte array. The array will not be grown if more bytes are attempted to be written than the given count.

BufferStream

public BufferStream(Stream stream)
Constructs a new BufferStream for buffering input and output from a given stream. A default buffer size of 50 is used.
Parameters:
stream - the stream to buffer.

BufferStream

public BufferStream(Stream stream,
                    int size)
Constructs a new BufferStream for buffering input and output from a given stream.
Parameters:
stream - the stream to buffer.
size - the size of the buffer in bytes. This is the number of bytes that are read or written when it is empty or full
Method Detail

getBuffer

public byte[] getBuffer()
Gets the buffer. Only useful for BufferStreams initialised with the empty constuctor.
Returns:
null, if this is a stream based BufferStream, the original buffer passed in, if one was, or a buffer the exact size of the number of bytes written to it, if the empty constructor was used.

setBuffer

public void setBuffer(byte[] buffer)
Sets the buffer used by this BufferStream. If the buffer is null, a growable array is used.
Parameters:
buffer - the buffer to use.

setBuffer

public void setBuffer(byte[] buffer,
                      int start,
                      int count)
Sets the buffer slice used by this BufferStream. If the buffer is null, a growable array is used.
Parameters:
buffer - the buffer to use.
start - the start position of the buffer
count - the number of bytes to access

readBytesUntil

public byte[] readBytesUntil(byte b)
Reads bytes from the stream until the stream finishes or the given byte is found.
Parameters:
b - the byte to look for
Returns:
a byte array containing all the bytes up to but not including the wanted byte.

readBytes

public int readBytes(byte[] buf,
                     int start,
                     int count)
Reads bytes from the stream. Returns the number of bytes actually read or -1 if an error prevented the read operation from occurring.
Overrides:
readBytes in class Stream
Parameters:
buf - the byte array to read data into
start - the start position in the array
count - the number of bytes to read

writeBytes

public int writeBytes(byte[] buf,
                      int start,
                      int count)
Writes bytes to the the stream. Returns the number of bytes actually written or -1 if an error prevented the write operation from occurring.
Overrides:
writeBytes in class Stream
Parameters:
buf - the byte array to write data from
start - the start position in the byte array
count - the number of bytes to write

flush

public int flush()
For stream based buffers, sends any remaining data in the buffer. You must call this before closing the underlying stream or some data may be lost.
Returns:
the number of bytes flushed down the stream, or -1 if a write error occured

reset

public void reset()
For non stream based buffers, resets the read and write positions to their initial location. The actual data is not reset.

close

public boolean close()
Closes the stream. Returns true if the operation is successful and false otherwise.
Overrides:
close in class Stream

isOpen

public boolean isOpen()
Description copied from class: Stream
Returns true if this Stream is open and false otherwise
Overrides:
isOpen in class Stream