001: /*
002: * %W% %E% %U%
003: *
004: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
005: * SUN PROPRIETARY/CONFIDENTAIL. Use is subject to license terms.
006: */
007:
008: package javax.script;
009:
010: import java.io.Reader;
011: import java.util.Map;
012: import java.util.Set;
013:
014: /**
015: * <code>ScriptEngine</code> is the fundamental interface whose methods must be
016: * fully functional in every implementation of this specification.
017: * <br><br>
018: * These methods provide basic scripting functionality. Applications written to this
019: * simple interface are expected to work with minimal modifications in every implementation.
020: * It includes methods that execute scripts, and ones that set and get values.
021: * <br><br>
022: * The values are key/value pairs of two types. The first type of pairs consists of
023: * those whose keys are reserved and defined in this specification or by individual
024: * implementations. The values in the pairs with reserved keys have specified meanings.
025: * <br><br>
026: * The other type of pairs consists of those that create Java language Bindings, the values are
027: * usually represented in scripts by the corresponding keys or by decorated forms of them.
028: *
029: * @author Mike Grogan
030: * @version 1.0
031: * @since 1.6
032: */
033:
034: public interface ScriptEngine {
035:
036: /**
037: * Reserved key for a named value that passes
038: * an array of positional arguments to a script.
039: */
040: public static final String ARGV = "javax.script.argv";
041:
042: /**
043: * Reserved key for a named value that is
044: * the name of the file being executed.
045: */
046: public static final String FILENAME = "javax.script.filename";
047:
048: /**
049: * Reserved key for a named value that is
050: * the name of the <code>ScriptEngine</code> implementation.
051: */
052: public static final String ENGINE = "javax.script.engine";
053:
054: /**
055: * Reserved key for a named value that identifies
056: * the version of the <code>ScriptEngine</code> implementation.
057: */
058: public static final String ENGINE_VERSION = "javax.script.engine_version";
059:
060: /**
061: * Reserved key for a named value that identifies
062: * the short name of the scripting language. The name is used by the
063: * <code>ScriptEngineManager</code> to locate a <code>ScriptEngine</code>
064: * with a given name in the <code>getEngineByName</code> method.
065: */
066: public static final String NAME = "javax.script.name";
067:
068: /**
069: * Reserved key for a named value that is
070: * the full name of Scripting Language supported by the implementation.
071: */
072: public static final String LANGUAGE = "javax.script.language";
073:
074: /**
075: * Reserved key for the named value that identifies
076: * the version of the scripting language supported by the implementation.
077: */
078: public static final String LANGUAGE_VERSION = "javax.script.language_version";
079:
080: /**
081: * Causes the immediate execution of the script whose source is the String
082: * passed as the first argument. The script may be reparsed or recompiled before
083: * execution. State left in the engine from previous executions, including
084: * variable values and compiled procedures may be visible during this execution.
085: *
086: * @param script The script to be executed by the script engine.
087: *
088: * @param context A <code>ScriptContext</code> exposing sets of attributes in
089: * different scopes. The meanings of the scopes <code>ScriptContext.GLOBAL_SCOPE</code>,
090: * and <code>ScriptContext.ENGINE_SCOPE</code> are defined in the specification.
091: * <br><br>
092: * The <code>ENGINE_SCOPE</code> <code>Bindings</code> of the <code>ScriptContext</code> contains the
093: * bindings of scripting variables to application objects to be used during this
094: * script execution.
095: *
096: *
097: * @return The value returned from the execution of the script.
098: *
099: * @throws ScriptException if an error occurrs. ScriptEngines should create and throw
100: * <code>ScriptException</code> wrappers for checked Exceptions thrown by underlying scripting
101: * implementations.
102: * @throws NullPointerException if either argument is null.
103: *
104: *
105: *
106: */
107: public Object eval(String script, ScriptContext context)
108: throws ScriptException;
109:
110: /**
111: * Same as <code>eval(String, ScriptContext)</code> where the source of the script
112: * is read from a <code>Reader</code>.
113: *
114: * @param reader The source of the script to be executed by the script engine.
115: *
116: * @param context The <code>ScriptContext</code> passed to the script engine.
117: *
118: * @return The value returned from the execution of the script.
119: *
120: * @throws ScriptException if an error occurrs.
121: * @throws NullPointerException if either argument is null.<p>
122: *
123: */
124: public Object eval(Reader reader, ScriptContext context)
125: 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: */
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: */
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: */
171: public Object eval(String script, Bindings n)
172: throws ScriptException;
173:
174: /**
175: * Same as <code>eval(String, Bindings)</code> except that the source of the script
176: * is provided as a <code>Reader</code>.
177: *
178: * @param reader The source of the script.
179: * @param n The <code>Bindings</code> of attributes.
180: *
181: * @return The value returned by the script.
182: *
183: * @throws ScriptException if an error occurrs.
184: * @throws NullPointerException if either argument is null.
185: */
186: public Object eval(Reader reader, Bindings n)
187: throws ScriptException;
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: */
199: public void put(String key, Object value);
200:
201: /**
202: * Retrieves a value set in the state of this engine. The value might be one
203: * which was set using <code>setValue</code> or some other value in the state
204: * of the <code>ScriptEngine</code>, depending on the implementation. Must have the same effect
205: * as <code>getBindings(ScriptContext.ENGINE_SCOPE).get</code>
206: *
207: * @param key The key whose value is to be returned
208: * @return the value for the given key
209: */
210: public Object get(String key);
211:
212: /**
213: * Returns a scope of named values. The possible scopes are:
214: * <br><br>
215: * <ul>
216: * <li><code>ScriptContext.GLOBAL_SCOPE</code> - A set of named values shared by all ScriptEngines
217: * created by the same ScriptEngineFactory. If the <code>ScriptEngine</code> is created by a
218: * <code>ScriptEngineManager</code>, a reference to the global scope stored by the
219: * <code>ScriptEngineManager</code> should be returned. May return <code>null</code> if no global scope
220: * is associated with this <code>ScriptEngine</code></li>
221: * <li><code>ScriptContext.ENGINE_SCOPE</code> - The set of named values representing the state of
222: * this <code>ScriptEngine</code>. The values are generally visible in scripts using
223: * the associated keys as variable names.</li>
224: * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
225: * </li>
226: * </ul>
227: * <br><br>
228: * The <code>Bindings</code> instances that are returned must be identical to those returned by the
229: * <code>getBindings</code> method of <code>ScriptContext</code> called with corresponding arguments on
230: * the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
231: *
232: * @param scope Either <code>ScriptContext.ENGINE_SCOPE</code> or <code>ScriptContext.GLOBAL_SCOPE</code>
233: * which specifies the <code>Bindings</code> to return. Implementations of <code>ScriptContext</code>
234: * may define additional scopes. If the default <code>ScriptContext</code> of the <code>ScriptEngine</code>
235: * defines additional scopes, any of them can be passed to get the corresponding <code>Bindings</code>.
236: *
237: * @return The <code>Bindings</code> with the specified scope.
238: *
239: * @throws IllegalArgumentException if specified scope is invalid
240: *
241: */
242: public Bindings getBindings(int scope);
243:
244: /**
245: * Sets a scope of named values to be used by scripts. The possible scopes are:
246: *<br><br>
247: * <ul>
248: * <li><code>ScriptContext.ENGINE_SCOPE</code> - The specified <code>Bindings</code> replaces the
249: * engine scope of the <code>ScriptEngine</code>.
250: * </li>
251: * <li><code>ScriptContext.GLOBAL_SCOPE</code> - The specified <code>Bindings</code> must be visible
252: * as the <code>GLOBAL_SCOPE</code>.
253: * </li>
254: * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
255: *</li>
256: * </ul>
257: * <br><br>
258: * The method must have the same effect as calling the <code>setBindings</code> method of
259: * <code>ScriptContext</code> with the corresponding value of <code>scope</code> on the default
260: * <code>ScriptContext</code> of the <code>ScriptEngine</code>.
261: *
262: * @param bindings The <code>Bindings</code> for the specified scope.
263: * @param scope The specified scope. Either <code>ScriptContext.ENGINE_SCOPE</code>,
264: * <code>ScriptContext.GLOBAL_SCOPE</code>, or any other valid value of scope.
265: *
266: * @throws IllegalArgumentException if the scope is invalid
267: */
268: public void setBindings(Bindings bindings, int scope);
269:
270: /**
271: * Returns an uninitialized <code>Bindings</code>.
272: *
273: * @return A <code>Bindings</code> that can be used to replace the state of this <code>ScriptEngine</code>.
274: **/
275: public Bindings createBindings();
276:
277: /**
278: * Returns the default <code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader
279: * and Writers are used for script executions when no <code>ScriptContext</code> is specified.
280: *
281: * @return The default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
282: */
283: public ScriptContext getContext();
284:
285: /**
286: * Sets the default code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader
287: * and Writers are used for script executions when no <code>ScriptContext</code> is specified.
288: *
289: * @param context - A <code>ScriptContext</code> that will replace the default <code>ScriptContext</code> in
290: * the <code>ScriptEngine</code>.
291: */
292: public void setContext(ScriptContext context);
293:
294: /**
295: * Returns a <code>ScriptEngineFactory</code> for the class to which this <code>ScriptEngine</code> belongs.
296: * The returned <code>ScriptEngineFactory</code> implements <code>ScriptEngineInfo</code>, which describes
297: * attributes of this <code>ScriptEngine</code> implementation.
298: *
299: * @return The <code>ScriptEngineFactory</code>
300: */
301: public ScriptEngineFactory getFactory();
302:
303: }
|