Class NonBlockingReader

java.lang.Object
java.io.Reader
org.jline.utils.NonBlockingReader
All Implemented Interfaces:
Closeable, AutoCloseable, Readable
Direct Known Subclasses:
NonBlockingPumpReader, NonBlockingReaderImpl
public abstract class NonBlockingReader extends Reader
A reader that provides non-blocking read operations.

The NonBlockingReader class extends the standard Reader class to provide non-blocking read operations. Unlike standard readers, which block until data is available or the end of the stream is reached, non-blocking readers can be configured to return immediately or after a specified timeout if no data is available.

This class is particularly useful for terminal applications that need to perform other tasks while waiting for user input, or that need to implement features like input timeouts or polling.

The class defines two special return values:

  • EOF (-1) - Indicates that the end of the stream has been reached
  • READ_EXPIRED (-2) - Indicates that the read operation timed out

Implementations of this class typically use a separate thread to handle blocking I/O operations, allowing the main thread to continue execution. The shutdown() method can be used to terminate this background thread when it is no longer needed.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    closed
    Flag indicating whether this reader has been closed.
    static final int
    EOF
     
    static final int
    READ_EXPIRED
     

    Fields inherited from class Reader

    lock

  • Constructor Summary

    Constructors
    Constructor
    Description
    NonBlockingReader()
    Default constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    available()
     
    protected void
    checkClosed()
    Checks if this reader has been closed.
    void
    close()
    Closes this reader and marks it as closed.
    int
    peek(long timeout)
    Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
    int
    read()
     
    int
    read(char[] b, int off, int len)
    This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
    int
    read(long timeout)
    Attempts to read a character from the input stream for a specific period of time.
    protected abstract int
    read(long timeout, boolean isPeek)
    Attempts to read a character from the input stream for a specific period of time.
    int
    readBuffered(char[] b)
     
    abstract int
    readBuffered(char[] b, int off, int len, long timeout)
     
    int
    readBuffered(char[] b, long timeout)
     
    void
    shutdown()
    Shuts down the thread that is handling blocking I/O.

    Methods inherited from class Reader

    mark, markSupported, nullReader, of, read, read, readAllAsString, readAllLines, ready, reset, skip, transferTo

    Methods inherited from class Object

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

  • Field Details

    • EOF

      public static final int EOF
      See Also:

    • READ_EXPIRED

      public static final int READ_EXPIRED
      See Also:

    • closed

      protected volatile boolean closed
      Flag indicating whether this reader has been closed. Marked as volatile to ensure visibility across threads.

  • Constructor Details

    • NonBlockingReader

      public NonBlockingReader()
      Default constructor. Initializes close mode based on the current value of the system property.

  • Method Details

    • checkClosed

      protected void checkClosed() throws IOException
      Checks if this reader has been closed.

      In JLine 3.x, warn mode is enabled by default: when a closed reader is accessed, it logs a WARNING instead of throwing an exception. This allows existing code to continue working while alerting developers to the issue.

      The behavior can be controlled via the system property PROP_CLOSE_MODE:

      • "strict" - Throw ClosedException
      • "warn" - Log a warning but continue (default in JLine 3.x)
      • "lenient" - Silently allow access (no warning, no exception)
      Throws:
      ClosedException - if this reader has been closed and strict mode is enabled
      IOException

    • shutdown

      public void shutdown()
      Shuts down the thread that is handling blocking I/O.

      This method terminates the background thread that is used to handle blocking I/O operations. This allows the application to clean up resources and prevent thread leaks when the reader is no longer needed.

      Note that if the thread is currently blocked waiting for I/O, it will not actually shut down until the I/O is received or the thread is interrupted. In some implementations, this method may interrupt the thread to force it to shut down immediately.

      After calling this method, the reader should not be used anymore, as subsequent read operations may fail or block indefinitely.

    • read

      public int read() throws IOException
      Overrides:
      read in class Reader
      Throws:
      IOException

    • peek

      public int peek(long timeout) throws IOException
      Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
      Parameters:
      timeout - The amount of time to wait, 0 == forever
      Returns:
      -1 on eof, -2 if the timeout expired with no available input or the character that was read (without consuming it).
      Throws:
      IOException - if anything wrong happens

    • read

      public int read(long timeout) throws IOException
      Attempts to read a character from the input stream for a specific period of time.
      Parameters:
      timeout - The amount of time to wait for the character
      Returns:
      The character read, -1 if EOF is reached, or -2 if the read timed out.
      Throws:
      IOException - if anything wrong happens

    • read

      public int read(char[] b, int off, int len) throws IOException
      This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
      Specified by:
      read in class Reader
      Parameters:
      b - the buffer
      off - the offset in the buffer
      len - the maximum number of chars to read
      Throws:
      IOException - if anything wrong happens

    • readBuffered

      public int readBuffered(char[] b) throws IOException
      Throws:
      IOException

    • readBuffered

      public int readBuffered(char[] b, long timeout) throws IOException
      Throws:
      IOException

    • readBuffered

      public abstract int readBuffered(char[] b, int off, int len, long timeout) throws IOException
      Throws:
      IOException

    • available

      public int available()

    • read

      protected abstract int read(long timeout, boolean isPeek) throws IOException
      Attempts to read a character from the input stream for a specific period of time.
      Parameters:
      timeout - The amount of time to wait for the character
      isPeek - trueif the character read must not be consumed
      Returns:
      The character read, -1 if EOF is reached, or -2 if the read timed out.
      Throws:
      IOException - if anything wrong happens

    • close

      public void close() throws IOException
      Closes this reader and marks it as closed.

      Subsequent read operations behavior depends on the PROP_CLOSE_MODE setting:

      • "strict" - Throw ClosedException
      • "warn" - Log a warning but continue (default in JLine 3.x)
      • "lenient" - Silently allow access
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in class Reader
      Throws:
      IOException - if an I/O error occurs