package-info.java revision 3062:15bdc18525ff
11573Srgrimes/* 21573Srgrimes * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. 31573Srgrimes * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 41573Srgrimes * 51573Srgrimes * This code is free software; you can redistribute it and/or modify it 66574Snate * under the terms of the GNU General Public License version 2 only, as 71573Srgrimes * published by the Free Software Foundation. Oracle designates this 81573Srgrimes * particular file as subject to the "Classpath" exception as provided 91573Srgrimes * by Oracle in the LICENSE file that accompanied this code. 101573Srgrimes * 118198Sjoerg * This code is distributed in the hope that it will be useful, but WITHOUT 128198Sjoerg * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 131573Srgrimes * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 141573Srgrimes * version 2 for more details (a copy is included in the LICENSE file that 157742Sjoerg * accompanied this code). 167742Sjoerg * 171573Srgrimes * You should have received a copy of the GNU General Public License version 181573Srgrimes * 2 along with this work; if not, write to the Free Software Foundation, 191573Srgrimes * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 201573Srgrimes * 211573Srgrimes * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 221850Swollman * or visit www.oracle.com if you need additional information or have any 237742Sjoerg * questions. 241573Srgrimes */ 251573Srgrimes 267742Sjoerg/** 271573Srgrimes * Provides interfaces for creating tools, such as a Read-Eval-Print Loop (REPL), 281573Srgrimes * which interactively evaluate "snippets" of Java programming language code. 291586Srgrimes * Where a "snippet" is a single expression, statement, or declaration. 301586Srgrimes * This functionality can be used to enhance tools such as IDEs or can be 311573Srgrimes * stand-alone. 321573Srgrimes * <p> 331573Srgrimes * {@link jdk.jshell.JShell} is the central class. An instance of 341573Srgrimes * <code>JShell</code> holds the evaluation state, which is both the current 351573Srgrimes * set of source snippets and the execution state they have produced. 361573Srgrimes * <p> 371573Srgrimes * Each source snippet is represented by an instance of a subclass of 381573Srgrimes * {@link jdk.jshell.Snippet}. For example, a statement is represented by an 391573Srgrimes * instance of {@link jdk.jshell.StatementSnippet}, and a method declaration is 401573Srgrimes * represented by an instance of {@link jdk.jshell.MethodSnippet}. 411573Srgrimes * Snippets are created when {@link jdk.jshell.JShell#eval(java.lang.String)} 421573Srgrimes * is invoked with an input which includes one or more snippets of code. 431573Srgrimes * <p> 441573Srgrimes * Any change to the compilation status of a snippet is reported with a 451573Srgrimes * {@link jdk.jshell.SnippetEvent}. There are three major kinds of 461586Srgrimes * changes to the status of a snippet: it can created with <code>eval</code>, 4712538Sache * it can be dropped from the active source state with 481573Srgrimes * {@link jdk.jshell.JShell#drop(jdk.jshell.PersistentSnippet)}, and it can have 491586Srgrimes * its status updated as a result of a status change in another snippet. 501586Srgrimes * For 511573Srgrimes * example: given <code>js</code>, an instance of <code>JShell</code>, executing 521573Srgrimes * <code>js.eval("int x = 5;")</code> will add the variable <code>x</code> to 5313987Smpp * the source state and will generate an event describing the creation of a 541573Srgrimes * {@link jdk.jshell.VarSnippet} for <code>x</code>. Then executing 551573Srgrimes * <code>js.eval("int timesx(int val) { return val * x; }")</code> will add 561573Srgrimes * a method to the source state and will generate an event 577742Sjoerg * describing the creation of a {@link jdk.jshell.MethodSnippet} for 581573Srgrimes * <code>timesx</code>. 591573Srgrimes * Assume that <code>varx</code> holds the snippet created by the first 601573Srgrimes * call to <code>eval</code>, executing <code>js.drop(varx)</code> will 611573Srgrimes * generate two events: one for changing the status of the 621850Swollman * variable snippet to <code>DROPPED</code> and one for 631573Srgrimes * updating the method snippet (which now has an unresolved reference to 641573Srgrimes * <code>x</code>). 651573Srgrimes * <p> 661573Srgrimes * Of course, for any general application of the API, the input would not be 678198Sjoerg * fixed strings, but would come from the user. Below is a very simplified 688198Sjoerg * example of how the API might be used to implement a REPL. 698198Sjoerg * <pre> 708198Sjoerg* {@code 718198Sjoerg * import java.io.ByteArrayInputStream; 728198Sjoerg * import java.io.Console; 731573Srgrimes * import java.util.List; 74 * import jdk.jshell.*; 75 * import jdk.jshell.Snippet.Status; 76 * 77 * class ExampleJShell { 78 * public static void main(String[] args) { 79 * Console console = System.console(); 80 * try (JShell js = JShell.create()) { 81 * do { 82 * System.out.print("Enter some Java code: "); 83 * String input = console.readLine(); 84 * if (input == null) { 85 * break; 86 * } 87 * List<SnippetEvent> events = js.eval(input); 88 * for (SnippetEvent e : events) { 89 * StringBuilder sb = new StringBuilder(); 90 * if (e.causeSnippet == null) { 91 * // We have a snippet creation event 92 * switch (e.status) { 93 * case VALID: 94 * sb.append("Successful "); 95 * break; 96 * case RECOVERABLE_DEFINED: 97 * sb.append("With unresolved references "); 98 * break; 99 * case RECOVERABLE_NOT_DEFINED: 100 * sb.append("Possibly reparable, failed "); 101 * break; 102 * case REJECTED: 103 * sb.append("Failed "); 104 * break; 105 * } 106 * if (e.previousStatus == Status.NONEXISTENT) { 107 * sb.append("addition"); 108 * } else { 109 * sb.append("modification"); 110 * } 111 * sb.append(" of "); 112 * sb.append(e.snippet.source()); 113 * System.out.println(sb); 114 * if (e.value != null) { 115 * System.out.printf("Value is: %s\n", e.value); 116 * } 117 * System.out.flush(); 118 * } 119 * } 120 * } while (true); 121 * } 122 * System.out.println("\nGoodbye"); 123 * } 124 * } 125 * } 126 * </pre> 127 * <p> 128 * To register for status change events use 129 * {@link jdk.jshell.JShell#onSnippetEvent(java.util.function.Consumer)}. 130 * These events are only generated by <code>eval</code> and <code>drop</code>, 131 * the return values of these methods are the list of events generated by that 132 * call. So, as in the example above, events can be used without registering 133 * to receive events. 134 * <p> 135 * If you experiment with this example, you will see that failing to terminate 136 * a statement or variable declaration with a semi-colon will simply fail. 137 * An unfinished entry (for example a desired multi-line method) will also just 138 * fail after one line. The utilities in {@link jdk.jshell.SourceCodeAnalysis} 139 * provide source boundary and completeness analysis to address cases like 140 * those. <code>SourceCodeAnalysis</code> also provides suggested completions 141 * of input, as might be used in tab-completion. 142 */ 143 144 145package jdk.jshell; 146 147