com.gc.iotools.stream.writer
Class WriterToReader<T>

java.lang.Object
  java.io.Writer
      com.gc.iotools.stream.writer.WriterToReader<T>

Type Parameters:

T - Type returned by the method getResults() after the thread has finished.

All Implemented Interfaces:

Closeable, Flushable, Appendable

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> oStream2IStream =
 new WriterToReader<String>() {
        protected String doRead(final Reader istream) 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 oStream2IStream through its write method.
                final String result = IOUtils.toString(istream);
                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.
        oStream2IStream.write("test".getBytes());
 } finally {
        // don't miss the close (or a thread would not terminate correctly).
        oStream2IStream.close();
 }
 String result = oStream2IStream.getResults();
 //result now contains the string "test was processed."
 

Since:

1.2.7

Version:

$Id: WriterToReader.java 463 2011-01-21 23:54:17Z dvd.smnt@gmail.com $

Author:

dvd.smnt

Field Summary

Fields inherited from class java.io.Writer

lock

Constructor Summary

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.

Method Summary

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 istream) 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	setDefaultBufferSize(int defaultPipeSize) Deprecated.
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)

Methods inherited from class java.io.Writer

append, append, append, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

WriterToReader

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.

Throws:

IllegalStateException - Exception thrown if pipe can't be created.

WriterToReader

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.

Parameters:

joinOnClose - if true the internal thread will be joined when close is invoked.

executionModel - The strategy for allocating threads.

Throws:

IllegalStateException - Exception thrown if pipe can't be created.

See Also:

ExecutionModel

WriterToReader

public 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.

Parameters:

joinOnClose - if true the internal thread will be joined when close is invoked.

executorService - Service for executing the internal thread.

Throws:

IllegalStateException - Exception thrown if pipe can't be created.

Since:

1.2.6

WriterToReader

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.

Parameters:

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.

Throws:

IllegalStateException - Exception thrown if pipe can't be created.

Since:

1.2.6

Method Detail

setDefaultBufferSize

@Deprecated
public static void setDefaultBufferSize(int defaultPipeSize)

Deprecated.

Set the size for the pipe circular buffer. This setting has effect for the newly created WriterToReader. Default is 4096 bytes.

Will be removed in the 1.3 release. Use setDefaultPipeSize(int) instead.

Parameters:

defaultPipeSize - The default pipe buffer size in bytes.

Since:

1.2.0

See Also:

setDefaultPipeSize(int)

setDefaultPipeSize

public static void setDefaultPipeSize(int defaultPipeSize)

Set the size for the pipe circular buffer. This setting has effect for the newly created WriterToReader. Default is 4096 bytes.

Parameters:

defaultPipeSize - The default pipe buffer size in bytes.

Since:

1.2.3

close

public final void close()
                 throws IOException

Specified by:

close in interface Closeable

Specified by:

close in class Writer

Throws:

IOException

close

public final void close(long timeout,
                        TimeUnit tu)
                 throws IOException

When this method is called the internal thread is always waited for completion.

Parameters:

timeout - maximum time to wait for the internal thread to finish.

tu - Time unit for the timeout.

Throws:

IOException - Threw if some problem (timeout or internal exception) occurs. see the getCause() method for the explanation.

doRead

protected abstract T doRead(Reader istream)
                     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().

Parameters:

istream - The Reader where the data can be retrieved.

Returns:

Optionally returns a result of the elaboration.

Throws:

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().

flush

public final void flush()
                 throws IOException

Specified by:

flush in interface Flushable

Specified by:

flush in class Writer

Throws:

IOException

getResults

public 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.

Returns:

the object returned from the doRead() method.

Throws:

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.

write

public final void write(char[] bytes)
                 throws IOException

Overrides:

write in class Writer

Throws:

IOException

write

public final void write(char[] bytes,
                        int offset,
                        int length)
                 throws IOException

Specified by:

write in class Writer

Throws:

IOException

write

public final void write(int chartowrite)
                 throws IOException

Overrides:

write in class Writer

Throws:

IOException