Interface TerminalProvider

All Known Implementing Classes:
DumbTerminalProvider, ExecTerminalProvider, JniTerminalProvider
public interface TerminalProvider
Service provider interface for terminal implementations.

The TerminalProvider interface defines the contract for classes that can create and manage terminal instances on specific platforms. Each provider implements platform-specific terminal functionality, allowing JLine to work across different operating systems and environments.

JLine includes several built-in terminal providers:

  • FFM - Foreign Function Memory (Java 22+) based implementation
  • JNI - Java Native Interface based implementation
  • Jansi - Implementation based on the Jansi library
  • JNA - Java Native Access based implementation
  • Exec - Implementation using external commands
  • Dumb - Fallback implementation with limited capabilities

Terminal providers are loaded dynamically using the load(String) method, which looks up provider implementations in the classpath based on their name.

See Also:

  • Method Details

    • name

      String name()
      Returns the name of this terminal provider.

      The provider name is a unique identifier that can be used to request this specific provider when creating terminals. Common provider names include "ffm", "jni", "jansi", "jna", "exec", and "dumb".

      Returns:
      the name of this terminal provider

    • sysTerminal

      @Deprecated default Terminal sysTerminal(String name, String type, boolean ansiPassThrough, Charset encoding, boolean nativeSignals, Terminal.SignalHandler signalHandler, boolean paused, SystemStream systemStream) throws IOException
      Deprecated.
      Use sysTerminal(String, String, boolean, Charset, Charset, Charset, Charset, boolean, Terminal.SignalHandler, boolean, SystemStream) instead
      Creates a terminal connected to a system stream.

      This method creates a terminal that is connected to one of the standard system streams (standard input, standard output, or standard error). Such terminals typically represent the actual terminal window or console that the application is running in.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      ansiPassThrough - whether to pass through ANSI escape sequences
      encoding - the character encoding to use
      nativeSignals - whether to use native signal handling
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      systemStream - the system stream to connect to
      Returns:
      a new terminal connected to the specified system stream
      Throws:
      IOException - if an I/O error occurs

    • sysTerminal

      default Terminal sysTerminal(String name, String type, boolean ansiPassThrough, Charset encoding, Charset inputEncoding, Charset outputEncoding, boolean nativeSignals, Terminal.SignalHandler signalHandler, boolean paused, SystemStream systemStream) throws IOException
      Creates a terminal connected to a system stream.

      This method creates a terminal that is connected to one of the standard system streams (standard input, standard output, or standard error). Such terminals typically represent the actual terminal window or console that the application is running in.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      ansiPassThrough - whether to pass through ANSI escape sequences
      encoding - the general character encoding to use
      inputEncoding - the character encoding to use for input
      outputEncoding - the character encoding to use for output
      nativeSignals - whether to use native signal handling
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      systemStream - the system stream to connect to
      Returns:
      a new terminal connected to the specified system stream
      Throws:
      IOException - if an I/O error occurs

    • sysTerminal

      @Deprecated Terminal sysTerminal(String name, String type, boolean ansiPassThrough, Charset encoding, Charset stdinEncoding, Charset stdoutEncoding, Charset stderrEncoding, boolean nativeSignals, Terminal.SignalHandler signalHandler, boolean paused, SystemStream systemStream) throws IOException
      Deprecated.
      Use sysTerminal(String, String, boolean, Charset, Charset, Charset, boolean, Terminal.SignalHandler, boolean, SystemStream) instead
      Creates a terminal connected to a system stream.

      This method creates a terminal that is connected to one of the standard system streams (standard input, standard output, or standard error). Such terminals typically represent the actual terminal window or console that the application is running in.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      ansiPassThrough - whether to pass through ANSI escape sequences
      encoding - the general character encoding to use
      stdinEncoding - the character encoding to use for standard input
      stdoutEncoding - the character encoding to use for standard output
      stderrEncoding - the character encoding to use for standard error
      nativeSignals - whether to use native signal handling
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      systemStream - the system stream to connect to
      Returns:
      a new terminal connected to the specified system stream
      Throws:
      IOException - if an I/O error occurs

    • newTerminal

      @Deprecated default Terminal newTerminal(String name, String type, InputStream masterInput, OutputStream masterOutput, Charset encoding, Terminal.SignalHandler signalHandler, boolean paused, Attributes attributes, Size size) throws IOException
      Deprecated.
      Use newTerminal(String, String, InputStream, OutputStream, Charset, Charset, Charset, Charset, Terminal.SignalHandler, boolean, Attributes, Size) instead
      Creates a new terminal with custom input and output streams.

      This method creates a terminal that is connected to the specified input and output streams. Such terminals can be used for various purposes, such as connecting to remote terminals over network connections or creating virtual terminals for testing.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      masterInput - the input stream to read from
      masterOutput - the output stream to write to
      encoding - the character encoding to use
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      attributes - the initial terminal attributes
      size - the initial terminal size
      Returns:
      a new terminal connected to the specified streams
      Throws:
      IOException - if an I/O error occurs

    • newTerminal

      default Terminal newTerminal(String name, String type, InputStream masterInput, OutputStream masterOutput, Charset encoding, Charset inputEncoding, Charset outputEncoding, Terminal.SignalHandler signalHandler, boolean paused, Attributes attributes, Size size) throws IOException
      Creates a new terminal with custom input and output streams.

      This method creates a terminal that is connected to the specified input and output streams. Such terminals can be used for various purposes, such as connecting to remote terminals over network connections or creating virtual terminals for testing.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      masterInput - the input stream to read from
      masterOutput - the output stream to write to
      encoding - the general character encoding to use
      inputEncoding - the character encoding to use for input
      outputEncoding - the character encoding to use for output
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      attributes - the initial terminal attributes
      size - the initial terminal size
      Returns:
      a new terminal connected to the specified streams
      Throws:
      IOException - if an I/O error occurs

    • newTerminal

      @Deprecated Terminal newTerminal(String name, String type, InputStream masterInput, OutputStream masterOutput, Charset encoding, Charset stdinEncoding, Charset stdoutEncoding, Charset stderrEncoding, Terminal.SignalHandler signalHandler, boolean paused, Attributes attributes, Size size) throws IOException
      Deprecated.
      Use newTerminal(String, String, InputStream, OutputStream, Charset, Charset, Charset, Terminal.SignalHandler, boolean, Attributes, Size) instead
      Creates a new terminal with custom input and output streams.

      This method creates a terminal that is connected to the specified input and output streams. Such terminals can be used for various purposes, such as connecting to remote terminals over network connections or creating virtual terminals for testing.

      Parameters:
      name - the name of the terminal
      type - the terminal type (e.g., "xterm", "dumb")
      masterInput - the input stream to read from
      masterOutput - the output stream to write to
      encoding - the general character encoding to use
      stdinEncoding - the character encoding to use for standard input
      stdoutEncoding - the character encoding to use for standard output
      stderrEncoding - the character encoding to use for standard error
      signalHandler - the signal handler to use
      paused - whether the terminal should start in a paused state
      attributes - the initial terminal attributes
      size - the initial terminal size
      Returns:
      a new terminal connected to the specified streams
      Throws:
      IOException - if an I/O error occurs

    • isSystemStream

      boolean isSystemStream(SystemStream stream)
      Checks if the specified system stream is available on this platform.

      This method determines whether the specified system stream (standard input, standard output, or standard error) is available for use on the current platform. Some platforms or environments may restrict access to certain system streams.

      Parameters:
      stream - the system stream to check
      Returns:
      true if the system stream is available, false otherwise

    • systemStreamName

      String systemStreamName(SystemStream stream)
      Returns the name of the specified system stream on this platform.

      This method returns a platform-specific name or identifier for the specified system stream. The name may be used for display purposes or for accessing the stream through platform-specific APIs.

      Parameters:
      stream - the system stream
      Returns:
      the name of the system stream on this platform

    • systemStreamWidth

      int systemStreamWidth(SystemStream stream)
      Returns the width (number of columns) of the specified system stream.

      This method determines the width of the terminal associated with the specified system stream. The width is measured in character cells and represents the number of columns available for display.

      Parameters:
      stream - the system stream
      Returns:
      the width of the system stream in character columns

    • getConsoleCodepage

      default int getConsoleCodepage()
      Returns the Windows console output codepage.

      On Windows, this method returns the console output codepage (equivalent to GetConsoleOutputCP()). On non-Windows platforms, or if the codepage cannot be determined, this method returns -1.

      Returns:
      the console output codepage, or -1 if not available

    • load

      static TerminalProvider load(String name) throws IOException
      Loads a terminal provider with the specified name.

      Provider Discovery Mechanism

      This method loads a terminal provider implementation based on its name by reading a provider-specific resource file at META-INF/jline/providers/[name] which contains the fully qualified class name of the provider implementation.

      This on-demand loading approach is used instead of ServiceLoader because it allows loading a specific provider by name without instantiating all available providers. This is critical for providers that may fail to initialize due to missing native libraries (JNI, FFM) or other platform-specific dependencies.

      Dual-Purpose Service Files

      JLine maintains two types of service registration files:

      • META-INF/services/org.jline.terminal.spi.TerminalProvider - Standard Java SPI files required by jlink and JPMS module tools to discover service implementations and establish proper module dependencies. These files are not used at runtime by JLine.
      • META-INF/jline/providers/[name] - Provider-specific files used by this method for efficient runtime loading. Each file contains the class name of a single provider and allows loading by provider name without scanning all available providers.

      File Format

      The provider file format follows standard Java SPI conventions:

      • One fully qualified class name per line
      • Comments start with # and extend to end of line
      • Blank lines and whitespace are ignored

      Example: META-INF/jline/providers/ffm

      # JLine FFM Terminal Provider
org.jline.terminal.impl.ffm.FfmTerminalProvider
      Parameters:
      name - the name of the provider to load (e.g., "ffm", "jni", "exec", "dumb")
      Returns:
      the loaded terminal provider
      Throws:
      IOException - if the provider cannot be loaded or is not found