Interface Terminal

All Superinterfaces:
AutoCloseable, Closeable
public interface Terminal extends Closeable
Terminal interface providing access to terminal functionality.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Terminal.SignalHandler
    Handler for terminal signals.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    READ_EXPIRED
    Return value indicating a read operation timed out without data.

  • Method Summary

    Modifier and Type
    Method
    Description
    Device
    device()
    Get the terminal device for capability queries.
    boolean
    echo()
    Get the current echo state of the terminal.
    boolean
    echo(boolean echo)
    Set the echo state of the terminal.
    Attributes
    getAttributes()
    Get the terminal attributes.
    default Consumer<int[]>
    getCodePointConsumer()
    Get the code point consumer for this terminal.
    String
    getName()
    Get the terminal name.
    Size
    getSize()
    Get the terminal size.
    Terminal.SignalHandler
    handle(Signal signal, Terminal.SignalHandler handler)
    Register a signal handler for the specified signal.
    InputStream
    input()
    Get the terminal input stream.
    OutputStream
    output()
    Get the terminal output stream.
    default int
    peek(long timeoutMs)
    Peeks at the next byte from the terminal input without consuming it.
    void
    raise(Signal signal)
    Raise a signal on this terminal.
    default int
    read(byte[] b, int off, int len, long timeoutMs)
    Reads multiple bytes from the terminal input into a buffer with a timeout.
    default int
    read(long timeoutMs)
    Reads a single byte from the terminal input with a timeout.
    void
    setAttributes(Attributes attr)
    Set the terminal attributes.
    default boolean
    supportsNonBlockingRead()
    Whether this terminal supports non-blocking read operations with timeouts.

    Methods inherited from interface Closeable

    close

  • Field Details

    • READ_EXPIRED

      static final int READ_EXPIRED
      Return value indicating a read operation timed out without data.
      See Also:

  • Method Details

    • getName

      String getName()
      Get the terminal name.
      Returns:
      the terminal name

    • handle

      Terminal.SignalHandler handle(Signal signal, Terminal.SignalHandler handler)
      Register a signal handler for the specified signal.
      Parameters:
      signal - the signal to handle
      handler - the handler to register
      Returns:
      the previous handler, or null if none

    • raise

      void raise(Signal signal)
      Raise a signal on this terminal.
      Parameters:
      signal - the signal to raise

    • input

      InputStream input()
      Get the terminal input stream.
      Returns:
      the input stream

    • output

      OutputStream output()
      Get the terminal output stream.
      Returns:
      the output stream

    • echo

      boolean echo()
      Get the current echo state of the terminal.
      Returns:
      true if echo is enabled

    • echo

      boolean echo(boolean echo)
      Set the echo state of the terminal.
      Parameters:
      echo - true to enable echo
      Returns:
      the previous echo state

    • getAttributes

      Attributes getAttributes()
      Get the terminal attributes.
      Returns:
      the terminal attributes

    • setAttributes

      void setAttributes(Attributes attr)
      Set the terminal attributes.
      Parameters:
      attr - the attributes to set

    • getSize

      Size getSize()
      Get the terminal size.
      Returns:
      the terminal size

    • device

      Device device()
      Get the terminal device for capability queries.
      Returns:
      the terminal device

    • getCodePointConsumer

      default Consumer<int[]> getCodePointConsumer()
      Get the code point consumer for this terminal.
      Returns:
      the code point consumer, or null if none

    • supportsNonBlockingRead

      default boolean supportsNonBlockingRead()
      Whether this terminal supports non-blocking read operations with timeouts.

      When this returns true, read(long) and peek(long) provide timeout-based reads using platform-native mechanisms (e.g., poll() on POSIX, WaitForSingleObject on Windows). When false, those methods fall back to blocking reads via input().

      Returns:
      true if non-blocking reads are supported

    • read

      default int read(long timeoutMs) throws IOException
      Reads a single byte from the terminal input with a timeout.

      If data is available, returns the byte value (0-255). If the end of stream is reached, returns -1. If the timeout expires with no data available, returns READ_EXPIRED (-2).

      The default implementation delegates to input().read() (blocking, ignoring the timeout). Terminals that support non-blocking reads should override this to use platform-native polling.

      Parameters:
      timeoutMs - timeout in milliseconds; 0 means non-blocking (return immediately), negative means block indefinitely
      Returns:
      the byte read (0-255), -1 for EOF, or READ_EXPIRED for timeout
      Throws:
      IOException - if an I/O error occurs

    • peek

      default int peek(long timeoutMs) throws IOException
      Peeks at the next byte from the terminal input without consuming it.

      If data is available within the timeout, returns the byte value (0-255) but leaves it available for the next read(long) call. If the end of stream is reached, returns -1. If the timeout expires with no data, returns READ_EXPIRED (-2).

      The default implementation returns READ_EXPIRED (no peek support). Terminals that support non-blocking reads should override this to provide true peek functionality.

      Parameters:
      timeoutMs - timeout in milliseconds; 0 means non-blocking
      Returns:
      the byte peeked (0-255), -1 for EOF, or READ_EXPIRED for timeout
      Throws:
      IOException - if an I/O error occurs

    • read

      default int read(byte[] b, int off, int len, long timeoutMs) throws IOException
      Reads multiple bytes from the terminal input into a buffer with a timeout.

      Reads the first byte using the specified timeout, then reads additional bytes that are immediately available (non-blocking). Returns the total number of bytes read, -1 for EOF, or READ_EXPIRED if the timeout expires with no data.

      The default implementation delegates to input().read(b, off, len) (blocking). Terminals that support non-blocking reads should override this to use platform-native polling.

      Parameters:
      b - the buffer to read into
      off - the offset in the buffer
      len - the maximum number of bytes to read
      timeoutMs - timeout in milliseconds for the first byte
      Returns:
      the number of bytes read, -1 for EOF, or READ_EXPIRED for timeout
      Throws:
      IOException - if an I/O error occurs