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 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 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 {
                // 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 method.
                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

Version:

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

Author:

dvd.smnt

Constructor Summary

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

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	getResults() This method returns the result of the method doRead(InputStream) 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(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()

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

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 OutputStreamToInputStream. 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 OutputStreamToInputStream. Default is 4096 bytes.

Parameters:

defaultPipeSize - The default pipe buffer size in bytes.

Since:

1.2.3

afterClose

protected void afterClose()

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.

Since:

1.2.9

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

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

InterruptedException - if the thread is interrupted.

ExecutionException - if the internal method launched an exception.

IllegalStateException - if close() was not called before.

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