Package org.jline.terminal.impl

Class ExternalTerminal

java.lang.Object

org.jline.terminal.impl.AbstractTerminal

org.jline.terminal.impl.LineDisciplineTerminal

org.jline.terminal.impl.ExternalTerminal

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable, TerminalExt, Terminal

public class ExternalTerminal
extends LineDisciplineTerminal

Terminal implementation designed for external connections with embedded line discipline.

The ExternalTerminal class provides a terminal implementation that is well-suited for supporting incoming external connections, such as those from network sources (telnet, SSH, or other protocols). It extends the LineDisciplineTerminal class, inheriting its line discipline functionality while adding features specific to external connection handling.

This terminal implementation starts consuming input in a separate thread to generate interruption events promptly, ensuring that signals like Ctrl+C are processed immediately rather than waiting for the application to read the input. This is particularly important for network-based terminals where latency could otherwise affect the responsiveness of signal handling.

Key features of this implementation include:

• Support for external connections over various protocols
• Prompt signal handling through background input processing
• Configurable terminal type and attributes
• Support for dynamic size changes

This terminal is commonly used in server applications that need to provide terminal access to remote clients, such as SSH servers, telnet servers, or custom network protocols that require terminal emulation.

See Also:

LineDisciplineTerminal

Nested Class Summary

Nested classes/interfaces inherited from interface org.jline.terminal.Terminal

Terminal.MouseTracking, Terminal.Signal, Terminal.SignalHandler

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.concurrent.atomic.AtomicBoolean	closed
protected java.lang.Object	lock
protected java.io.InputStream	masterInput
protected boolean	paused
protected java.lang.Thread	pumpThread

Fields inherited from class org.jline.terminal.impl.LineDisciplineTerminal

attributes, masterOutput, size, skipNextLf, slaveInput, slaveInputPipe, slaveOutput, slaveReader, slaveWriter

Fields inherited from class org.jline.terminal.impl.AbstractTerminal

bools, currentMouseTracking, encoding, handlers, inputEncoding, ints, name, onClose, outputEncoding, palette, status, strings, type

Fields inherited from interface org.jline.terminal.Terminal

TYPE_DUMB, TYPE_DUMB_COLOR

Constructor Summary

Constructors

Constructor	Description
ExternalTerminal(java.lang.String name, java.lang.String type, java.io.InputStream masterInput, java.io.OutputStream masterOutput, java.nio.charset.Charset encoding)
ExternalTerminal(TerminalProvider provider, 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 stdinEncoding, java.nio.charset.Charset stdoutEncoding, java.nio.charset.Charset stderrEncoding, Terminal.SignalHandler signalHandler)
ExternalTerminal(TerminalProvider provider, 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)
ExternalTerminal(TerminalProvider provider, 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)
ExternalTerminal(TerminalProvider provider, java.lang.String name, java.lang.String type, java.io.InputStream masterInput, java.io.OutputStream masterOutput, java.nio.charset.Charset encoding, Terminal.SignalHandler signalHandler)
ExternalTerminal(TerminalProvider provider, java.lang.String name, java.lang.String type, java.io.InputStream masterInput, java.io.OutputStream masterOutput, java.nio.charset.Charset encoding, Terminal.SignalHandler signalHandler, boolean paused)
ExternalTerminal(TerminalProvider provider, java.lang.String name, java.lang.String type, java.io.InputStream masterInput, java.io.OutputStream masterOutput, java.nio.charset.Charset encoding, Terminal.SignalHandler signalHandler, boolean paused, Attributes attributes, Size size)

Method Summary

Modifier and Type	Method	Description
boolean	canPauseResume()	Whether this terminal supports Terminal.pause() and Terminal.resume() calls.
protected void	doClose()
Cursor	getCursorPosition(java.util.function.IntConsumer discarded)	Query the terminal to report the cursor position.
TerminalProvider	getProvider()	Returns the terminal provider that created this terminal.
void	pause()	Temporarily stops reading the input stream.
void	pause(boolean wait)	Stop reading the input stream and optionally wait for the underlying threads to finish.
boolean	paused()	Check whether the terminal is currently reading the input stream or not.
void	pump()
void	resume()	Resumes reading the input stream after it has been paused.

Methods inherited from class org.jline.terminal.impl.LineDisciplineTerminal

doProcessInputByte, getAttributes, getSize, getSystemStream, input, output, processInputByte, processInputBytes, processInputBytes, processIOException, processOutputByte, raise, reader, setAttributes, setSize, writer

Methods inherited from class org.jline.terminal.impl.AbstractTerminal

checkClosed, checkInterrupted, close, echo, echo, echoSignal, encoding, enterRawMode, flush, getBooleanCapability, getCurrentMouseTracking, getDefaultBackgroundColor, getDefaultForegroundColor, getKind, getName, getNumericCapability, getPalette, getStatus, getStatus, getStringCapability, getType, handle, hasFocusSupport, hasMouseSupport, inputEncoding, outputEncoding, parseInfoCmp, puts, readMouseEvent, readMouseEvent, readMouseEvent, readMouseEvent, setOnClose, toString, trackFocus, trackMouse

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jline.terminal.Terminal

getBufferSize, getHeight, getWidth, stderrEncoding, stdinEncoding, stdoutEncoding

Field Detail

closed

protected final java.util.concurrent.atomic.AtomicBoolean closed

masterInput

protected final java.io.InputStream masterInput

lock

protected final java.lang.Object lock

paused

protected boolean paused

pumpThread

protected java.lang.Thread pumpThread

Constructor Detail

ExternalTerminal

public ExternalTerminal(java.lang.String name,
                        java.lang.String type,
                        java.io.InputStream masterInput,
                        java.io.OutputStream masterOutput,
                        java.nio.charset.Charset encoding)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        java.lang.String name,
                        java.lang.String type,
                        java.io.InputStream masterInput,
                        java.io.OutputStream masterOutput,
                        java.nio.charset.Charset encoding,
                        Terminal.SignalHandler signalHandler)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        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 stdinEncoding,
                        java.nio.charset.Charset stdoutEncoding,
                        java.nio.charset.Charset stderrEncoding,
                        Terminal.SignalHandler signalHandler)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        java.lang.String name,
                        java.lang.String type,
                        java.io.InputStream masterInput,
                        java.io.OutputStream masterOutput,
                        java.nio.charset.Charset encoding,
                        Terminal.SignalHandler signalHandler,
                        boolean paused)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        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)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        java.lang.String name,
                        java.lang.String type,
                        java.io.InputStream masterInput,
                        java.io.OutputStream masterOutput,
                        java.nio.charset.Charset encoding,
                        Terminal.SignalHandler signalHandler,
                        boolean paused,
                        Attributes attributes,
                        Size size)
                 throws java.io.IOException

Throws:

java.io.IOException

ExternalTerminal

public ExternalTerminal(TerminalProvider provider,
                        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

Throws:

java.io.IOException

Method Detail

doClose

protected void doClose()
                throws java.io.IOException

Overrides:

doClose in class LineDisciplineTerminal

Throws:

java.io.IOException

canPauseResume

public boolean canPauseResume()

Description copied from interface: Terminal

Whether this terminal supports Terminal.pause() and Terminal.resume() calls.

Specified by:

canPauseResume in interface Terminal

Overrides:

canPauseResume in class AbstractTerminal

Returns:

whether this terminal supports Terminal.pause() and Terminal.resume() calls.

See Also:

Terminal.paused(), Terminal.pause(), Terminal.resume()

pause

public void pause()

Description copied from interface: Terminal

Temporarily stops reading the input stream.

This method pauses the terminal's input processing, which can be useful when transferring control to a subprocess or when the terminal needs to be in a specific state for certain operations. While paused, the terminal will not process input or handle signals that would normally be triggered by special characters in the input stream.

This method returns immediately without waiting for the terminal to actually pause. To wait until the terminal has fully paused, use Terminal.pause(boolean) with a value of true.

Example usage:

 Terminal terminal = TerminalBuilder.terminal();

 // Pause terminal input processing before running a subprocess
 terminal.pause();

 // Run subprocess that takes control of the terminal
 Process process = new ProcessBuilder("vim").inheritIO().start();
 process.waitFor();

 // Resume terminal input processing
 terminal.resume();
 

Specified by:

pause in interface Terminal

Overrides:

pause in class AbstractTerminal

See Also:

Terminal.resume(), Terminal.pause(boolean), Terminal.paused(), Terminal.canPauseResume()

pause

public void pause(boolean wait)
           throws java.lang.InterruptedException

Description copied from interface: Terminal

Stop reading the input stream and optionally wait for the underlying threads to finish.

Specified by:

pause in interface Terminal

Overrides:

pause in class AbstractTerminal

Parameters:

wait - true to wait until the terminal is actually paused

Throws:

java.lang.InterruptedException - if the call has been interrupted

resume

public void resume()

Description copied from interface: Terminal

Resumes reading the input stream after it has been paused.

This method restarts the terminal's input processing after it has been temporarily stopped using Terminal.pause() or Terminal.pause(boolean). Once resumed, the terminal will continue to process input and handle signals triggered by special characters in the input stream.

Calling this method when the terminal is not paused has no effect.

Example usage:

 Terminal terminal = TerminalBuilder.terminal();

 // Pause terminal input processing
 terminal.pause();

 // Perform operations while terminal input is paused...

 // Resume terminal input processing
 terminal.resume();
 

Specified by:

resume in interface Terminal

Overrides:

resume in class AbstractTerminal

See Also:

Terminal.pause(), Terminal.pause(boolean), Terminal.paused(), Terminal.canPauseResume()

paused

public boolean paused()

Description copied from interface: Terminal

Check whether the terminal is currently reading the input stream or not. In order to process signal as quickly as possible, the terminal need to read the input stream and buffer it internally so that it can detect specific characters in the input stream (Ctrl+C, Ctrl+D, etc...) and raise the appropriate signals. However, there are some cases where this processing should be disabled, for example when handing the terminal control to a subprocess.

Specified by:

paused in interface Terminal

Overrides:

paused in class AbstractTerminal

Returns:

whether the terminal is currently reading the input stream or not

See Also:

Terminal.pause(), Terminal.resume()

pump

public void pump()

getCursorPosition

public Cursor getCursorPosition(java.util.function.IntConsumer discarded)

Description copied from interface: Terminal

Query the terminal to report the cursor position. As the response is read from the input stream, some characters may be read before the cursor position is actually read. Those characters can be given back using org.jline.keymap.BindingReader#runMacro(String)

Specified by:

getCursorPosition in interface Terminal

Overrides:

getCursorPosition in class AbstractTerminal

Parameters:

discarded - a consumer receiving discarded characters

Returns:

null if cursor position reporting is not supported or a valid cursor position

getProvider

public TerminalProvider getProvider()

Description copied from interface: TerminalExt

Returns the terminal provider that created this terminal.

The terminal provider is responsible for creating and managing terminal instances on a specific platform. This method allows access to the provider that created this terminal, which can be useful for accessing provider-specific functionality or for creating additional terminals with the same provider.

Specified by:

getProvider in interface TerminalExt

Overrides:

getProvider in class LineDisciplineTerminal

Returns:

the TerminalProvider that created this terminal, or null if the terminal was created with no provider

See Also:

TerminalProvider