JavaShellToolBuilder (Java SE 21 & JDK 21)
Description: declaration: module: jdk.jshell, package: jdk.jshell.tool, interface: JavaShellToolBuilder
Keywords: jdk.jshell.tool.JavaShellToolBuilder interface

Module jdk.jshell
Package jdk.jshell.tool

# 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