ReadWriteBufferOutputStream

package saker.util.io

public class ReadWriteBufferOutputStream extends OutputStream implements ByteSource, ByteSink

saker.util.io.ReadWriteBufferOutputStream

java.io.OutputStream

java.lang.Object

java.io.Closeable

java.lang.AutoCloseable

java.io.Flushable

saker.util.io.ByteSource

saker.util.io.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	ReadWriteBufferOutputStream() Creates a new instance.
public	ReadWriteBufferOutputStream(int size) Creates a new instance with the argument buffer size.

Methods

public int	available() Gets the number of bytes that can be read without blocking.
public void	close() Closes this output stream and releases any system resources associated with this stream.
public int	read() 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	read(ByteRegion buffer) 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	readFrom(InputStream in) Same as readFrom(ByteSource), but with an InputStream argument.
public long	readFrom(ByteSource in) 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	write(ByteArrayRegion buf) 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	writeTo(OutputStream out) Same as writeTo(ByteSink), but with an OutputStream argument.
public long	writeTo(ByteSink out) Writes the remaining bytes in this byte source to the specified byte sink.

Inherited methods
From: OutputStream flush
From: ByteSource skip
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

public ReadWriteBufferOutputStream()

Creates a new instance.

public ReadWriteBufferOutputStream(int size) throws NegativeArraySizeException

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.

public long readFrom(InputStream in) throws IOException, NullPointerException

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.

public long readFrom(ByteSource in) throws IOException, NullPointerException

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.

public void write(ByteArrayRegion buf) throws IOException, NullPointerException

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.

OutputStream.write(byte[], int, int)

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.

public long writeTo(OutputStream out) throws IOException, NullPointerException

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.

public long writeTo(ByteSink out) throws IOException, NullPointerException

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.