Interface Connection

All Superinterfaces:
Appendable, AutoCloseable
All Known Implementing Classes:
AbstractConnection
public interface Connection extends Appendable, AutoCloseable
Represent a connection to either a local/direct/remote Terminal.

This interface provides core I/O operations: input/output handlers, encoding, lifecycle (open/close), and terminal state (attributes, size).

Advanced terminal features (queries, capability detection, semantic output, mode toggles) are accessible via terminal(), which returns a TerminalFeatures object.

Author:
Ståle W. Pedersen

  • Method Details

    • device

      Device device()
      Get the device associated with this connection.
      Returns:
      type of terminal

    • size

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

    • stdinHandler

      Consumer<int[]> stdinHandler()
      Get the standard input handler.
      Returns:
      the stdin handler that processes input as code point arrays

    • setStdinHandler

      void setStdinHandler(Consumer<int[]> handler)
      Set the standard input handler.
      Parameters:
      handler - the handler to process input as code point arrays

    • supportsNonBlockingRead

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

      When this returns true, peek(long) provides timeout-based peek using platform-native mechanisms. When false, peek is not available and callers should use the event-driven setStdinHandler(Consumer) API instead.

      Returns:
      true if non-blocking reads are supported

    • peek

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

      Returns the byte value (0-255), -1 for EOF, or Terminal.READ_EXPIRED (-2) if the timeout expires. The byte remains available for subsequent reads. Only available when supportsNonBlockingRead() returns true.

      This is used by the ActionDecoder for escape sequence timeout disambiguation: after seeing ESC, peek with a short timeout to determine if more bytes are coming (escape sequence) or not (bare ESC).

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

    • stdoutHandler

      Consumer<int[]> stdoutHandler()
      Handler that's called for all output.
      Returns:
      output handler

    • write

      default Connection write(String s)
      Write a string to the output handler. When the stdout handler is an Encoder, this uses a fast path that encodes the String directly to bytes without an intermediate int[] allocation.
      Parameters:
      s - string
      Returns:
      this connection

    • put

      boolean put(Capability capability, Object... params)
      Specify terminal settings.
      Parameters:
      capability - capability
      params - parameters
      Returns:
      true if the terminal accepted the settings

    • signalHandler

      Consumer<Signal> signalHandler()
      Get the signal handler.
      Returns:
      handler that's called when a Signal is sent to the terminal

    • setSignalHandler

      void setSignalHandler(Consumer<Signal> handler)
      Specify the signal handler.
      Parameters:
      handler - signal handler

    • sizeHandler

      Consumer<Size> sizeHandler()
      Get the size handler.
      Returns:
      handler that's called when the terminal changes size

    • setSizeHandler

      void setSizeHandler(Consumer<Size> handler)
      Specify size handler that's called when the terminal changes size.
      Parameters:
      handler - the size change handler

    • closeHandler

      Consumer<Void> closeHandler()
      Get the close handler.
      Returns:
      handler that's called when the input stream is closed

    • setCloseHandler

      void setCloseHandler(Consumer<Void> closeHandler)
      Specify handler that's called when the input stream is closed.
      Parameters:
      closeHandler - handler

    • setThemeChangeHandler

      default void setThemeChangeHandler(Consumer<org.aesh.terminal.detect.TerminalTheme> handler)
      Set a handler to be called when the terminal's theme changes.
      Parameters:
      handler - the handler to invoke with the new theme, or null to remove

    • themeChangeHandler

      default Consumer<org.aesh.terminal.detect.TerminalTheme> themeChangeHandler()
      Get the current theme change handler.
      Returns:
      the theme change handler, or null if not set

    • setMouseHandler

      default void setMouseHandler(Consumer<MouseEvent> handler)
      Set a handler to be called when mouse events are received.

      Mouse tracking must be explicitly enabled via MouseTracking for the terminal to send mouse events.

      Parameters:
      handler - the handler to invoke with mouse events, or null to remove
      See Also:

    • mouseHandler

      default Consumer<MouseEvent> mouseHandler()
      Get the current mouse event handler.
      Returns:
      the mouse handler, or null if not set

    • setFocusHandler

      default void setFocusHandler(Consumer<Boolean> handler)
      Set the handler for terminal focus events.

      When set, the terminal will report focus gained (true) and focus lost (false) events. Focus tracking must be enabled by sending ESC [ ? 1004 h to the terminal.

      Parameters:
      handler - the focus handler, or null to disable

    • focusHandler

      default Consumer<Boolean> focusHandler()
      Get the current focus event handler.
      Returns:
      the focus handler, or null if not set

    • printAbove

      default void printAbove(String text)
      Print text above the current prompt without disrupting the user's input.

      When a readline session is active, the prompt and buffer are erased, the text is printed, and the prompt and buffer are redrawn with the cursor restored to its original position. This is thread-safe and can be called from any thread.

      When no readline session is active, the text is simply written to the terminal output followed by a newline.

      Parameters:
      text - the text to print above the prompt

    • setPrintAboveHandler

      default void setPrintAboveHandler(Consumer<String> handler)
      Set the handler for printAbove(String) calls.

      This is typically set by the readline implementation during an active readline session, and cleared when the session ends.

      Parameters:
      handler - the handler, or null to disable

    • printAboveHandler

      default Consumer<String> printAboveHandler()
      Get the current printAbove handler.
      Returns:
      the handler, or null if not set

    • registerStatusLine

      default StatusLine registerStatusLine(int priority)
      Register a persistent status line displayed between scrolling output and the prompt.

      Status lines are rendered in priority order: lowest priority at top, highest priority at bottom (closest to the prompt). They persist across printAbove(String) calls and are redrawn automatically.

      If multiple status lines share the same priority, they are ordered by registration time.

      Parameters:
      priority - the display priority (higher = closer to prompt)
      Returns:
      a new StatusLine that can be updated or closed

    • splitScreen

      default SplitScreen splitScreen(double ratio)
      Split the terminal screen into two independently scrolling regions.

      The top region (created by the split) occupies the specified fraction of the screen. The bottom region (the original/main area) is where readline continues to operate.

      The returned ScreenRegion is the new top region. Write to it to display output (logs, monitoring data, etc.) that scrolls independently from the readline prompt.

      Experimental API — this feature is under active development and the API may change.

      Parameters:
      ratio - fraction of the screen for the top region (0.0-1.0), e.g. 0.67 for top 2/3
      Returns:
      the new top ScreenRegion
      Throws:
      IllegalArgumentException - if ratio results in regions smaller than SplitScreen.MIN_REGION_HEIGHT
      UnsupportedOperationException - if split screen is not supported

    • splitScreen

      default SplitScreen splitScreen()
      Returns the current split screen manager, or null if not split.
      Returns:
      the SplitScreen, or null

    • setCurrentRegion

      default void setCurrentRegion(ScreenRegion region)
      Set the current/active screen region for output routing.

      When set, write(String) routes output to this region. When null or when no split is active, write goes to the terminal directly (default behavior).

      Parameters:
      region - the region to route output to, or null for default

    • currentRegion

      default ScreenRegion currentRegion()
      Get the current/active screen region.
      Returns:
      the current region, or null if not split

    • openBlocking

      void openBlocking()
      Start reading from the input stream using the current thread. The current thread will be blocked while reading/waiting to read from the stream.

    • openNonBlocking

      void openNonBlocking()
      Start reading from the input stream in a separate thread. The current thread will continue.

    • reading

      default boolean reading()
      Check if the connection is actively reading from the input stream.
      Returns:
      true if the connection is actively reading input

    • close

      void close()
      Stop reading from the input stream. The stream will be closed and cleanup methods will be called. Eg for terminals they will be restored to their original settings.
      Specified by:
      close in interface AutoCloseable

    • close

      default void close(int exit)
      Close the connection with an exit code.
      Parameters:
      exit - the exit code

    • attributes

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

    • setAttributes

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

    • enterRawMode

      default Attributes enterRawMode()
      Enter raw mode for the terminal.

      In raw mode, input is not line-buffered, echo is disabled, and special character processing is turned off.

      Returns:
      the previous terminal attributes (to restore later)

    • supportsAnsi

      boolean supportsAnsi()
      Check if this terminal supports ANSI escape sequences.
      Returns:
      true if ANSI is supported, false otherwise

    • isInteractive

      default boolean isInteractive()
      Check if this connection is interactive (connected to a real terminal).

      For local terminal connections, this checks if stdin is connected to a TTY (not piped or redirected). For SSH and HTTP connections, this always returns true since those are inherently interactive.

      Use this to decide whether to enable interactive features like prompts, completion, colors, and history navigation.

      Returns:
      true if the connection is interactive, false if piped/redirected

    • inputEncoding

      Charset inputEncoding()
      Get the input character encoding.
      Returns:
      the charset used for input encoding

    • outputEncoding

      Charset outputEncoding()
      Get the output character encoding.
      Returns:
      the charset used for output encoding

    • append

      default Appendable append(char c)
      Specified by:
      append in interface Appendable

    • append

      default Appendable append(CharSequence csq)
      Specified by:
      append in interface Appendable

    • append

      default Appendable append(CharSequence csq, int start, int end)
      Specified by:
      append in interface Appendable

    • terminal

      default TerminalFeatures terminal()
      Access advanced terminal features: queries, capability detection, semantic output, and mode management.
      Returns:
      the terminal features for this connection

    • asWriter

      default Writer asWriter()
      Return a Writer view of this connection. Writes to the returned Writer are forwarded to this connection's output.
      Returns:
      a Writer that delegates to this connection

    • asPrintWriter

      default PrintWriter asPrintWriter()
      Return a PrintWriter view of this connection. Useful for formatted output (printf, println, etc.).
      Returns:
      a PrintWriter that delegates to this connection