Package org.jline.utils

Class NonBlockingInputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    NonBlockingInputStreamImpl, NonBlockingPumpInputStream
    public abstract class NonBlockingInputStream
extends java.io.InputStream
    An input stream that supports non-blocking read operations with timeouts.

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

    This 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

    This abstract class provides the framework for non-blocking input operations, with concrete implementations handling the details of how the non-blocking behavior is achieved (e.g., through NIO, separate threads, or native methods).

    Non-blocking input streams are 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.

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void checkClosed()
      Checks if this input stream has been closed.
      void close()
      Closes this input stream 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()
      Reads the next byte of data from the input stream.
      int read​(byte[] b, int off, int len)  
      int read​(long timeout)
      Attempts to read a character from the input stream for a specific period of time.
      abstract int read​(long timeout, boolean isPeek)  
      int readBuffered​(byte[] b)  
      int readBuffered​(byte[] b, int off, int len, long timeout)  
      int readBuffered​(byte[] b, long timeout)  
      void shutdown()
      Shuts down the thread that is handling blocking I/O if any.

      • Methods inherited from class java.io.InputStream

        available, mark, markSupported, nullInputStream, read, readAllBytes, readNBytes, readNBytes, reset, skip, transferTo

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • closed

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

    • Constructor Detail

      • NonBlockingInputStream

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

    • Method Detail

      • checkClosed

        protected void checkClosed()
                    throws java.io.IOException
        Checks if this input stream has been closed.

        In JLine 3.x, warn mode is enabled by default: when a closed input stream 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 input stream has been closed and strict mode is enabled
        java.io.IOException

      • read

        public int read()
         throws java.io.IOException
        Reads the next byte of data from the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
        Specified by:
        read in class java.io.InputStream
        Returns:
        the next byte of data, or -1 if the end of the stream is reached.
        Throws:
        java.io.IOException - if an I/O error occurs.

      • peek

        public int peek​(long timeout)
         throws java.io.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:
        java.io.IOException - if an I/O error occurs.

      • read

        public int read​(long timeout)
         throws java.io.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:
        java.io.IOException - if an I/O error occurs.

      • read

        public int read​(byte[] b,
                int off,
                int len)
         throws java.io.IOException
        Overrides:
        read in class java.io.InputStream
        Throws:
        java.io.IOException

      • readBuffered

        public int readBuffered​(byte[] b)
                 throws java.io.IOException
        Throws:
        java.io.IOException

      • readBuffered

        public int readBuffered​(byte[] b,
                        long timeout)
                 throws java.io.IOException
        Throws:
        java.io.IOException

      • readBuffered

        public int readBuffered​(byte[] b,
                        int off,
                        int len,
                        long timeout)
                 throws java.io.IOException
        Throws:
        java.io.IOException

      • shutdown

        public void shutdown()
        Shuts down the thread that is handling blocking I/O if any. Note that if the thread is currently blocked waiting for I/O it may not actually shut down until the I/O is received.

      • read

        public abstract int read​(long timeout,
                         boolean isPeek)
                  throws java.io.IOException
        Throws:
        java.io.IOException

      • close

        public void close()
           throws java.io.IOException
        Closes this input stream 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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.InputStream
        Throws:
        java.io.IOException - if an I/O error occurs