Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD