bb.io
Interface StreamDrainer

All Superinterfaces:
Runnable
All Known Implementing Classes:
StreamDrainerForwarding, StreamDrainerForwarding.UnitTest.Crashes, StreamDrainerStoring

public interface StreamDrainer
extends Runnable

Defines methods for a type that can be used to drain InputStreams. This type extends Runnable because a dedicated thread is typically used to call run.

A given implementation instance may only be used once to drain but a single InputStream (which should have nothing else reading it). Therefore, it is an error to call init or run multiple times).

Some implementations store the bytes drained from the source InputStream, in which case this data may be read by calling getBytes. Other implementations immediately process the bytes that the drain in some other way.

Implementations must be multithread safe, because run may be called by one thread while other threads may call other methods (e.g. getBytes).

Author:
Brent Boyer

Method Summary
 byte[] getBytes()
          Returns all the bytes that have been drained by run and stored by this instance since the last time this method was called.
 Throwable getThrowable()
          Returns any Throwable caught by run while it was draining that it could not handle.
 void init(InputStream in)
          Assigns the InputStream that this instance must drain.
 void run()
          Drains the InputStream supplied to init.
 

Method Detail

init

void init(InputStream in)
          throws IllegalArgumentException,
                 IllegalStateException
Assigns the InputStream that this instance must drain.

Note that some implementations may have a constructor which takes an InputStream arg. In these cases, that constructor must call this method and the user should not subsequently call it again.

Throws:
IllegalArgumentException - if in is null
IllegalStateException - if called more than once

run

void run()
         throws IllegalStateException
Drains the InputStream supplied to init. The fate of the drained bytes is implementation dependent (see getBytes).

Other than the IllegalStateException described below, this method guarantees to never throw any Throwable once draining has started. Instead, if a Throwable is thrown that cannot be internally handled, this method guarantees to store it for future retrieval by getThrowable before aborting execution.

Specified by:
run in interface Runnable
Throws:
IllegalStateException - if init has not been called yet; this method is called more than once

getBytes

byte[] getBytes()
                throws IllegalStateException
Returns all the bytes that have been drained by run and stored by this instance since the last time this method was called.

Side effect: any stored bytes are cleared upon return.

Note: implementations are not required to store drained bytes (e.g. because they may immediately process them some other way, such as log them).

Assume that the implementation stores bytes. One usage scenario is that while one thread executes run, another thread periodically calls this method to poll for data. Alternatively, that other thread may simply wait for the thread executing run to finish, and then call this method to get all the data at once.

Returns:
all the bytes drained by run and stored since the last call of this method; the result is never null, but may be zero-length
Throws:
IllegalStateException - if run has never been called

getThrowable

Throwable getThrowable()
                       throws IllegalStateException
Returns any Throwable caught by run while it was draining that it could not handle.

Returns:
the Throwable which aborted the draining; is null if no such Throwable occurred
Throws:
IllegalStateException - if run has never been called