Interface TerminalProvider

  • All Known Implementing Classes:
    DumbTerminalProvider, ExecTerminalProvider

    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
    • Exec - Implementation using external commands
    • Dumb - Fallback-only implementation with limited capabilities (not included in default provider order)

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

    See Also:
    Terminal, TerminalBuilder
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default int getConsoleCodepage()
      Retrieve the Windows console output code page.
      boolean isSystemStream​(SystemStream stream)
      Checks if the specified system stream is available on this platform.
      static TerminalProvider load​(java.lang.String name)
      Loads a terminal provider with the specified name using the default classloader resolution strategy.
      static TerminalProvider load​(java.lang.String name, java.lang.ClassLoader classLoader)
      Loads a terminal provider with the specified name, using an optional explicit classloader.
      java.lang.String name()
      Returns the name of this terminal provider.
      Terminal newTerminal​(java.lang.String name, java.lang.String type, java.io.InputStream masterInput, java.io.OutputStream masterOutput, java.nio.charset.Charset encoding, java.nio.charset.Charset inputEncoding, java.nio.charset.Charset outputEncoding, Terminal.SignalHandler signalHandler, boolean paused, Attributes attributes, Size size)
      Creates a new terminal with custom input and output streams.
      default java.lang.Object registerDefaultSignal​(java.lang.String signal)
      Registers the default handler for the specified signal.
      default java.lang.Object registerSignal​(java.lang.String signal, java.lang.Runnable handler)
      Registers a handler for the specified signal.
      java.lang.String systemStreamName​(SystemStream stream)
      Returns the name of the specified system stream on this platform.
      int systemStreamWidth​(SystemStream stream)
      Returns the width (number of columns) of the specified system stream.
      default Terminal sysTerminal​(java.lang.String name, java.lang.String type, boolean ansiPassThrough, java.nio.charset.Charset encoding, java.nio.charset.Charset inputEncoding, java.nio.charset.Charset outputEncoding, boolean nativeSignals, Terminal.SignalHandler signalHandler, boolean paused)
      Creates a terminal connected to the controlling terminal device (/dev/tty).
      Terminal sysTerminal​(java.lang.String name, java.lang.String type, boolean ansiPassThrough, java.nio.charset.Charset encoding, java.nio.charset.Charset inputEncoding, java.nio.charset.Charset outputEncoding, boolean nativeSignals, Terminal.SignalHandler signalHandler, boolean paused, SystemStream systemStream)
      Creates a terminal connected to a system stream.
      default void unregisterSignal​(java.lang.String signal, java.lang.Object registration)
      Unregisters a previously registered signal handler, restoring the prior handler.
    • Method Detail

      • name

        java.lang.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", "exec", and "dumb".

        Returns:
        the name of this terminal provider
      • sysTerminal

        Terminal sysTerminal​(java.lang.String name,
                             java.lang.String type,
                             boolean ansiPassThrough,
                             java.nio.charset.Charset encoding,
                             java.nio.charset.Charset inputEncoding,
                             java.nio.charset.Charset outputEncoding,
                             boolean nativeSignals,
                             Terminal.SignalHandler signalHandler,
                             boolean paused,
                             SystemStream systemStream)
                      throws java.io.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 (only used on Windows)
        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 (only used on Windows)
        systemStream - the system stream to connect to
        Returns:
        a new terminal connected to the specified system stream
        Throws:
        java.io.IOException - if an I/O error occurs
      • sysTerminal

        default Terminal sysTerminal​(java.lang.String name,
                                     java.lang.String type,
                                     boolean ansiPassThrough,
                                     java.nio.charset.Charset encoding,
                                     java.nio.charset.Charset inputEncoding,
                                     java.nio.charset.Charset outputEncoding,
                                     boolean nativeSignals,
                                     Terminal.SignalHandler signalHandler,
                                     boolean paused)
                              throws java.io.IOException
        Creates a terminal connected to the controlling terminal device (/dev/tty).

        This method creates a terminal using the process's controlling terminal, bypassing the standard system streams (stdin, stdout, stderr). This is useful when all standard streams are redirected (e.g., when running via Maven's exec-maven-plugin with the exec:exec goal) but the controlling terminal is still available.

        The default implementation throws UnsupportedOperationException. Providers that support this functionality (e.g., the exec provider on POSIX systems) should override this method.

        Parameters:
        name - the name of the terminal
        type - the terminal type (e.g., "xterm", "dumb")
        ansiPassThrough - whether to pass through ANSI escape sequences (only used on Windows)
        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 (only used on Windows)
        Returns:
        a new terminal connected to the controlling terminal
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if this provider does not support creating a terminal from the controlling terminal device
      • newTerminal

        Terminal newTerminal​(java.lang.String name,
                             java.lang.String type,
                             java.io.InputStream masterInput,
                             java.io.OutputStream masterOutput,
                             java.nio.charset.Charset encoding,
                             java.nio.charset.Charset inputEncoding,
                             java.nio.charset.Charset outputEncoding,
                             Terminal.SignalHandler signalHandler,
                             boolean paused,
                             Attributes attributes,
                             Size size)
                      throws java.io.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:
        java.io.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

        java.lang.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()
        Retrieve the Windows console output code page. On Windows this returns the console output code page; on non-Windows platforms or when the code page cannot be determined this returns -1.
        Returns:
        the console output code page, or -1 if not available
      • registerSignal

        default java.lang.Object registerSignal​(java.lang.String signal,
                                                java.lang.Runnable handler)
        Registers a handler for the specified signal. Providers may override this to use platform-specific signal handling.
        Parameters:
        signal - the signal name (e.g., "INT", "WINCH")
        handler - the callback to run when the signal is received
        Returns:
        an opaque registration object suitable for use with unregisterSignal(String, Object)
      • registerDefaultSignal

        default java.lang.Object registerDefaultSignal​(java.lang.String signal)
        Registers the default handler for the specified signal.
        Parameters:
        signal - the signal name (e.g., "INT", "WINCH")
        Returns:
        an opaque registration object for use with unregisterSignal(java.lang.String, java.lang.Object)
      • load

        static TerminalProvider load​(java.lang.String name)
                              throws java.io.IOException
        Loads a terminal provider with the specified name using the default classloader resolution strategy.

        This is equivalent to calling load(name, null).

        Parameters:
        name - the name of the provider to load (e.g., "ffm", "jni", "exec", "dumb")
        Returns:
        the loaded terminal provider
        Throws:
        java.io.IOException - if the provider cannot be loaded or is not found
        See Also:
        load(String, ClassLoader)
      • load

        static TerminalProvider load​(java.lang.String name,
                                     java.lang.ClassLoader classLoader)
                              throws java.io.IOException
        Loads a terminal provider with the specified name, using an optional explicit classloader.

        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.

        Classloader Resolution

        The classloader used for provider discovery is resolved in this order:

        1. The explicit classLoader parameter, if non-null
        2. The thread's context classloader
        3. The classloader that loaded the TerminalProvider class itself

        Each classloader is tried in order until the provider resource file is found. This fallback chain ensures provider discovery works in environments with non-standard classloader hierarchies, such as OSGi containers, application servers, and plugin systems that load JLine through a child classloader that is not the thread's context classloader.

        The explicit classloader can be set via TerminalBuilder.classLoader(ClassLoader).

        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")
        classLoader - an explicit classloader to try first, or null to use the default resolution strategy (context classloader, then JLine's own classloader)
        Returns:
        the loaded terminal provider
        Throws:
        java.io.IOException - if the provider cannot be loaded or is not found