net.sf.okapi.common.io

## Class InputStreamFromOutputStream<T>

- java.lang.Object
- - java.io.InputStream
  - - java.io.PipedInputStream
    - - net.sf.okapi.common.io.InputStreamFromOutputStream<T>

- Type Parameters:
    `T` - Optional result returned by the function produce(OutputStream) after the data has been written. It can be obtained calling the getResult()
  All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public abstract class InputStreamFromOutputStream<T>
      extends java.io.PipedInputStream

  This class allow to read the data written to an OutputStream from an InputStream.

  To use this class you must subclass it and implement the abstract method produce(OutputStream). The data who is produced inside this function can be written to the sink `OutputStream` passed as a parameter. Later it can be read back from from the `InputStreamFromOutputStream` class (whose ancestor is `java.io.InputStream` ).

       final String dataId=//id of some data.
       final InputStreamFromOutputStream<String> isos
                                = new InputStreamFromOutputStream<String>() {
         @Override
         public String produce(final OutputStream dataSink) throws Exception {
            //call your application function who produces the data here
            //WARNING: we're in another thread here, so this method shouldn't
            //write any class field or make assumptions on the state of the class.
            return produceMydata(dataId,dataSink)
         }
       };
        try {
          //now you can read from the InputStream the data that was written to the
          //dataSink OutputStream
           byte[] read=IOUtils.toByteArray(isos);
           //Use data here
         } catch (final IOException e) {
           //Handle exception here
         } finally {
         isos.close();
       }
       //You can get the result of produceMyData after the stream has been closed.
       String resultOfProduction = isos.getResult();

  This class encapsulates a pipe and a `Thread`, hiding the complexity of using them. It is possible to select different strategies for allocating the internal thread or even specify the ExecutorService for thread execution.

  Since:
    1.0
  Author:
    dvd.smnt

- - ### Field Summary

    - ### Fields inherited from class java.io.PipedInputStream

      `buffer, in, out, PIPE_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `InputStreamFromOutputStream()` Creates a `InputStreamFromOutputStream` with a THREAD_PER_INSTANCE thread strategy.
    `InputStreamFromOutputStream(boolean startImmediately)`

  - ### 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()`
    `static java.lang.String[]` | `getActiveThreadNames()` This method can be used for debugging purposes to get a list of the currently active threads.
    `T` | `getResult()` Returns the object that was previously returned by the produce(OutputStream) method.
    `protected abstract T` | `produce(java.io.OutputStream sink)` This method must be implemented by the user of this class to produce the data that must be read from the external `InputStream`.
    `int` | `read()`
    `int` | `read(byte[] b, int off, int len)`
    `static void` | `setDefaultPipeSize(int defaultPipeSize)` Set the size for the pipe circular buffer for the newly created `InputStreamFromOutputStream`.

    - ### Methods inherited from class java.io.PipedInputStream

      `available, connect, receive`

    - ### Methods inherited from class java.io.InputStream

      `mark, markSupported, read, reset, skip`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### InputStreamFromOutputStream

          public InputStreamFromOutputStream()

      Creates a `InputStreamFromOutputStream` with a THREAD_PER_INSTANCE thread strategy.

    - #### InputStreamFromOutputStream

          public InputStreamFromOutputStream(boolean startImmediately)

  - ### Method Detail

    - #### getActiveThreadNames

          public static final java.lang.String[] getActiveThreadNames()

      This method can be used for debugging purposes to get a list of the currently active threads.
      Returns:
        Array containing names of the threads currently active.

    - #### setDefaultPipeSize

          public static void setDefaultPipeSize(int defaultPipeSize)

      Set the size for the pipe circular buffer for the newly created `InputStreamFromOutputStream`. Default is 4096 bytes.
      Parameters:
        `defaultPipeSize` - the default pipe buffer size in bytes.
      Since:
        1.2.2

    - #### afterClose

          protected void afterClose()
                             throws java.io.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 `InputStream` is closed.

      Throws:
        `java.io.IOException` - threw when the subclass wants to communicate an exception during close.
      Since:
        1.2.9

    - #### close

          public final void close()
                           throws java.io.IOException

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.PipedInputStream`
      Throws:
        `java.io.IOException`

    - #### getResult

          public T getResult()
                      throws java.lang.Exception

      Returns the object that was previously returned by the produce(OutputStream) method. It performs all the synchronization operations needed to read the result and waits for the internal thread to terminate.

      This method must be called after the method close(), otherwise an IllegalStateException is thrown.

      Returns:
        Object that was returned by the produce(OutputStream) method.
      Throws:
        `java.lang.Exception` - If the produce(OutputStream) method threw an java.lang.Exception this method will throw again the same exception.
        `java.lang.IllegalStateException` - If the close() method hasn't been called yet.
      Since:
        1.2.0

    - #### produce

          protected abstract T produce(java.io.OutputStream sink)
                                throws java.lang.Exception

      This method must be implemented by the user of this class to produce the data that must be read from the external `InputStream`.

      Special care must be paid passing arguments to this method or setting global fields because it is executed in another thread.

      The right way to set a field variable is to return a value in the `produce`and retrieve it in the getResult().

      Parameters:
        `sink` - the implementing class should write its data to this stream.
      Returns:
        The implementing class can use this to return a result of data production. The result will be available through the method getResult().
      Throws:
        `java.lang.Exception` - the exception eventually thrown by the implementing class is returned by the read() methods.
      See Also:
        `getResult()`

    - #### read

          public final int read()
                         throws java.io.IOException

      Overrides:
        `read` in class `java.io.PipedInputStream`
      Throws:
        `java.io.IOException`

    - #### read

          public final int read(byte[] b,
                 int off,
                 int len)
                         throws java.io.IOException

      Overrides:
        `read` in class `java.io.PipedInputStream`
      Throws:
        `java.io.IOException`