| /* |
| * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package jdk.jshell.tool; |
| |
| import java.io.InputStream; |
| import java.io.PrintStream; |
| import java.util.Locale; |
| import java.util.Map; |
| import java.util.prefs.Preferences; |
| import jdk.internal.jshell.tool.JShellToolBuilder; |
| |
| /** |
| * Interface to configure and run a Java shell tool instance. An instance of the |
| * builder is created with the static {@link #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 {@link #run(java.lang.String...) }. |
| * |
| * @since 9 |
| */ |
| public interface JavaShellToolBuilder { |
| |
| /** |
| * Create a builder for launching the JDK jshell tool. |
| * |
| * @return a builder which can be used to configure and launch the jshell |
| * tool |
| */ |
| static JavaShellToolBuilder builder() { |
| return new JShellToolBuilder(); |
| } |
| |
| /** |
| * Set the input channels. |
| * |
| * @implSpec If this method is not called, the behavior should be |
| * equivalent to calling {@code in(System.in, null)}. |
| * |
| * @param cmdIn source of command input |
| * @param userIn source of input for running user code, or {@code null} to |
| * extract user input from cmdIn |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder in(InputStream cmdIn, InputStream userIn); |
| |
| /** |
| * Set the output channels. Same as {@code out(output, output, output)}. |
| * |
| * @implSpec If neither {@code out} method is called, the behavior should be |
| * equivalent to calling {@code out(System.out)}. |
| * |
| * @param output destination of command feedback, console interaction, and |
| * user code output |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder out(PrintStream output); |
| |
| /** |
| * Set the output channels. |
| * |
| * @implSpec If neither {@code out} method is called, the behavior should be |
| * equivalent to calling {@code out(System.out, System.out, System.out)}. |
| * |
| * @param cmdOut destination of command feedback including error messages |
| * for users |
| * @param console destination of console interaction |
| * @param userOut destination of user code output. For example, user snippet |
| * {@code System.out.println("Hello")} when executed {@code Hello} goes to |
| * userOut. |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder out(PrintStream cmdOut, PrintStream console, PrintStream userOut); |
| |
| /** |
| * Set the error channels. Same as {@code err(error, error)}. |
| * |
| * @implSpec If neither {@code err} method is called, the behavior should be |
| * equivalent to calling {@code err(System.err)}. |
| * |
| * @param error destination of tool errors, and |
| * user code errors |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder err(PrintStream error); |
| |
| /** |
| * Set the error channels. |
| * |
| * @implSpec If neither {@code err} method is called, the behavior should be |
| * equivalent to calling {@code err(System.err, System.err, System.err)}. |
| * |
| * @param cmdErr destination of tool start-up and fatal errors |
| * @param userErr destination of user code error output. |
| * For example, user snippet {@code System.err.println("Oops")} |
| * when executed {@code Oops} goes to userErr. |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder err(PrintStream cmdErr, PrintStream userErr); |
| |
| /** |
| * Set the storage mechanism for persistent information which includes |
| * input history and retained settings. |
| * |
| * @implSpec If neither {@code persistence} method is called, the behavior |
| * should be to use the tool's standard persistence mechanism. |
| * |
| * @param prefs an instance of {@link java.util.prefs.Preferences} that |
| * is used to retrieve and store persistent information |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder persistence(Preferences prefs); |
| |
| /** |
| * Set the storage mechanism for persistent information which includes |
| * input history and retained settings. |
| * |
| * @implSpec If neither {@code persistence} method is called, the behavior |
| * should be to use the tool's standard persistence mechanism. |
| * |
| * @param prefsMap an instance of {@link java.util.Map} that |
| * is used to retrieve and store persistent information |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder persistence(Map<String,String> prefsMap); |
| |
| /** |
| * Set the source for environment variables. |
| * |
| * @implSpec If this method is not called, the behavior should be |
| * equivalent to calling {@code env(System.getenv())}. |
| * |
| * @param vars the Map of environment variable names to values |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder env(Map<String,String> vars); |
| |
| /** |
| * Set the locale. |
| * |
| * @implSpec If this method is not called, the behavior should be |
| * equivalent to calling {@code locale(Locale.getDefault())}. |
| * |
| * @param locale the locale |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder locale(Locale locale); |
| |
| /** |
| * Set to enable a command capturing prompt override. |
| * |
| * @implSpec If this method is not called, the behavior should be |
| * equivalent to calling {@code promptCapture(false)}. |
| * |
| * @param capture if {@code true}, basic prompt is the {@code ENQ} |
| * character and continuation prompt is the {@code ACK} character. |
| * If false, prompts are as set with set-up or user {@code /set} commands. |
| * @return the {@code JavaShellToolBuilder} instance |
| */ |
| JavaShellToolBuilder promptCapture(boolean capture); |
| |
| /** |
| * 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. |
| * |
| * @param arguments the command-line arguments (including options), if any |
| * @throws Exception an unexpected fatal exception |
| */ |
| void run(String... arguments) throws Exception; |
| } |