T - Type returned by the method getResults() after the
thread has finished.public abstract class WriterToReader<T> extends Writer
This class allow to read from an Reader the data who has been
written to an Writer (performs an Writer ->
Reader conversion).
More detailiy it is an Writer that, when extended, allows to
read the data written to it from the Reader inside the method
doRead(Reader).
To use this class you must extend it and implement the method
doRead(Reader). Inside this method place the logic that needs
to read the data from the Reader. Then the data can be written
to this class that implements Writer. When
close() method is called on the outer Writer an
EOF is generated in the Reader passed in the
doRead(Reader).
The doRead(Reader) call executes in another thread, so there is no warranty on when it will start and when it will end. Special care must be taken in passing variables to it: all the arguments must be final and inside doRead(Reader) you shouldn't change the variables of the outer class.
Any Exception threw inside the doRead(Reader) method is
propagated to the outer Writer on the next write
operation.
The method getResults() suspend the outer thread and wait for the
read from the internal stream is over. It returns when the
doRead() terminates and has produced its result.
Some sample code:
WriterToReader<String> oStream2Reader =
new WriterToReader<String>() {
protected String doRead(final Reader reader) throws Exception {
// Users of this class should place all the code that need to read data
// from the Reader in this method. Data available through the
// Reader passed as a parameter is the data that is written to the
// Writer oStream2Reader through its write method.
final String result = IOUtils.toString(reader);
return result + " was processed.";
}
};
try {
// some data is written to the Writer, will be passed to the method
// doRead(Reader i) above and after close() is called the results
// will be available through the getResults() method.
oStream2Reader.write("test".getBytes());
} finally {
// don't miss the close (or a thread would not terminate correctly).
oStream2Reader.close();
}
String result = oStream2Reader.getResults();
//result now contains the string "test was processed."
| Constructor and Description |
|---|
WriterToReader()
Creates a new
WriterToReader. |
WriterToReader(boolean joinOnClose,
ExecutionModel executionModel)
Creates a new
WriterToReader. |
WriterToReader(boolean joinOnClose,
ExecutorService executorService)
Creates a new
WriterToReader. |
WriterToReader(boolean joinOnClose,
ExecutorService executorService,
int pipeBufferSize)
Creates a new
WriterToReader. |
| Modifier and Type | Method and Description |
|---|---|
void |
close() |
void |
close(long timeout,
TimeUnit tu)
When this method is called the internal thread is always waited for
completion.
|
protected abstract T |
doRead(Reader reader)
This method has to be implemented to use this class.
|
void |
flush() |
T |
getResults()
This method returns the result of the method
doRead(Reader)
and ensure the previous method is over. |
static void |
setDefaultPipeSize(int defaultPipeSize)
Set the size for the pipe circular buffer.
|
void |
write(char[] bytes) |
void |
write(char[] bytes,
int offset,
int length) |
void |
write(int chartowrite) |
public WriterToReader()
Creates a new WriterToReader. It uses the default
ExecutionModel.THREAD_PER_INSTANCE thread instantiation
strategy. This means that a new thread is created for every instance of
WriterToReader.
When the close() method is called this class wait for the internal thread to terminate.
IllegalStateException - Exception thrown if pipe can't be created.public WriterToReader(boolean joinOnClose,
ExecutionModel executionModel)
Creates a new WriterToReader. It let the user specify the
thread instantiation strategy and what will happen upon the invocation
of close() method.
If joinOnClose is true when the
close() method is invoked this class will wait for the
internal thread to terminate.
joinOnClose - if true the internal thread will be joined when
close is invoked.executionModel - The strategy for allocating threads.IllegalStateException - Exception thrown if pipe can't be created.ExecutionModelpublic WriterToReader(boolean joinOnClose,
ExecutorService executorService)
Creates a new WriterToReader. It let the user specify the
thread instantiation service and what will happen upon the invocation
of close() method.
If joinOnClose is true when the
close() method is invoked this class will wait for the
internal thread to terminate.
joinOnClose - if true the internal thread will be joined when
close is invoked.executorService - Service for executing the internal thread.IllegalStateException - Exception thrown if pipe can't be created.public WriterToReader(boolean joinOnClose,
ExecutorService executorService,
int pipeBufferSize)
Creates a new WriterToReader. It let the user specify the
thread instantiation service and what will happen upon the invocation
of close() method.
If joinOnClose is true when the
close() method is invoked this class will wait for the
internal thread to terminate.
It also let the user specify the size of the pipe buffer to allocate.
joinOnClose - if true the internal thread will be joined when
close is invoked.executorService - Service for executing the internal thread.pipeBufferSize - The size of the pipe buffer to allocate.IllegalStateException - Exception thrown if pipe can't be created.public static void setDefaultPipeSize(int defaultPipeSize)
WriterToReader. Default is 4096 bytes.defaultPipeSize - The default pipe buffer size in bytes.public final void close()
throws IOException
close in interface Closeableclose in interface AutoCloseableclose in class WriterIOExceptionpublic final void close(long timeout,
TimeUnit tu)
throws IOException
timeout - maximum time to wait for the internal thread to finish.tu - Time unit for the timeout.IOException - Threw if some problem (timeout or internal exception)
occurs. see the getCause() method for the
explanation.protected abstract T doRead(Reader reader) throws Exception
This method has to be implemented to use this class. It allows to
retrieve the data written to the outer Writer from the
Reader passed as a parameter.
Any exception eventually threw inside this method will be propagated to
the external Writer. When the next
write(char[]) operation is called an
IOException will be thrown and the original exception can
be accessed calling the getCause() method on the IOException. It will
also be available by calling the method getResults().
reader - The Reader where the data can be retrieved.Exception - If an java.lang.Exception occurs during the elaboration
it can be thrown. It will be propagated to the external
Writer and will be available calling the
method getResults().public final void flush()
throws IOException
flush in interface Flushableflush in class WriterIOExceptionpublic final T getResults() throws InterruptedException, ExecutionException
This method returns the result of the method doRead(Reader)
and ensure the previous method is over.
This method suspend the calling thread and waits for the function
doRead(Reader) to finish. It returns when the
doRead() terminates and has produced its result.
It must be called after the method close() otherwise a
IllegalStateException is thrown.
InterruptedException - Thrown when the thread is interrupted.ExecutionException - Thrown if the method doRead(Reader) threw
an Exception. The getCause() returns the
original Exception.IllegalStateException - When it is called before the method close() has
been called.InterruptedException - if the running thread is interrupted.ExecutionException - if the internal method launched an exception.IllegalStateException - if close() was not called before.public final void write(char[] bytes)
throws IOException
write in class WriterIOExceptionpublic final void write(char[] bytes,
int offset,
int length)
throws IOException
write in class WriterIOExceptionpublic final void write(int chartowrite)
throws IOException
write in class WriterIOExceptionCopyright © 2008–2016. All rights reserved.