Package org.jline.utils

Class NonBlockingReader

java.lang.Object

java.io.Reader

org.jline.utils.NonBlockingReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable

Direct Known Subclasses:

NonBlockingPumpReader, NonBlockingReaderImpl

public abstract class NonBlockingReader
extends java.io.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 int	EOF
static int	READ_EXPIRED

Fields inherited from class java.io.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 java.io.Reader

mark, markSupported, nullReader, read, read, ready, reset, skip, transferTo

Methods inherited from class java.lang.Object

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

Field Detail

EOF

public static final int EOF

See Also:

Constant Field Values

READ_EXPIRED

public static final int READ_EXPIRED

See Also:

Constant Field Values

closed

protected volatile boolean closed

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

Constructor Detail

NonBlockingReader

public NonBlockingReader()

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

java.io.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 java.io.IOException

Overrides:

read in class java.io.Reader

Throws:

java.io.IOException

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 anything wrong happens

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 anything wrong happens

read

public int read(char[] b,
                int off,
                int len)
         throws java.io.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 java.io.Reader

Parameters:

b - the buffer

off - the offset in the buffer

len - the maximum number of chars to read

Throws:

java.io.IOException - if anything wrong happens

readBuffered

public int readBuffered(char[] b)
                 throws java.io.IOException

Throws:

java.io.IOException

readBuffered

public int readBuffered(char[] b,
                        long timeout)
                 throws java.io.IOException

Throws:

java.io.IOException

readBuffered

public abstract int readBuffered(char[] b,
                                 int off,
                                 int len,
                                 long timeout)
                          throws java.io.IOException

Throws:

java.io.IOException

available

public int available()

read

protected abstract int read(long timeout,
                            boolean isPeek)
                     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

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:

java.io.IOException - if anything wrong happens

close

public void close()
           throws java.io.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 java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Specified by:

close in class java.io.Reader

Throws:

java.io.IOException - if an I/O error occurs