Class TerminalBuilder
Terminal
instances with flexible configuration options.
TerminalBuilder provides a fluent API for creating and configuring terminals with various characteristics. It supports multiple implementation providers and handles the complexities of terminal creation across different platforms and environments.
Terminal Providers
JLine supports multiple terminal provider implementations:
- 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
The provider selection can be controlled using the provider(String)
method or the
org.jline.terminal.provider
system property. By default, providers are tried in the
order: FFM, JNI, Jansi, JNA, Exec.
Native Library Support
When using providers that require native libraries (such as JNI, JNA, or Jansi), the appropriate
native library will be loaded automatically. The loading of these libraries is handled by
JLineNativeLoader
for the JNI provider.
The native library loading can be configured using system properties as documented in
JLineNativeLoader
.
System vs. Non-System Terminals
TerminalBuilder can create two types of terminals:
- System terminals - Connected to the actual system input/output streams
- Non-system terminals - Connected to custom input/output streams
System terminals are created using system(boolean)
with a value of true
,
while non-system terminals require specifying input and output streams using
streams(InputStream, OutputStream)
.
Usage Examples
Creating a default system terminal:
Terminal terminal = TerminalBuilder.builder() .system(true) .build();
Creating a terminal with custom streams:
Terminal terminal = TerminalBuilder.builder() .name("CustomTerminal") .streams(inputStream, outputStream) .encoding(StandardCharsets.UTF_8) .build();
Creating a terminal with a specific provider:
Terminal terminal = TerminalBuilder.builder() .system(true) .provider("jni") .build();
Creating a dumb terminal (with limited capabilities):
Terminal terminal = TerminalBuilder.builder() .dumb(true) .build();
- See Also:
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
-
Method Summary
Modifier and TypeMethodDescriptionattributes
(Attributes attributes) Attributes to use when creating a non system terminal, i.e.build()
Builds the terminal.static TerminalBuilder
builder()
Creates a new terminal builder instance for configuring and creating terminals.codepage
(int codepage) Deprecated.JLine now writes Unicode output independently from the selected code page.color
(boolean color) dumb
(boolean dumb) Enables or disables thePROP_PROVIDER_DUMB
/dumb
terminal provider.Set the encoding to use for reading/writing from the console.Set theCharset
to use for reading/writing from the console.exec
(boolean exec) Enables or disables thePROP_PROVIDER_EXEC
/exec
terminal provider.ffm
(boolean ffm) Enables or disables thePROP_PROVIDER_FFM
/ffm
terminal provider.getProviders
(String provider, IllegalStateException exception) Get the list of available terminal providers.jansi
(boolean jansi) Enables or disables thePROP_PROVIDER_JANSI
/jansi
terminal provider.jna
(boolean jna) Enables or disables thePROP_PROVIDER_JNA
/jna
terminal provider.jni
(boolean jni) Enables or disables thePROP_PROVIDER_JNI
/jni
terminal provider.nativeSignals
(boolean nativeSignals) paused
(boolean paused) Initial paused state of the terminal (defaults to false).Forces the usage of the give terminal provider.Sets the list of providers to try when creating the terminal.static void
setTerminalOverride
(Terminal terminal) Deprecated.signalHandler
(Terminal.SignalHandler signalHandler) Determines the default value for signal handlers.Initial size to use when creating a non system terminal, i.e.stderrEncoding
(String encoding) Set the encoding to use for writing to standard error.stderrEncoding
(Charset encoding) Set theCharset
to use for writing to standard error.stdinEncoding
(String encoding) Set the encoding to use for reading from standard input.stdinEncoding
(Charset encoding) Set theCharset
to use for reading from standard input.stdoutEncoding
(String encoding) Set the encoding to use for writing to standard output.stdoutEncoding
(Charset encoding) Set theCharset
to use for writing to standard output.streams
(InputStream in, OutputStream out) system
(boolean system) systemOutput
(TerminalBuilder.SystemOutput systemOutput) Indicates which standard stream should be used when displaying to the terminal.static Terminal
terminal()
Returns the default system terminal with automatic configuration.
-
Field Details
-
PROP_ENCODING
- See Also:
-
PROP_STDIN_ENCODING
- See Also:
-
PROP_STDOUT_ENCODING
- See Also:
-
PROP_STDERR_ENCODING
- See Also:
-
PROP_CODEPAGE
- See Also:
-
PROP_TYPE
- See Also:
-
PROP_PROVIDER
- See Also:
-
PROP_PROVIDERS
- See Also:
-
PROP_PROVIDER_FFM
- See Also:
-
PROP_PROVIDER_JNI
- See Also:
-
PROP_PROVIDER_JANSI
- See Also:
-
PROP_PROVIDER_JNA
- See Also:
-
PROP_PROVIDER_EXEC
- See Also:
-
PROP_PROVIDER_DUMB
- See Also:
-
PROP_PROVIDERS_DEFAULT
-
PROP_FFM
- See Also:
-
PROP_JNI
- See Also:
-
PROP_JANSI
- See Also:
-
PROP_JNA
- See Also:
-
PROP_EXEC
- See Also:
-
PROP_DUMB
- See Also:
-
PROP_DUMB_COLOR
- See Also:
-
PROP_OUTPUT
- See Also:
-
PROP_OUTPUT_OUT
- See Also:
-
PROP_OUTPUT_ERR
- See Also:
-
PROP_OUTPUT_OUT_ERR
- See Also:
-
PROP_OUTPUT_ERR_OUT
- See Also:
-
PROP_OUTPUT_FORCED_OUT
- See Also:
-
PROP_OUTPUT_FORCED_ERR
- See Also:
-
PROP_NON_BLOCKING_READS
- See Also:
-
PROP_COLOR_DISTANCE
- See Also:
-
PROP_DISABLE_ALTERNATE_CHARSET
- See Also:
-
PROP_FILE_DESCRIPTOR_CREATION_MODE
- See Also:
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE
- See Also:
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION
- See Also:
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT
-
PROP_REDIRECT_PIPE_CREATION_MODE
- See Also:
-
PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE
- See Also:
-
PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION
- See Also:
-
PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT
-
DEPRECATED_PROVIDERS
-
PROP_DISABLE_DEPRECATED_PROVIDER_WARNING
- See Also:
-
-
Method Details
-
terminal
Returns the default system terminal with automatic configuration.This method creates a terminal connected to the system's standard input and output streams, automatically detecting the appropriate terminal type and capabilities for the current environment. It's the simplest way to get a working terminal instance for most applications.
The terminal is created with default settings, which include:
- System streams for input and output
- Auto-detected terminal type
- System default encoding
- Native signal handling
This call is equivalent to:
builder().build()
Important: Terminals should be closed properly using the
Closeable.close()
method when they are no longer needed in order to restore the original terminal state.Example usage:
try (Terminal terminal = TerminalBuilder.terminal()) { terminal.writer().println("Hello, terminal!"); terminal.flush(); // Use terminal... }
- Returns:
- the default system terminal, never
null
- Throws:
IOException
- if an error occurs during terminal creation- See Also:
-
builder
Creates a new terminal builder instance for configuring and creating terminals.This method returns a builder that can be used to configure various aspects of the terminal before creating it. The builder provides a fluent API for setting terminal properties such as name, type, encoding, input/output streams, and more.
Example usage:
Terminal terminal = TerminalBuilder.builder() .name("MyTerminal") .system(true) .encoding(StandardCharsets.UTF_8) .build();
- Returns:
- a new terminal builder instance, never
null
- See Also:
-
name
-
streams
-
system
-
systemOutput
Indicates which standard stream should be used when displaying to the terminal. The default is to use the system output stream. Building a system terminal will fail if one of the stream specified is not linked to the controlling terminal.- Parameters:
systemOutput
- The mode to choose the output stream.- Returns:
- The builder.
-
provider
Forces the usage of the give terminal provider.- Parameters:
provider
- TheTerminalProvider
's name to use when creating the Terminal.- Returns:
- The builder.
-
providers
Sets the list of providers to try when creating the terminal. If not specified, the system propertyPROP_PROVIDERS
will be used if set. Else, the valuePROP_PROVIDERS_DEFAULT
will be used.- Parameters:
providers
- The list ofTerminalProvider
's names to check when creating the Terminal.- Returns:
- The builder.
-
jna
Enables or disables thePROP_PROVIDER_JNA
/jna
terminal provider. If not specified, the system propertyPROP_JNA
will be used if set. If not specified, the provider will be checked. -
jansi
Enables or disables thePROP_PROVIDER_JANSI
/jansi
terminal provider. If not specified, the system propertyPROP_JANSI
will be used if set. If not specified, the provider will be checked. -
jni
Enables or disables thePROP_PROVIDER_JNI
/jni
terminal provider.The JNI provider uses the JLine native library loaded by
JLineNativeLoader
to access low-level terminal functionality. This provider generally offers the best performance and most complete terminal support.If not specified, the system property
PROP_JNI
will be used if set. If not specified, the provider will be checked for availability.The native library loading can be configured using system properties as documented in
JLineNativeLoader
.- Parameters:
jni
- true to enable the JNI provider, false to disable it- Returns:
- this builder
- See Also:
-
exec
Enables or disables thePROP_PROVIDER_EXEC
/exec
terminal provider. If not specified, the system propertyPROP_EXEC
will be used if set. If not specified, the provider will be checked. -
ffm
Enables or disables thePROP_PROVIDER_FFM
/ffm
terminal provider. If not specified, the system propertyPROP_FFM
will be used if set. If not specified, the provider will be checked. -
dumb
Enables or disables thePROP_PROVIDER_DUMB
/dumb
terminal provider. If not specified, the system propertyPROP_DUMB
will be used if set. If not specified, the provider will be checked. -
type
-
color
-
encoding
Set the encoding to use for reading/writing from the console. Ifnull
(the default value), JLine will automatically select aCharset
, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on theTerminal
implementation.Use
Terminal.encoding()
to get theCharset
that should be used for aTerminal
.This method sets a single encoding for all streams (stdin, stdout, stderr). To set separate encodings for each stream, use
stdinEncoding(Charset)
,stdoutEncoding(Charset)
, andstderrEncoding(Charset)
.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
UnsupportedCharsetException
- If the given encoding is not supported- See Also:
-
encoding
Set theCharset
to use for reading/writing from the console. Ifnull
(the default value), JLine will automatically select aCharset
, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on theTerminal
implementation.Use
Terminal.encoding()
to get theCharset
that should be used to read/write from aTerminal
.This method sets a single encoding for all streams (stdin, stdout, stderr). To set separate encodings for each stream, use
stdinEncoding(Charset)
,stdoutEncoding(Charset)
, andstderrEncoding(Charset)
.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
-
stdinEncoding
Set the encoding to use for reading from standard input. Ifnull
(the default value), JLine will use the value from the "stdin.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
UnsupportedCharsetException
- If the given encoding is not supported- See Also:
-
stdinEncoding
Set theCharset
to use for reading from standard input. Ifnull
(the default value), JLine will use the value from the "stdin.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
-
stdoutEncoding
Set the encoding to use for writing to standard output. Ifnull
(the default value), JLine will use the value from the "stdout.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
UnsupportedCharsetException
- If the given encoding is not supported- See Also:
-
stdoutEncoding
Set theCharset
to use for writing to standard output. Ifnull
(the default value), JLine will use the value from the "stdout.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
-
stderrEncoding
Set the encoding to use for writing to standard error. Ifnull
(the default value), JLine will use the value from the "stderr.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
UnsupportedCharsetException
- If the given encoding is not supported- See Also:
-
stderrEncoding
Set theCharset
to use for writing to standard error. Ifnull
(the default value), JLine will use the value from the "stderr.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding
- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
-
codepage
Deprecated.JLine now writes Unicode output independently from the selected code page. Using this option will only make it emulate the selected code page forTerminal.input()
andTerminal.output()
.- Parameters:
codepage
- the codepage- Returns:
- The builder
-
attributes
Attributes to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using thestreams(InputStream, OutputStream)
method or whensystem(boolean)
has been explicitly called withfalse
.- Parameters:
attributes
- the attributes to use- Returns:
- The builder
- See Also:
-
size
Initial size to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using thestreams(InputStream, OutputStream)
method or whensystem(boolean)
has been explicitly called withfalse
.- Parameters:
size
- the initial size- Returns:
- The builder
- See Also:
-
nativeSignals
-
signalHandler
Determines the default value for signal handlers. All signals will be mapped to the given handler.- Parameters:
signalHandler
- the default signal handler- Returns:
- The builder
-
paused
Initial paused state of the terminal (defaults to false). By default, the terminal is started, but in some cases, one might want to make sure the input stream is not consumed before needed, in which case the terminal needs to be created in a paused state.- Parameters:
paused
- the initial paused state- Returns:
- The builder
- See Also:
-
build
Builds the terminal.- Returns:
- the newly created terminal, never
null
- Throws:
IOException
- if an error occurs
-
computeSystemOutput
-
computeType
-
computeEncoding
-
computeStdinEncoding
-
computeStdoutEncoding
-
computeStderrEncoding
-
getProviders
Get the list of available terminal providers. This list is sorted according to thePROP_PROVIDERS
system property.- Parameters:
provider
- if notnull
, only this provider will be checkedexception
- if a provider throws an exception, it will be added to this exception as a suppressed exception- Returns:
- a list of terminal providers
-
setTerminalOverride
Deprecated.Allows an application to override the result ofbuild()
. The intended use case is to allow a container or server application to control an embedded application that uses a LineReader that uses Terminal constructed with TerminalBuilder.build but provides no public api for setting theLineReader
of theTerminal
. For example, the sbt build tool uses aLineReader
to implement an interactive shell. One of its supported commands isconsole
which invokes the scala REPL. The scala REPL also uses aLineReader
and it is necessary to override theTerminal
used by the the REPL to share the sameTerminal
instance used by sbt.When this method is called with a non-null
Terminal
, all subsequent calls tobuild()
will return the providedTerminal
regardless of how theTerminalBuilder
was constructed. The default behavior ofTerminalBuilder
can be restored by calling setTerminalOverride with a nullTerminal
Usage of setTerminalOverride should be restricted to cases where it isn't possible to update the api of the nested application to accept a
instance
.- Parameters:
terminal
- theTerminal
to globally override
-