Package org.aesh.terminal

Interface Connection

All Superinterfaces:
AutoCloseable
public interface Connection extends AutoCloseable
Represent a connection to either a local/direct/remote Terminal.
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

    • getSizeHandler

      Consumer<Size> getSizeHandler()
      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

    • getSignalHandler

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

    • setSignalHandler

      void setSignalHandler(Consumer<Signal> handler)
      Specify the signal handler. A handler that's called when a Signal is sent to the terminal
      Parameters:
      handler - signal handler

    • getStdinHandler

      Consumer<int[]> getStdinHandler()
      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

    • stdoutHandler

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

    • setCloseHandler

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

    • getCloseHandler

      Consumer<Void> getCloseHandler()
      Get the close handler.
      Returns:
      handler thats called when the input stream is closed.

    • 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. Note that if the reader thread is blocking waiting for data it will wait until either killed or if the input stream is closed.
      Specified by:
      close in interface AutoCloseable

    • close

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

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

    • put

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

    • getAttributes

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

    • setAttributes

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

    • 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

    • supportsAnsi

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

    • write

      default Connection write(String s)
      Write a string to the output handler
      Parameters:
      s - string
      Returns:
      this connection

    • 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. This allows reading individual keystrokes as they are typed.

      Returns:
      the previous terminal attributes (to restore later)

    • getCursorPosition

      default Point getCursorPosition()
      Get the current cursor position in the terminal.

      This method sends a cursor position query to the terminal and waits for the response. The terminal must be actively reading input for this to work.

      Returns:
      the current cursor position as a Point (row, column)

    • queryTerminal

      default <T> T queryTerminal(String query, long timeoutMs, Function<int[],T> responseParser)
      Send a query to the terminal and wait for a response with timeout.

      This method enters raw mode, sends the query, collects the response, and restores the original terminal attributes. It's useful for OSC queries and other terminal interrogation sequences.

      Note: This method requires the connection to be actively reading input (via openBlocking() or openNonBlocking()).

      Type Parameters:
      T - the type of the parsed response
      Parameters:
      query - the query sequence to send
      timeoutMs - timeout in milliseconds to wait for response
      responseParser - function to parse the response; should return non-null when a complete response is received, null to continue waiting
      Returns:
      the parsed response, or null if timeout or parsing failed

    • supportsOscQueries

      default boolean supportsOscQueries()
      Check if OSC (Operating System Command) queries are supported.

      This checks both the device type and environment variables to determine if OSC queries like color detection are likely to work.

      Returns:
      true if OSC queries are likely supported

    • getColorDepth

      default ColorDepth getColorDepth()
      Get the color depth of this terminal connection.

      This method uses the device's max_colors capability if available, otherwise falls back to environment variable detection.

      Returns:
      the detected color depth

    • getColorCapability

      default TerminalColorCapability getColorCapability()
      Get the color capabilities of this terminal connection.

      This is a fast, non-blocking operation that uses environment variables and terminfo data. For more accurate color detection including background theme detection via OSC queries, use the TerminalColorDetector class in the readline module.

      Returns:
      the detected color capabilities