jdk.jshell (Java SE 15 & JDK 15) (original) (raw)

Provides interfaces for creating tools, such as a Read-Eval-Print Loop (REPL), which interactively evaluate "snippets" of Java programming language code. Where a "snippet" is a single expression, statement, or declaration. This functionality can be used to enhance tools such as IDEs or can be stand-alone.

JShell is the central class. An instance ofJShell holds the evaluation state, which is both the current set of source snippets and the execution state they have produced.

Each source snippet is represented by an instance of a subclass ofSnippet. For example, a statement is represented by an instance of StatementSnippet, and a method declaration is represented by an instance of MethodSnippet. Snippets are created whenJShell.eval(String) is invoked with an input which includes one or more snippets of code.

Any change to the compilation status of a snippet is reported with aSnippetEvent. There are three major kinds of changes to the status of a snippet: it can created with eval, it can be dropped from the active source state withJShell.drop(jdk.jshell.Snippet), and it can have its status updated as a result of a status change in another snippet. For example: given js, an instance of JShell, executingjs.eval("int x = 5;") will add the variable x to the source state and will generate an event describing the creation of aVarSnippet for x. Then executingjs.eval("int timesx(int val) { return val * x; }") will add a method to the source state and will generate an event describing the creation of a MethodSnippet fortimesx. Assume that varx holds the snippet created by the first call to eval, executing js.drop(varx) will generate two events: one for changing the status of the variable snippet to DROPPED and one for updating the method snippet (which now has an unresolved reference tox).

Of course, for any general application of the API, the input would not be fixed strings, but would come from the user. Below is a very simplified example of how the API might be used to implement a REPL.

` import java.io.ByteArrayInputStream; import java.io.Console; import java.util.List; import jdk.jshell.*; import jdk.jshell.Snippet.Status;

 class ExampleJShell {
     public static void main(String[] args) {
         Console console = System.console();
         try (JShell js = JShell.create()) {
             do {
                 System.out.print("Enter some Java code: ");
                 String input = console.readLine();
                 if (input == null) {
                     break;
                 }
                 List<SnippetEvent> events = js.eval(input);
                 for (SnippetEvent e : events) {
                     StringBuilder sb = new StringBuilder();
                     if (e.causeSnippet == null) {
                         //  We have a snippet creation event
                         switch (e.status) {
                             case VALID:
                                 sb.append("Successful ");
                                 break;
                             case RECOVERABLE_DEFINED:
                                 sb.append("With unresolved references ");
                                 break;
                             case RECOVERABLE_NOT_DEFINED:
                                 sb.append("Possibly reparable, failed  ");
                                 break;
                             case REJECTED:
                                 sb.append("Failed ");
                                 break;
                         }
                         if (e.previousStatus == Status.NONEXISTENT) {
                             sb.append("addition");
                         } else {
                             sb.append("modification");
                         }
                         sb.append(" of ");
                         sb.append(e.snippet.source());
                         System.out.println(sb);
                         if (e.value != null) {
                             System.out.printf("Value is: %s\n", e.value);
                         }
                         System.out.flush();
                     }
                 }
             } while (true);
         }
         System.out.println("\nGoodbye");
     }
 }

`

To register for status change events useJShell.onSnippetEvent(java.util.function.Consumer). These events are only generated by eval and drop, the return values of these methods are the list of events generated by that call. So, as in the example above, events can be used without registering to receive events.

If you experiment with this example, you will see that failing to terminate a statement or variable declaration with a semi-colon will simply fail. An unfinished entry (for example a desired multi-line method) will also just fail after one line. The utilities in SourceCodeAnalysis provide source boundary and completeness analysis to address cases like those. SourceCodeAnalysis also provides suggested completions of input, as might be used in tab-completion.

Since:

9

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2020, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.