W3cubDocs

/OpenJDK 21

Interface JavaShellToolBuilder

public interface JavaShellToolBuilder
Interface to configure and run a Java shell tool instance. An instance of the builder is created with the static builder() method. This builder can, optionally, be configured with the configuration methods. All configuration methods return the builder instance for use in chained initialization. All configuration methods have sensible defaults which will be used if they are not called.. After zero or more calls to configuration methods, the tool is launched with a call to run(java.lang.String...).
Since:
9

Method Summary

Modifier and Type Method Description
static JavaShellToolBuilder builder()
Create a builder for launching the JDK jshell tool.
JavaShellToolBuilder env(Map<String,String> vars)
Set the source for environment variables.
JavaShellToolBuilder err(PrintStream error)
Set the error channels.
JavaShellToolBuilder err(PrintStream cmdErr, PrintStream userErr)
Set the error channels.
JavaShellToolBuilder in(InputStream cmdIn, InputStream userIn)
Set the input channels.
default JavaShellToolBuilder interactiveTerminal(boolean terminal)
Set to true to specify the inputs and outputs are connected to an interactive terminal that can interpret the ANSI escape codes.
JavaShellToolBuilder locale(Locale locale)
Set the locale.
JavaShellToolBuilder out(PrintStream output)
Set the output channels.
JavaShellToolBuilder out(PrintStream cmdOut, PrintStream console, PrintStream userOut)
Set the output channels.
JavaShellToolBuilder persistence(Map<String,String> prefsMap)
Set the storage mechanism for persistent information which includes input history and retained settings.
JavaShellToolBuilder persistence(Preferences prefs)
Set the storage mechanism for persistent information which includes input history and retained settings.
JavaShellToolBuilder promptCapture(boolean capture)
Set to enable a command capturing prompt override.
void run(String... arguments)
Run an instance of the Java shell tool as configured by the other methods in this interface.
default int start(String... arguments)
Run an instance of the Java shell tool as configured by the other methods in this interface.

Method Details

builder

static JavaShellToolBuilder builder()
Create a builder for launching the JDK jshell tool.
Returns:
a builder which can be used to configure and launch the jshell tool

in

JavaShellToolBuilder in(InputStream cmdIn, InputStream userIn)
Set the input channels.
Implementation Requirements:
If this method is not called, the behavior should be equivalent to calling in(System.in, null).
Parameters:
cmdIn - source of command input
userIn - source of input for running user code, or null to extract user input from cmdIn
Returns:
the JavaShellToolBuilder instance

out

JavaShellToolBuilder out(PrintStream output)
Set the output channels. Same as out(output, output, output).
Implementation Requirements:
If neither out method is called, the behavior should be equivalent to calling out(System.out).
Parameters:
output - destination of command feedback, console interaction, and user code output
Returns:
the JavaShellToolBuilder instance

out

JavaShellToolBuilder out(PrintStream cmdOut, PrintStream console, PrintStream userOut)
Set the output channels.
Implementation Requirements:
If neither out method is called, the behavior should be equivalent to calling out(System.out, System.out, System.out).
Parameters:
cmdOut - destination of command feedback including error messages for users
console - destination of console interaction
userOut - destination of user code output. For example, user snippet System.out.println("Hello") when executed Hello goes to userOut.
Returns:
the JavaShellToolBuilder instance

err

JavaShellToolBuilder err(PrintStream error)
Set the error channels. Same as err(error, error).
Implementation Requirements:
If neither err method is called, the behavior should be equivalent to calling err(System.err).
Parameters:
error - destination of tool errors, and user code errors
Returns:
the JavaShellToolBuilder instance

err

JavaShellToolBuilder err(PrintStream cmdErr, PrintStream userErr)
Set the error channels.
Implementation Requirements:
If neither err method is called, the behavior should be equivalent to calling err(System.err, System.err, System.err).
Parameters:
cmdErr - destination of tool start-up and fatal errors
userErr - destination of user code error output. For example, user snippet System.err.println("Oops") when executed Oops goes to userErr.
Returns:
the JavaShellToolBuilder instance

persistence

JavaShellToolBuilder persistence(Preferences prefs)
Set the storage mechanism for persistent information which includes input history and retained settings.
Implementation Requirements:
If neither persistence method is called, the behavior should be to use the tool's standard persistence mechanism.
Parameters:
prefs - an instance of Preferences that is used to retrieve and store persistent information
Returns:
the JavaShellToolBuilder instance

persistence

JavaShellToolBuilder persistence(Map<String,String> prefsMap)
Set the storage mechanism for persistent information which includes input history and retained settings.
Implementation Requirements:
If neither persistence method is called, the behavior should be to use the tool's standard persistence mechanism.
Parameters:
prefsMap - an instance of Map that is used to retrieve and store persistent information
Returns:
the JavaShellToolBuilder instance

env

JavaShellToolBuilder env(Map<String,String> vars)
Set the source for environment variables.
Implementation Requirements:
If this method is not called, the behavior should be equivalent to calling env(System.getenv()).
Parameters:
vars - the Map of environment variable names to values
Returns:
the JavaShellToolBuilder instance

locale

JavaShellToolBuilder locale(Locale locale)
Set the locale.
Implementation Requirements:
If this method is not called, the behavior should be equivalent to calling locale(Locale.getDefault()).
Parameters:
locale - the locale
Returns:
the JavaShellToolBuilder instance

promptCapture

JavaShellToolBuilder promptCapture(boolean capture)
Set to enable a command capturing prompt override.
Implementation Requirements:
If this method is not called, the behavior should be equivalent to calling promptCapture(false).
Parameters:
capture - if true, basic prompt is the ENQ character and continuation prompt is the ACK character. If false, prompts are as set with set-up or user /set commands.
Returns:
the JavaShellToolBuilder instance

interactiveTerminal

default JavaShellToolBuilder interactiveTerminal(boolean terminal)
Set to true to specify the inputs and outputs are connected to an interactive terminal that can interpret the ANSI escape codes. The characters sent to the output streams are assumed to be interpreted by a terminal and shown to the user, and the exact order and nature of characters sent to the outputs are unspecified. Set to false to specify a legacy simpler behavior whose output can be parsed by automatic tools. When the input stream for this Java Shell is System.in, this value is ignored, and the behavior is similar to specifying true in this method, but is more closely following the specific terminal connected to System.in.
Implementation Requirements:
If this method is not called, the behavior should be equivalent to calling interactiveTerminal(false). The default implementation of this method returns this.
Parameters:
terminal - if true, an terminal that can interpret the ANSI escape codes is assumed to interpret the output. If false, a simpler output is selected.
Returns:
the JavaShellToolBuilder instance
Since:
17

run

void run(String... arguments) throws Exception
Run an instance of the Java shell tool as configured by the other methods in this interface. This call is not destructive, more than one call of this method may be made from a configured builder. The exit code from the Java shell tool is ignored.
Parameters:
arguments - the command-line arguments (including options), if any
Throws:
Exception - an unexpected fatal exception

start

default int start(String... arguments) throws Exception
Run an instance of the Java shell tool as configured by the other methods in this interface. This call is not destructive, more than one call of this method may be made from a configured builder.
Implementation Requirements:
The default implementation always returns zero. Implementations of this interface should override this method, returning the exit status.
Parameters:
arguments - the command-line arguments (including options), if any
Returns:
the exit status with which the tool explicitly exited (if any), otherwise 0 for success or 1 for failure
Throws:
Exception - an unexpected fatal exception

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jshell/jdk/jshell/tool/JavaShellToolBuilder.html