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