1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
/* * @(#)ScriptEngine.java 1.5 06/06/19 20:53:06 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTAIL. Use is subject to license terms. */ package javax.script; import java.io.Reader; import java.util.Map; import java.util.Set; /** * <code>ScriptEngine</code> is the fundamental interface whose methods must be * fully functional in every implementation of this specification. * <br><br> * These methods provide basic scripting functionality. Applications written to this * simple interface are expected to work with minimal modifications in every implementation. * It includes methods that execute scripts, and ones that set and get values. * <br><br> * The values are key/value pairs of two types. The first type of pairs consists of * those whose keys are reserved and defined in this specification or by individual * implementations. The values in the pairs with reserved keys have specified meanings. * <br><br> * The other type of pairs consists of those that create Java language Bindings, the values are * usually represented in scripts by the corresponding keys or by decorated forms of them. * * @author Mike Grogan * @version 1.0 * @since 1.6 */ public interface ScriptEngine { /** * Reserved key for a named value that passes * an array of positional arguments to a script. */ public static final String ARGV="javax.script.argv"; /** * Reserved key for a named value that is * the name of the file being executed. */ public static final String FILENAME = "javax.script.filename"; /** * Reserved key for a named value that is * the name of the <code>ScriptEngine</code> implementation. */ public static final String ENGINE = "javax.script.engine"; /** * Reserved key for a named value that identifies * the version of the <code>ScriptEngine</code> implementation. */ public static final String ENGINE_VERSION = "javax.script.engine_version"; /** * Reserved key for a named value that identifies * the short name of the scripting language. The name is used by the * <code>ScriptEngineManager</code> to locate a <code>ScriptEngine</code> * with a given name in the <code>getEngineByName</code> method. */ public static final String NAME = "javax.script.name"; /** * Reserved key for a named value that is * the full name of Scripting Language supported by the implementation. */ public static final String LANGUAGE = "javax.script.language"; /** * Reserved key for the named value that identifies * the version of the scripting language supported by the implementation. */ public static final String LANGUAGE_VERSION ="javax.script.language_version"; /** * Causes the immediate execution of the script whose source is the String * passed as the first argument. The script may be reparsed or recompiled before * execution. State left in the engine from previous executions, including * variable values and compiled procedures may be visible during this execution. * * @param script The script to be executed by the script engine. * * @param context A <code>ScriptContext</code> exposing sets of attributes in * different scopes. The meanings of the scopes <code>ScriptContext.GLOBAL_SCOPE</code>, * and <code>ScriptContext.ENGINE_SCOPE</code> are defined in the specification. * <br><br> * The <code>ENGINE_SCOPE</code> <code>Bindings</code> of the <code>ScriptContext</code> contains the * bindings of scripting variables to application objects to be used during this * script execution. * * * @return The value returned from the execution of the script. * * @throws ScriptException if an error occurrs in script. ScriptEngines should create and throw * <code>ScriptException</code> wrappers for checked Exceptions thrown by underlying scripting * implementations. * @throws NullPointerException if either argument is null. */ public Object eval(String script, ScriptContext context) throws ScriptException; /** * Same as <code>eval(String, ScriptContext)</code> where the source of the script * is read from a <code>Reader</code>. * * @param reader The source of the script to be executed by the script engine. * * @param context The <code>ScriptContext</code> passed to the script engine. * * @return The value returned from the execution of the script. * * @throws ScriptException if an error occurrs in script. * @throws NullPointerException if either argument is null. */ public Object eval(Reader reader , ScriptContext context) throws ScriptException; /** * Executes the specified script. The default <code>ScriptContext</code> for the <code>ScriptEngine</code> * is used. * * @param script The script language source to be executed. * * @return The value returned from the execution of the script. * * @throws ScriptException if error occurrs in script. * @throws NullPointerException if the argument is null. */ public Object eval(String script) throws ScriptException; /** * Same as <code>eval(String)</code> except that the source of the script is * provided as a <code>Reader</code> * * @param reader The source of the script. * * @return The value returned by the script. * * @throws ScriptException if an error occurrs in script. * @throws NullPointerException if the argument is null. */ public Object eval(Reader reader) throws ScriptException; /** * Executes the script using the <code>Bindings</code> argument as the <code>ENGINE_SCOPE</code> * <code>Bindings</code> of the <code>ScriptEngine</code> during the script execution. The * <code>Reader</code>, <code>Writer</code> and non-<code>ENGINE_SCOPE</code> <code>Bindings</code> of the * default <code>ScriptContext</code> are used. The <code>ENGINE_SCOPE</code> * <code>Bindings</code> of the <code>ScriptEngine</code> is not changed, and its * mappings are unaltered by the script execution. * * @param script The source for the script. * * @param n The <code>Bindings</code> of attributes to be used for script execution. * * @return The value returned by the script. * * @throws ScriptException if an error occurrs in script. * @throws NullPointerException if either argument is null. */ public Object eval(String script, Bindings n) throws ScriptException; /** * Same as <code>eval(String, Bindings)</code> except that the source of the script * is provided as a <code>Reader</code>. * * @param reader The source of the script. * @param n The <code>Bindings</code> of attributes. * * @return The value returned by the script. * * @throws ScriptException if an error occurrs. * @throws NullPointerException if either argument is null. */ public Object eval(Reader reader , Bindings n) throws ScriptException; /** * Sets a key/value pair in the state of the ScriptEngine that may either create * a Java Language Binding to be used in the execution of scripts or be used in some * other way, depending on whether the key is reserved. Must have the same effect as * <code>getBindings(ScriptContext.ENGINE_SCOPE).put</code>. * * @param key The name of named value to add * @param value The value of named value to add. * * @throws NullPointerException if key is null. * @throws IllegalArgumentException if key is empty. */ public void put(String key, Object value); /** * Retrieves a value set in the state of this engine. The value might be one * which was set using <code>setValue</code> or some other value in the state * of the <code>ScriptEngine</code>, depending on the implementation. Must have the same effect * as <code>getBindings(ScriptContext.ENGINE_SCOPE).get</code> * * @param key The key whose value is to be returned * @return the value for the given key * * @throws NullPointerException if key is null. * @throws IllegalArgumentException if key is empty. */ public Object get(String key); /** * Returns a scope of named values. The possible scopes are: * <br><br> * <ul> * <li><code>ScriptContext.GLOBAL_SCOPE</code> - The set of named values representing global * scope. If this <code>ScriptEngine</code> is created by a <code>ScriptEngineManager</code>, * then the manager sets global scope bindings. This may be <code>null</code> if no global * scope is associated with this <code>ScriptEngine</code></li> * <li><code>ScriptContext.ENGINE_SCOPE</code> - The set of named values representing the state of * this <code>ScriptEngine</code>. The values are generally visible in scripts using * the associated keys as variable names.</li> * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>. * </li> * </ul> * <br><br> * The <code>Bindings</code> instances that are returned must be identical to those returned by the * <code>getBindings</code> method of <code>ScriptContext</code> called with corresponding arguments on * the default <code>ScriptContext</code> of the <code>ScriptEngine</code>. * * @param scope Either <code>ScriptContext.ENGINE_SCOPE</code> or <code>ScriptContext.GLOBAL_SCOPE</code> * which specifies the <code>Bindings</code> to return. Implementations of <code>ScriptContext</code> * may define additional scopes. If the default <code>ScriptContext</code> of the <code>ScriptEngine</code> * defines additional scopes, any of them can be passed to get the corresponding <code>Bindings</code>. * * @return The <code>Bindings</code> with the specified scope. * * @throws IllegalArgumentException if specified scope is invalid * */ public Bindings getBindings(int scope); /** * Sets a scope of named values to be used by scripts. The possible scopes are: *<br><br> * <ul> * <li><code>ScriptContext.ENGINE_SCOPE</code> - The specified <code>Bindings</code> replaces the * engine scope of the <code>ScriptEngine</code>. * </li> * <li><code>ScriptContext.GLOBAL_SCOPE</code> - The specified <code>Bindings</code> must be visible * as the <code>GLOBAL_SCOPE</code>. * </li> * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>. *</li> * </ul> * <br><br> * The method must have the same effect as calling the <code>setBindings</code> method of * <code>ScriptContext</code> with the corresponding value of <code>scope</code> on the default * <code>ScriptContext</code> of the <code>ScriptEngine</code>. * * @param bindings The <code>Bindings</code> for the specified scope. * @param scope The specified scope. Either <code>ScriptContext.ENGINE_SCOPE</code>, * <code>ScriptContext.GLOBAL_SCOPE</code>, or any other valid value of scope. * * @throws IllegalArgumentException if the scope is invalid * @throws NullPointerException if the bindings is null and the scope is * <code>ScriptContext.ENGINE_SCOPE</code> */ public void setBindings(Bindings bindings, int scope); /** * Returns an uninitialized <code>Bindings</code>. * * @return A <code>Bindings</code> that can be used to replace the state of this <code>ScriptEngine</code>. **/ public Bindings createBindings(); /** * Returns the default <code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader * and Writers are used for script executions when no <code>ScriptContext</code> is specified. * * @return The default <code>ScriptContext</code> of the <code>ScriptEngine</code>. */ public ScriptContext getContext(); /** * Sets the default <code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader * and Writers are used for script executions when no <code>ScriptContext</code> is specified. * * @param context A <code>ScriptContext</code> that will replace the default <code>ScriptContext</code> in * the <code>ScriptEngine</code>. * @throws NullPointerException if context is null. */ public void setContext(ScriptContext context); /** * Returns a <code>ScriptEngineFactory</code> for the class to which this <code>ScriptEngine</code> belongs. * * @return The <code>ScriptEngineFactory</code> */ public ScriptEngineFactory getFactory(); }