saker.util Documentation TaskDoc JavaDoc Packages
public class ReadWriteBufferOutputStream extends OutputStream implements ByteSource, ByteSink
Stream class providing reading and writing operations to an internal buffer.

The class serves as a mediator for a stream writer and stream reader. Any data that is written to the stream is buffered in an internal buffer. Reading from the buffer will remove the previously written bytes from the buffer.

The above behaviour means that a stream instance can be concurrently used by a producer and consumer thread. Any read operations will read the currently available data if any, or block until some data is written to it. When data is written, the consumer threads are notified about this and the bytes may be read.

Closing the stream will not discard previously written data from it, they may still be readable.

This class extends OutputStream, and implements ByteSource and ByteSink. To retrieve an InputStream instance, use ByteSource.toInputStream(ByteSource).

Constructors
public
Creates a new instance.
public
Creates a new instance with the argument buffer size.
Methods
public int
Gets the number of bytes that can be read without blocking.
public void
Closes this output stream and releases any system resources associated with this stream.
public int
Reads a single byte from this byte source.
public ByteArrayRegion
read(int count)
Reads a given number of bytes from this byte source.
public int
Reads bytes from this byte source and writes them to the argument buffer.
public int
read(byte[] buffer)
Reads bytes into the argument byte array, waiting for some if not available.
public int
read(byte[] buffer, int offset, int length)
Reads bytes into the argument range of the specified byte array, waiting for some if not available.
public long
Same as readFrom(ByteSource), but with an InputStream argument.
public long
Reads bytes from the argument byte source and writes it to this byte sink.
public void
write(int b)
Writes the specified byte to this output stream.
public void
Writes the bytes contained in the argument byte array to the byte sink.
public void
write(byte[] b)
Writes b.length bytes from the specified byte array to this output stream.
public void
write(byte[] b, int off, int len)
Writes len bytes from the specified byte array starting at offset off to this output stream.
public long
Same as writeTo(ByteSink), but with an OutputStream argument.
public long
Writes the remaining bytes in this byte source to the specified byte sink.
Creates a new instance.
Creates a new instance with the argument buffer size.
sizeThe buffer size.
NegativeArraySizeExceptionIf the size is negative.
public int available()
Gets the number of bytes that can be read without blocking.
The number of available bytes.
public void close()
Overridden from: OutputStream
Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened.

The close method of OutputStream does nothing.

public int read() throws IOException
Overridden from: ByteSource
Reads a single byte from this byte source.

This method works similarly to InputStream.read().

An unsigned single byte or negative if no more bytes available.
IOExceptionIn case of I/O error.
public ByteArrayRegion read(int count) throws IOException
Overridden from: ByteSource
Reads a given number of bytes from this byte source.

This method reads at most the specified number of bytes from this byte source and returns it as a byte array region. The resulting buffer may contain less than the requested number of bytes. This doesn't mean that the end of the stream has been reached, but only that reading more bytes will most likely block.

If a byte array of zero length is returned, that means that the end of the stream is reached (or the requested count was less or equal to 0).

It is recommended that the number of bytes to read is not too large, so a buffer allocated for that size will not cause OutOfMemoryError.

countThe number of bytes to read.
The bytes read from the stream.
IOExceptionIn case of I/O error.
public int read(ByteRegion buffer) throws IOException
Overridden from: ByteSource
Reads bytes from this byte source and writes them to the argument buffer.

The number of bytes read is based on the buffer length.

This method works similarly to InputStream.read(byte[], int, int).

RMI method calls to this method is redirected to ByteSource.redirectReadCall(ByteSource, ByteRegion).

bufferThe buffer to read the bytes to.
The number of bytes read and put into the buffer. Negative result means that the end of the byte source has been reached.
IOExceptionIn case of I/O error.
public int read(byte[] buffer) throws IOException, NullPointerException
Reads bytes into the argument byte array, waiting for some if not available.

If there are any available bytes in the stream, they will be copied into the buffer, and returned immediately.

Else the method will wait for bytes to be written to the stream, and will return them accordingly.

bufferThe buffer to read the bytes into.
The number of bytes read, or -1 if the stream has been closed.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the buffer is null.
public int read(byte[] buffer, int offset, int length) throws IOException, IndexOutOfBoundsException, NullPointerException
Reads bytes into the argument range of the specified byte array, waiting for some if not available.

If there are any available bytes in the stream, they will be copied into the buffer, and returned immediately.

Else the method will wait for bytes to be written to the stream, and will return them accordingly.

bufferThe buffer to read the bytes into.
offsetThe offset index where to start copying the read bytes into the buffer.
lengthThe number of bytes to read.
The number of bytes read, or -1 if the stream has been closed.
IOExceptionIn case of I/O error.
IndexOutOfBoundsExceptionIf the specified range is outside of the array.
NullPointerExceptionIf the buffer is null.
Same as readFrom(ByteSource), but with an InputStream argument.
inThe input stream.
The number of bytes read and written to this stream.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.
Overridden from: ByteSink
Reads bytes from the argument byte source and writes it to this byte sink.

This method will possibly read all bytes from the argument byte source and all the read bytes will be written to this byte sink. If the argument is a blocking source, then this method will block too.

Calling this method instead of copying the bytes externally can have advantages, as implementations can read the bytes into an internal buffer more efficiently, therefore avoiding unnecessary copying and allocations.

The default implementation calls ByteSource.writeTo(ByteSink) of the argument.

inThe byte source to read the input from.
The number of bytes read and written to this sink.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.
public void write(int b) throws IOException
Overridden from: OutputStream
Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Subclasses of OutputStream must provide an implementation for this method.

bthe byte.
IOExceptionif an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.
Overridden from: ByteSink
Writes the bytes contained in the argument byte array to the byte sink.

This method works similarly to OutputStream.write(byte[], int, int).

bufThe bytes to write.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.
public void write(byte[] b) throws IOException
Overridden from: OutputStream
Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).
bthe data.
IOExceptionif an I/O error occurs.
public void write(byte[] b, int off, int len) throws IOException
Overridden from: OutputStream
Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

The write method of OutputStream calls the write method of one argument on each of the bytes to be written out. Subclasses are encouraged to override this method and provide a more efficient implementation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

bthe data.
offthe start offset in the data.
lenthe number of bytes to write.
IOExceptionif an I/O error occurs. In particular, an IOException is thrown if the output stream is closed.
Same as writeTo(ByteSink), but with an OutputStream argument.
outThe output stream.
The number of bytes written to the output stream. Always zero or greater.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.
Writes the remaining bytes in this byte source to the specified byte sink.

This method will take the remaining bytes in this byte source and write it to the specified byte sink. It is expected that after this method finishes, reading from this byte source will not return any bytes.

Warning: This method doesn't return until the stream is closed or the current thread is interrupted, which is signaled by a thrown InterruptedIOException.

The number of bytes actually written to the sink. Always zero or greater.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.