de.caff.io

## Class InputStreamLineBuffer

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

- All Implemented Interfaces:
    java.lang.Runnable

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

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

  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 `InputStreamBuffer` if you are interested in the raw bytes, `InputStreamSink` if you are not interested at all 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` | `DEFAULT_BUFFER_SIZE` Default size for line buffers.
    `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
    `InputStreamLineBuffer(java.io.InputStream is, int maxSize)` Constructor using the system's default charset.
    `InputStreamLineBuffer(java.io.InputStream is, int maxSize, java.nio.charset.Charset charset)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearOutput()` Clear the output.
    `java.io.IOException` | `getError()` Return a possible error which happened during reading the stream when using the `run()` method.
    `java.lang.String[]` | `getLines()` Get the collected output lines.
    `java.lang.String` | `getOutput()` Get the output as text, using the default charset.
    `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 InputStreamLineBuffer` | `startOn(java.io.InputStream inStream)` Start a sink on the given stream.
    `static InputStreamLineBuffer` | `startOn(java.io.InputStream inStream, int bufferSize)` Start a sink on the given stream.
    `Indexable<java.lang.String>` | `toLineIndexable()` Get the buffered lines as an independent indexable.
    `java.util.List<java.lang.String>` | `toLineList()` Get the buffered lines as an independent indexable.
    `java.lang.String` | `toString()`
    `Indexable<java.lang.String>` | `viewLines()` Get a view to the buffered lines.

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

    - #### DEFAULT_BUFFER_SIZE

          public static final int DEFAULT_BUFFER_SIZE

      Default size for line buffers.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### InputStreamLineBuffer

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

      Constructor using the system's default charset.

      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 number of buffered lines, implementation might store one line more

    - #### InputStreamLineBuffer

          public InputStreamLineBuffer(@NotNull
                                       java.io.InputStream is,
                                       int maxSize,
                                       @NotNull
                                       java.nio.charset.Charset charset)

      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 number of buffered lines, implementation might store one line more
        `charset` - charset used to decode the input stream

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

    - #### viewLines

          @NotNull
          public Indexable<java.lang.String> viewLines()

      Get a view to the buffered lines. Note that this does not copy the lines, but has the disadvantage that the view will become invalid as soon as more data is written to this buffer. If the input is not close prefer `toLineIndexable()`, `toLineList()`, or `getLines()`.
      Returns:
        lines
      See Also:
        `toLineIndexable()`, `toLineList()`, `getLines()`

    - #### toLineIndexable

          @NotNull
          public Indexable<java.lang.String> toLineIndexable()

      Get the buffered lines as an independent indexable.
      Returns:
        buffered lines
      See Also:
        `viewLines()`, `toLineList()`, `getLines()`

    - #### toLineList

          @NotNull
          public java.util.List<java.lang.String> toLineList()

      Get the buffered lines as an independent indexable.
      Returns:
        buffered lines
      See Also:
        `viewLines()`, `toLineIndexable()`, `getLines()`

    - #### getLines

          @NotNull
          public java.lang.String[] getLines()

      Get the collected output lines.
      Returns:
        byte array with the collected bytes
      See Also:
        `viewLines()`, `toLineIndexable()`, `toLineList()`

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

    - #### 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 InputStreamLineBuffer startOn(@NotNull
                                                               java.io.InputStream inStream)

      Start a sink on the given stream. This method uses `DEFAULT_BUFFER_SIZE` as buffer size.
      Parameters:
        `inStream` - input stream
      Returns:
        input stream line buffer based on the given stream
      See Also:
        `startOn(InputStream, int)`

    - #### startOn

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

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

    - #### toString

          public java.lang.String toString()

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