com.gc.iotools.stream.os

Class OutputStreamToInputStream<T>

java.lang.Object

java.io.OutputStream

java.io.PipedOutputStream

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 PipedOutputStream

This class allow to read from an InputStream the data who has been written to an OutputStream (performs an OutputStream -> InputStream conversion).

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

To use this class you must extend it and implement the method doRead(InputStream). 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. When close() method is called on the outer OutputStream an EOF is generated in the InputStream passed in the doRead(InputStream).

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

Any Exception threw inside the doRead(InputStream) method is propagated to the outer OutputStream on the next write operation.

The method getResult() 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 {
                // Users of this class should place all the code that need to read data
      // from the InputStream in this method. Data available through the
      // InputStream passed as a parameter is the data that is written to the
                // OutputStream oStream2IStream through its write() methods.
                final String result = IOUtils.toString(istream);
      //"result" is here only for example of how returning data to the external OutputStream. 
      //Real implementations might return "null" if they doesn't need to return a value.
                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.getResult();
 //result now contains the string "test was processed."
 

Since:

1.0

Author:

dvd.smnt

Constructor Summary

Constructors

Constructor and Description
OutputStreamToInputStream() Creates a new OutputStreamToInputStream.
OutputStreamToInputStream(boolean startImmediately) Creates a new OutputStreamToInputStream.
OutputStreamToInputStream(boolean startImmediately, boolean joinOnClose, ExecutorService executorService, int pipeBufferSize) Creates a new OutputStreamToInputStream.
OutputStreamToInputStream(boolean joinOnClose, ExecutionModel executionModel) Creates a new OutputStreamToInputStream.
OutputStreamToInputStream(boolean joinOnClose, ExecutorService executorService) Creates a new OutputStreamToInputStream.
OutputStreamToInputStream(boolean joinOnClose, ExecutorService executorService, int pipeBufferSize) Creates a new OutputStreamToInputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	afterClose() This method is called just before the close method completes, and after the eventual join with the internal thread.
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(InputStream istream) This method has to be implemented to use this class.
void	flush()
T	getResult() This method returns the result of the method doRead(InputStream) and ensure the previous method is over.
static void	setDefaultPipeSize(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.io.PipedOutputStream

connect

Methods inherited from class java.lang.Object

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

Constructor Detail

OutputStreamToInputStream

public OutputStreamToInputStream()

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:

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

OutputStreamToInputStream

public OutputStreamToInputStream(boolean startImmediately)

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.

If startImmediately is true the internal thread will start before the constructor completes. This is the best way if you're doing anonymous subclassing. While if you do explicit sublcassing you should set this parameter to false to allow the constructor of the superclass to complete before the threads are started.

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.

Since:

1.2.13

OutputStreamToInputStream

public OutputStreamToInputStream(boolean startImmediately,
                         boolean joinOnClose,
                         ExecutorService executorService,
                         int pipeBufferSize)

Creates a new OutputStreamToInputStream. It let the user specify the thread instantiation service and what will happen upon the invocation of close() method.

If startImmediately is true the internal thread will start before the constructor completes. This is the best way if you're doing anonymous subclassing. While if you do explicit sublcassing you should set this parameter to false to allow the constructor of the superclass to complete before the threads are started.

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:

startImmediately - if true the internal thread will start immediately after this constructor completes.

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

OutputStreamToInputStream

public OutputStreamToInputStream(boolean joinOnClose,
                         ExecutionModel executionModel)

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 - The strategy for allocating threads.

Throws:

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

See Also:

ExecutionModel

OutputStreamToInputStream

public OutputStreamToInputStream(boolean joinOnClose,
                         ExecutorService executorService)

Creates a new OutputStreamToInputStream. 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

OutputStreamToInputStream

public OutputStreamToInputStream(boolean joinOnClose,
                         ExecutorService executorService,
                         int pipeBufferSize)

Creates a new OutputStreamToInputStream. 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

setDefaultPipeSize

public static void setDefaultPipeSize(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.3

afterClose

protected void afterClose()
                   throws IOException

This method is called just before the close method completes, and after the eventual join with the internal thread.

It is an extension point designed for applications that need to perform some operation when the OutputStream is closed.

Throws:

IOException - threw when the extension point wants to launch an exception.

Since:

1.2.9

close

public final void close()
                 throws IOException

Specified by:

close in interface Closeable

Overrides:

close in class PipedOutputStream

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

Any exception eventually threw inside this method will be propagated to the external OutputStream. When the next write(byte[]) 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 InputStream 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 OutputStream and will be available calling the method #getResults().

flush

public final void flush()
                 throws IOException

Specified by:

flush in interface Flushable

Overrides:

flush in class PipedOutputStream

Throws:

IOException

getResult

public final T getResult()
                  throws Exception

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.

Exception - Thrown if the method doRead(InputStream) threw an Exception.

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 PipedOutputStream

Throws:

IOException

write

public final void write(int bytetowr)
                 throws IOException

Overrides:

write in class PipedOutputStream

Throws:

IOException