Package com.norconex.commons.lang.io

# Class InputStreamConsumer

java.lang.Object
java.lang.Thread
com.norconex.commons.lang.io.InputStreamConsumer

All Implemented Interfaces:
  `Runnable`

public class InputStreamConsumer extends Thread
A stream consumer will read all it can from a stream in its own thread. This is often required by some processes/operating systems in order to prevent application freeze. For example, this is a way to capture the STDOUT and STDERR from a process. This class also allows to "listen" to what is being read. Listeners should not be considered thread-safe. If you share a listener between threads, make sure to have unique types to identify each one or the content being streamed from different threads can easily be mixed up in the order sent and is likely not a desired behavior.

Since:
  1.13.0

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Thread

  `Thread.Builder, Thread.State, Thread.UncaughtExceptionHandler`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_CHUNK_SIZE`

  ### Fields inherited from class java.lang.Thread

  `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InputStreamConsumer(InputStream input)`
  Constructor.
  `InputStreamConsumer(InputStream input, int chunkSize, String type, InputStreamListener... listeners)`
  Constructor.
  `InputStreamConsumer(InputStream input, String type, InputStreamListener... listeners)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `afterStreaming()`
  Invoked just after steaming ended, before the thread dies.
  `protected void`
  `beforeStreaming()`
  Invoked just before steaming begins, in a new thread.
  `static void`
  `consume(InputStream input)`
  Convenience method for creating a consumer instance and starting it.
  `static void`
  `consume(InputStream input, int chunkSize, String type, InputStreamListener... listeners)`
  Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
  `static void`
  `consume(InputStream input, String type, InputStreamListener... listeners)`
  Convenience method for creating a consumer instance and starting it.
  `static void`
  `consumeAndWait(InputStream input)`
  Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
  `static void`
  `consumeAndWait(InputStream input, int chunkSize, String type, InputStreamListener... listeners)`
  Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
  `static void`
  `consumeAndWait(InputStream input, String type, InputStreamListener... listeners)`
  Convenience method for creasing a consumer instance and starting it.
  `InputStreamListener[]`
  `getStreamListeners()`
  Returns stream listeners.
  `String`
  `getType()`
  Gets the stream type or `null` if no type was set.
  `void`
  `run()`
  `void`
  `startAndWait()`
  Starts this consumer thread and wait for it to complete before returning.

  ### Methods inherited from class java.lang.Thread

  `activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, isVirtual, join, join, join, join, ofPlatform, ofVirtual, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, sleep, start, startVirtualThread, stop, suspend, threadId, toString, yield`

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

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

- ## Field Details

  - ### DEFAULT_CHUNK_SIZE

    public static final int DEFAULT_CHUNK_SIZE
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### InputStreamConsumer

    public InputStreamConsumer(InputStream input)
    Constructor.
    Parameters:
      `input` - input stream

  - ### InputStreamConsumer

    public InputStreamConsumer(InputStream input, String type, InputStreamListener... listeners)
    Constructor.
    Parameters:
      `input` - input stream
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners

  - ### InputStreamConsumer

    public InputStreamConsumer(InputStream input, int chunkSize, String type, InputStreamListener... listeners)
    Constructor.
    Parameters:
      `input` - input stream
      `chunkSize` - how many bytes to read at once before (will also be the maximum byte array size sent to listeners)
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners

- ## Method Details

  - ### run

    public void run()
    Specified by:
      `run` in interface `Runnable`
    Overrides:
      `run` in class `Thread`

  - ### getStreamListeners

    public InputStreamListener[] getStreamListeners()
    Returns stream listeners.
    Returns:
      the listeners

  - ### getType

    public String getType()
    Gets the stream type or `null` if no type was set.
    Returns:
      the type

  - ### beforeStreaming

    protected void beforeStreaming()
    Invoked just before steaming begins, in a new thread. Default implementation does nothing. This method is for implementors.

  - ### afterStreaming

    protected void afterStreaming()
    Invoked just after steaming ended, before the thread dies. Default implementation does nothing. This method is for implementors.

  - ### startAndWait

    public void startAndWait()
    Starts this consumer thread and wait for it to complete before returning.
    Throws:
      `StreamException` - if streaming is interrupted while waiting

  - ### consume

    public static void consume(InputStream input)
    Convenience method for creating a consumer instance and starting it.
    Parameters:
      `input` - input stream to consume.

  - ### consume

    public static void consume(InputStream input, String type, InputStreamListener... listeners)
    Convenience method for creating a consumer instance and starting it.
    Parameters:
      `input` - input stream
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners

  - ### consume

    public static void consume(InputStream input, int chunkSize, String type, InputStreamListener... listeners)
    Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
    Parameters:
      `input` - input stream
      `chunkSize` - how many bytes to read at once before (will also be the maximum byte array size sent to listeners)
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners

  - ### consumeAndWait

    public static void consumeAndWait(InputStream input)
    Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
    Parameters:
      `input` - input stream to consume.

  - ### consumeAndWait

    public static void consumeAndWait(InputStream input, String type, InputStreamListener... listeners)
    Convenience method for creasing a consumer instance and starting it.
    Parameters:
      `input` - input stream
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners

  - ### consumeAndWait

    public static void consumeAndWait(InputStream input, int chunkSize, String type, InputStreamListener... listeners)
    Convenience method for creasing a consumer instance, starting it, and waiting for it to complete.
    Parameters:
      `input` - input stream
      `chunkSize` - how many bytes to read at once before (will also be the maximum byte array size sent to listeners)
      `type` - an optional way to identify each portion being read to stream listeners. Useful when listeners are shared. Can be `null`.
      `listeners` - input stream listeners