Summary

A mechanism to pass jshell tool exit status to system shell exit status.

Problem

jdk.internal.jshell.tool.JShellToolProvider, which is run by the launcher, reports exit status per Tool.run().

However, the JavaShellToolBuilder in the jshell tool launching API (jdk.jshell.tool) declares run() as a void method, providing no way to propagate the exit status code from the tool. This is important when:

• The tool fails during launch (e.g. missing load file)
• The user explicitly exits with an exit code (JDK-8185840)

Solution

A new version of the builder run method is needed in the builder which returns the exit status.

A new default method is added to the JavaShellToolBuilder interface:

    default int start(String... arguments) throws Exception { .. }

The implementing class and participating tool code pass the status code through.

Specification

In text form, the added method has this doc:

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

The javadoc form can be seen here:

http://cr.openjdk.java.net/~rfield/8190564v3.javadoc/jdk/jshell/tool/JavaShellToolBuilder.html

And the jdk.jshell.tool package docs updated to use the new method, are here:

http://cr.openjdk.java.net/~rfield/8190564v3.javadoc/jdk/jshell/tool/package-summary.html

The webrev for this and JDK-8185840 is attached (8190564v5.webrev.zip, please ignore older versions) and can be seen here:

http://cr.openjdk.java.net/~rfield/8190564v5.webrev/

The sdiff for the interface changes can be seen here:

http://cr.openjdk.java.net/~rfield/8190564v5.webrev/src/jdk.jshell/share/classes/jdk/jshell/tool/JavaShellToolBuilder.java.sdiff.html

The sdiff for the name change in the example in the jdk.jshell.tool docs is here:

http://cr.openjdk.java.net/~rfield/8190564v5.webrev/src/jdk.jshell/share/classes/jdk/jshell/tool/package-info.java.sdiff.html