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