Package org.dellroad.stuff.io

Class NullModemOutputStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

org.dellroad.stuff.io.NullModemOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class NullModemOutputStream
extends FilterOutputStream

Presents an OutputStream interface given a ReadCallback that can read from an InputStream.

A background process, initated by a provided Executor, invokes the ReadCallback to read from an InputStream which receives whatever is written to this OutputStream.

Exceptions

Regarding this OutputStream:

• If the ReadCallback throws an IOException, any subsequent write to this OutputStream will throw an IOException, with the original appended to it.
• If the ReadCallback close()'es the InputStream, any subsequent write to this OutputStream will generate an IOException.

The InputStream provided to the ReadCallback should never throw any IOException, as long as it is still open.

Synchronous Close

Normally, an OutputStream will not return from close() until all data has been written out (e.g., to a destination file). However, due to internal buffering, it's possible to flush and close a NullModemOutputStream before the reader thread has finished actually reading that data. Therefore, the guarantee normally provided by close() that all of the data has been flushed and "reached its destination" (so to speak) is lost. To prevent this scenario, use setSynchronousClose(true) prior to close(), which will force close() to block until the reader thread has finished reading and returned from readFrom().

Since:

1.0.82

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

Constructor	Description
NullModemOutputStream(ReadCallback reader, String threadName)	Constructor that uses a background thread for reading.
NullModemOutputStream(ReadCallback reader, Executor executor)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	close()
void	flush()
protected PipedStreams	getPipedStreams()	Get the PipedStreams associated with this instance.
boolean	isSynchronousClose()	Get whether close() should block until the reader has finished reading (or thrown an exception).
void	setSynchronousClose(boolean synchronousClose)	Set whether close() should block until the reader has finished reading (or thrown an exception).
protected void	waitForReader()
void	write(byte[] b)
void	write(byte[] b, int off, int len)
void	write(int b)

Methods inherited from class java.io.OutputStream

nullOutputStream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

NullModemOutputStream

public NullModemOutputStream(ReadCallback reader,
 String threadName)

Constructor that uses a background thread for reading.

Delegates to NullModemOutputStream(ReadCallback, Executor), passing an executor that creates a dedicated daemon Thread with the given name.

Parameters:

reader - callback that reads the data written

threadName - name for the background thread to be created

NullModemOutputStream

public NullModemOutputStream(ReadCallback reader,
 Executor executor)

Constructor.

The reader's readFrom() method will be invoked (once) in an asynchronous thread created by executor. The InputStream provided to it will produce whatever data is written to this instance.

Parameters:

reader - callback that reads the data written

executor - executes reading process in the background

Throws:

IllegalArgumentException - if any parameter is null

Method Details

isSynchronousClose

public boolean isSynchronousClose()

Get whether close() should block until the reader has finished reading (or thrown an exception).

Default is false.

Returns:

true if close() should block until the reader has finished, otherwise false

setSynchronousClose

public void setSynchronousClose(boolean synchronousClose)

Set whether close() should block until the reader has finished reading (or thrown an exception).

Parameters:

synchronousClose - true to make close() block until the reader finishes, false to make it return immediately

write

public void write(int b)
           throws IOException

Overrides:

write in class FilterOutputStream

Throws:

IOException

write

public void write(byte[] b)
           throws IOException

Overrides:

write in class FilterOutputStream

Throws:

IOException

write

public void write(byte[] b,
 int off,
 int len)
           throws IOException

Overrides:

write in class FilterOutputStream

Throws:

IOException

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Overrides:

flush in class FilterOutputStream

Throws:

IOException

close

public void close()
           throws IOException

If synchronous close is enabled, this method will block until the reader thread has finished reading (or thrown an exception). Otherwise, this method returns immediately.

If the current thread is interrupted during a synchronous close, an IOException is thrown.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class FilterOutputStream

Throws:

IOException

See Also:

• isSynchronousClose()

waitForReader

protected void waitForReader()
                      throws InterruptedException

Throws:

InterruptedException

getPipedStreams

protected PipedStreams getPipedStreams()

Get the PipedStreams associated with this instance.

Returns:

the underlying PipedStreams