com.gc.iotools.stream.os
Class OutputStreamToInputStream<T>

java.lang.Object
  java.io.OutputStream
      com.gc.iotools.stream.os.OutputStreamToInputStream<T>

Type Parameters:

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

All Implemented Interfaces:

Closeable, Flushable

public abstract class OutputStreamToInputStream<T>
extends OutputStream

This class is an OutputStream that, when extended, allows to read the data written to it from the InputStream inside the method #doRead().

To use this class you must extend it and implement the method #doRead(). Inside this method place the logic that needs to read the data from the InputStream. Then the data can be written to this class that implements OutputStream.

The #doRead() 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() you shouldn't change the variables of the outer class.

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:

 OutputStreamToInputStream<String> oStream2IStream = 
 new OutputStreamToInputStream<String>() {
        protected String doRead(final InputStream istream) throws Exception {
                // read from InputStream into a string. Data will be written to the 
                // outer class later (oStream2IStream.write). 
                final String result = IOUtils.toString(istream);
                return result + " was processed.";
        }
 };
 try {
        // some data is written to the OutputStream, will be passed to the method
        // doRead(InputStream 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.0

Author:

dvd.smnt

Constructor Summary

OutputStreamToInputStream()
Creates a new OutputStreamToInputStream.

OutputStreamToInputStream(boolean joinOnClose, ExecutionModel executionModel)
Creates a new OutputStreamToInputStream.

OutputStreamToInputStream(boolean joinOnClose, ExecutorService executorService)

Method Summary

void	close()
void	close(long timeout, TimeUnit tu)
protected abstract T	doRead(InputStream istream) This method has to be implemented to use this class.
void	flush()
T	getResults() This method returns the result of the method doRead(InputStream) and ensure the previous method is over.
static void	setDefaultBufferSize(int defaultPipeSize) Set the size for the pipe circular buffer.
void	write(byte[] bytes)
void	write(byte[] bytes, int offset, int length)
void	write(int bytetowr)

Methods inherited from class java.lang.Object

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

Constructor Detail

OutputStreamToInputStream

public OutputStreamToInputStream()
                          throws IOException

Creates a new OutputStreamToInputStream. It uses the default ExecutionModel.THREAD_PER_INSTANCE thread instantiation strategy. This means that a new thread is created for every instance of OutputStreamToInputStream.

When the close() method is called this class wait for the internal thread to terminate.

Throws:

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

OutputStreamToInputStream

public OutputStreamToInputStream(boolean joinOnClose,
                                 ExecutionModel executionModel)
                          throws IOException

Creates a new OutputStreamToInputStream. 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 - Strategy for allocating threads.

Throws:

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

See Also:

ExecutionModel

OutputStreamToInputStream

public OutputStreamToInputStream(boolean joinOnClose,
                                 ExecutorService executorService)
                          throws IOException

Parameters:

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

executorService - Service for executing the internal thread.

Throws:

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

Method Detail

setDefaultBufferSize

public static void setDefaultBufferSize(int defaultPipeSize)

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

Parameters:

defaultPipeSize - The default pipe buffer size in bytes.

Since:

1.2.0

close

public final void close()
                 throws IOException

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException

close

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

Parameters:

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

tu - Time unit for the timeout.

Throws:

IOException

InterruptedException

ExecutionException

TimeoutException - threw if timeout expires.

flush

public final void flush()
                 throws IOException

Specified by:

flush in interface Flushable

Overrides:

flush in class OutputStream

Throws:

IOException

getResults

public final T getResults()
                   throws InterruptedException,
                          ExecutionException

This method returns the result of the method doRead(InputStream) and ensure the previous method is over.

This method suspend the calling thread and waits for the function doRead(InputStream) 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(InputStream) threw an Exception. The getCause() returns the original Exception.

IllegalStateException - When it is called before the method close() has been called.

write

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

Overrides:

write in class OutputStream

Throws:

IOException

write

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

Overrides:

write in class OutputStream

Throws:

IOException

write

public final void write(int bytetowr)
                 throws IOException

Specified by:

write in class OutputStream

Throws:

IOException

doRead

protected abstract T doRead(InputStream istream)
                     throws Exception

This method has to be implemented to use this class. It allows to retrieve the data written to the outer OutputStream from the InputStream passed as a parameter.

Parameters:

istream - The InputStream where the data can be retrieved.

Returns:

Optionally returns a result of the elaboration.

Throws:

Exception - If an Exception occurs during the elaboration it can be thrown. Will be returned in the method getResults().