extra.io
Class BufferStream

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--extra.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();
 

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.
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, hashCode, toString

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