1 /* 2 * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package jdk.jshell.spi; 27 28 import java.util.Collection; 29 import jdk.jshell.JShellException; 30 31 /** 32 * This interface specifies the functionality that must provided to implement 33 * a pluggable JShell execution engine. 34 * <p> 35 * The audience for this Service Provider Interface is engineers 36 * wishing to implement their own version of the execution engine in support 37 * of the JShell API. This is NOT a part of the JShell API. 38 * <p> 39 * A Snippet is compiled into code wrapped in a 'wrapper class'. The execution 40 * engine is used by the core JShell implementation to load and, for 41 * executable Snippets, execute the Snippet. 42 * <p> 43 * Methods defined in this interface should only be called by the core JShell 44 * implementation. 45 * <p> 46 * To install an instance of ExecutionControl, it is passed to 47 * {@link jdk.jshell.JShell.Builder#executionEngine(jdk.jshell.spi.ExecutionControl) }. 48 */ 49 public interface ExecutionControl { 50 51 /** 52 * Represents the current status of a class in the execution engine. 53 */ 54 public enum ClassStatus { 55 /** 56 * Class is not known to the execution engine (not loaded). 57 */ 58 UNKNOWN, 59 60 /** 61 * Class is loaded, but the loaded/redefined bytes do not match those 62 * returned by {@link ExecutionEnv#getClassBytes(java.lang.String) }. 63 */ 64 NOT_CURRENT, 65 66 /** 67 * Class is loaded and loaded/redefined bytes match those 68 * returned by {@link ExecutionEnv#getClassBytes(java.lang.String) }. 69 */ 70 CURRENT 71 }; 72 73 /** 74 * Initializes the instance. No methods in this interface can be called 75 * before this. 76 * 77 * @param env the execution environment information provided by JShell 78 * @throws Exception if the instance is unable to initialize 79 */ 80 void start(ExecutionEnv env) throws Exception; 81 82 /** 83 * Shuts down this execution engine. Implementation should free all 84 * resources held by this execution engine. 85 * <p> 86 * No calls to methods on this interface should be made after close. 87 */ 88 void close(); 89 90 /** 91 * Adds the path to the execution class path. 92 * 93 * @param path the path to add 94 * @return true if successful 95 */ 96 boolean addToClasspath(String path); 97 98 /** 99 * Invokes an executable Snippet by calling a method on the specified 100 * wrapper class. The method must have no arguments and return String. 101 * 102 * @param classname the class whose method should be invoked 103 * @param methodname the name of method to invoke 104 * @return the result of the execution or null if no result 105 * @throws JShellException if a user exception if thrown, 106 * {@link jdk.jshell.EvalException EvalException} will be thrown; if an 107 * unresolved reference is encountered, 108 * {@link jdk.jshell.UnresolvedReferenceException UnresolvedReferenceException} 109 * will be thrown 110 */ 111 String invoke(String classname, String methodname) throws JShellException; 112 113 /** 114 * Attempts to load new classes. Class bytes are retrieved from 115 * {@link ExecutionEnv#getClassBytes(java.lang.String) } 116 * 117 * @param classes list of class names to load 118 * @return true if load succeeded 119 */ 120 boolean load(Collection<String> classes); 121 122 /** 123 * Attempts to redefine previously loaded classes. Class bytes are retrieved 124 * from {@link ExecutionEnv#getClassBytes(java.lang.String) } 125 * 126 * @param classes list of class names to redefine 127 * @return true if redefine succeeded 128 */ 129 boolean redefine(Collection<String> classes); 130 131 /** 132 * Queries if the class is loaded and the class bytes are current. 133 * 134 * @param classname name of the wrapper class to query 135 * @return {@code UNKNOWN} if the class is not loaded; {@code CURRENT} if 136 * the loaded/redefined bytes are equal to the most recent bytes for this 137 * wrapper class; otherwise {@code NOT_CURRENT} 138 */ 139 ClassStatus getClassStatus(String classname); 140 141 /** 142 * Interrupt a running invoke. 143 */ 144 void stop(); 145 146 /** 147 * Returns the value of a variable. 148 * 149 * @param classname the name of the wrapper class of the variable 150 * @param varname the name of the variable 151 * @return the value of the variable 152 */ 153 String varValue(String classname, String varname); 154 }