de.caff.io

## Class InputStreamBuffer

- java.lang.Object
- - de.caff.io.InputStreamBuffer

- All Implemented Interfaces:
    java.lang.Runnable

      public class InputStreamBuffer
      extends java.lang.Object
      implements java.lang.Runnable

  A sink for data from an input stream which collects the incoming data.

  It is especially useful for handling the outputting streams of `Process`. Create via `startOn(InputStream)` or `startOn(InputStream, int)` which will automatically collect all bytes from the stream in a background thread.

  See `InputStreamSink` if you are not interested in the content of the streams, and `InputStreamPipe` which forwards all bytes from one stream to another.

  Since:
    August 10, 2022
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAXIMUM_ARRAY_SIZE` This is suggestion from OpenJDK's ArraySupport class which makes sure to work with all Java versions.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `InputStreamBuffer(java.io.InputStream is, int maxSize)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearOutput()` Clear the output.
    `byte[]` | `getBinaryOutput()` Get the collected output as binary data.
    `java.io.IOException` | `getError()` Return a possible error which happened during reading the stream when using the `run()` method.
    `java.lang.String` | `getOutput()` Get the output as text, using the default charset.
    `java.lang.String` | `getOutput(java.nio.charset.Charset charset)` Get the output as text, using the given charset Note that due to limited buffer size for multi-byte encodings such as UTF-8 the first characters may be broken.
    `long` | `getTotalByteCount()` Get the total number of bytes read by this sink.
    `void` | `run()` When an object implementing interface `Runnable` is used to create a thread, starting the thread causes the object's `run` method to be called in that separately executing thread.
    `static InputStreamBuffer` | `startOn(java.io.InputStream inStream)` Start a buffer on the given stream.
    `static InputStreamBuffer` | `startOn(java.io.InputStream inStream, int bufferSize)` Start a buffer on the given stream.
    `java.lang.String` | `toString()`

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

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

- - ### Field Detail

    - #### MAXIMUM_ARRAY_SIZE

          public static final int MAXIMUM_ARRAY_SIZE

      This is suggestion from OpenJDK's ArraySupport class which makes sure to work with all Java versions.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### InputStreamBuffer

          public InputStreamBuffer(@NotNull
                                   java.io.InputStream is,
                                   int maxSize)

      Constructor.

      Note that in most use cases the factory methods `startOn(InputStream)` and `startOn(InputStream, int)` are better ways to create an input stream sink.

      Parameters:
        `is` - input stream
        `maxSize` - maximum buffer size

  - ### Method Detail

    - #### getError

          @Nullable
          public java.io.IOException getError()

      Return a possible error which happened during reading the stream when using the `run()` method.
      Returns:
        error caught during run() or `null`, if no error was caught

    - #### getBinaryOutput

          @NotNull
          public byte[] getBinaryOutput()

      Get the collected output as binary data.
      Returns:
        byte array with the collected bytes

    - #### getOutput

          @NotNull
          public java.lang.String getOutput()

      Get the output as text, using the default charset. Note that due to limited buffer size for multi-byte encodings such as UTF-8 the first characters may be broken.
      Returns:
        stream output as text

    - #### getOutput

          @NotNull
          public java.lang.String getOutput(@NotNull
                                                     java.nio.charset.Charset charset)

      Get the output as text, using the given charset Note that due to limited buffer size for multi-byte encodings such as UTF-8 the first characters may be broken.
      Parameters:
        `charset` - charset to use for decoding the binary output
      Returns:
        stream output as text

    - #### clearOutput

          public void clearOutput()

      Clear the output. This will remove all cached bytes from the buffer.

    - #### getTotalByteCount

          public long getTotalByteCount()

      Get the total number of bytes read by this sink.
      Returns:
        total number of bytes read so far

    - #### run

          public void run()

      When an object implementing interface `Runnable` is used to create a thread, starting the thread causes the object's `run` method to be called in that separately executing thread.

      The general contract of the method `run` is that it may take any action whatsoever.

      Specified by:
        `run` in interface `java.lang.Runnable`
      See Also:
        `Thread.run()`

    - #### startOn

          @NotNull
          public static InputStreamBuffer startOn(@NotNull
                                                           java.io.InputStream inStream)

      Start a buffer on the given stream. This method uses `MAXIMUM_ARRAY_SIZE` as size for the ring buffer.
      Parameters:
        `inStream` - input stream
      Returns:
        input stream buffer

    - #### startOn

          @NotNull
          public static InputStreamBuffer startOn(@NotNull
                                                           java.io.InputStream inStream,
                                                           int bufferSize)

      Start a buffer on the given stream.
      Parameters:
        `inStream` - input stream
        `bufferSize` - maximum number of cached bytes
      Returns:
        input stream buffer

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`