ScriptEngine


1   /*
2    * @(#)ScriptEngine.java    1.5 06/06/19 20:53:06
3    *
4    * Copyright 2006 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 in script. 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     public Object   eval(String   script, ScriptContext context) throws ScriptException;
106     
107     
108     /**
109      * Same as <code>eval(String, ScriptContext)</code> where the source of the script
110      * is read from a <code>Reader</code>.
111      *
112      * @param reader The source of the script to be executed by the script engine.
113      *
114      * @param context The <code>ScriptContext</code> passed to the script engine.
115      *
116      * @return The value returned from the execution of the script.
117      *
118      * @throws ScriptException if an error occurrs in script.
119      * @throws NullPointerException if either argument is null.
120      */
121     public Object   eval(Reader   reader , ScriptContext context) throws ScriptException;
122     
123     /**
124      * Executes the specified script.  The default <code>ScriptContext</code> for the <code>ScriptEngine</code>
125      * is used.
126      *
127      * @param script The script language source to be executed.
128      *
129      * @return The value returned from the execution of the script.
130      *
131      * @throws ScriptException if error occurrs in script.
132      * @throws NullPointerException if the argument is null.
133      */
134     public Object   eval(String   script) throws ScriptException;
135     
136     /**
137      * Same as <code>eval(String)</code> except that the source of the script is
138      * provided as a <code>Reader</code>
139      *
140      * @param reader The source of the script.
141      *
142      * @return The value returned by the script.
143      *
144      * @throws ScriptException if an error occurrs in script.
145      * @throws NullPointerException if the argument is null.
146      */
147     public Object   eval(Reader   reader) throws ScriptException;
148     
149     /**
150      * Executes the script using the <code>Bindings</code> argument as the <code>ENGINE_SCOPE</code>
151      * <code>Bindings</code> of the <code>ScriptEngine</code> during the script execution.  The
152      * <code>Reader</code>, <code>Writer</code> and non-<code>ENGINE_SCOPE</code> <code>Bindings</code> of the
153      * default <code>ScriptContext</code> are used. The <code>ENGINE_SCOPE</code>
154      * <code>Bindings</code> of the <code>ScriptEngine</code> is not changed, and its
155      * mappings are unaltered by the script execution.
156      *
157      * @param script The source for the script.
158      *
159      * @param n The <code>Bindings</code> of attributes to be used for script execution.
160      *
161      * @return The value returned by the script.
162      *
163      * @throws ScriptException if an error occurrs in script.
164      * @throws NullPointerException if either argument is null.
165      */
166     public Object   eval(String   script, Bindings n) throws ScriptException;
167     
168     /**
169      * Same as <code>eval(String, Bindings)</code> except that the source of the script
170      * is provided as a <code>Reader</code>.
171      *
172      * @param reader The source of the script.
173      * @param n The <code>Bindings</code> of attributes.
174      *
175      * @return The value returned by the script.
176      *
177      * @throws ScriptException if an error occurrs.
178      * @throws NullPointerException if either argument is null.
179      */
180     public Object   eval(Reader   reader , Bindings n) throws ScriptException;
181     
182     
183     
184     /**
185      * Sets a key/value pair in the state of the ScriptEngine that may either create
186      * a Java Language Binding to be used in the execution of scripts or be used in some
187      * other way, depending on whether the key is reserved.  Must have the same effect as
188      * <code>getBindings(ScriptContext.ENGINE_SCOPE).put</code>.
189      *
190      * @param key The name of named value to add
191      * @param value The value of named value to add.
192      *
193      * @throws NullPointerException if key is null.
194      * @throws IllegalArgumentException if key is empty.
195      */
196     public void put(String   key, Object   value);
197     
198     
199     /**
200      * Retrieves a value set in the state of this engine.  The value might be one
201      * which was set using <code>setValue</code> or some other value in the state
202      * of the <code>ScriptEngine</code>, depending on the implementation.  Must have the same effect
203      * as <code>getBindings(ScriptContext.ENGINE_SCOPE).get</code>
204      *
205      * @param key The key whose value is to be returned
206      * @return the value for the given key
207      *
208      * @throws NullPointerException if key is null.
209      * @throws IllegalArgumentException if key is empty.
210      */
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> - The set of named values representing global
219      * scope. If this <code>ScriptEngine</code> is created by a <code>ScriptEngineManager</code>, 
220      * then the manager sets global scope bindings. This may be <code>null</code> if no global 
221      * scope is associated with this <code>ScriptEngine</code></li>
222      * <li><code>ScriptContext.ENGINE_SCOPE</code> - The set of named values representing the state of
223      * this <code>ScriptEngine</code>.  The values are generally visible in scripts using
224      * the associated keys as variable names.</li>
225      * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
226      * </li>
227      * </ul>
228      * <br><br>
229      * The <code>Bindings</code> instances that are returned must be identical to those returned by the
230      * <code>getBindings</code> method of <code>ScriptContext</code> called with corresponding arguments on
231      * the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
232      *
233      * @param scope Either <code>ScriptContext.ENGINE_SCOPE</code> or <code>ScriptContext.GLOBAL_SCOPE</code>
234      * which specifies the <code>Bindings</code> to return.  Implementations of <code>ScriptContext</code>
235      * may define additional scopes.  If the default <code>ScriptContext</code> of the <code>ScriptEngine</code>
236      * defines additional scopes, any of them can be passed to get the corresponding <code>Bindings</code>.
237      *
238      * @return The <code>Bindings</code> with the specified scope.
239      *
240      * @throws IllegalArgumentException if specified scope is invalid
241      *
242      */
243     public Bindings getBindings(int scope);
244     
245     /**
246      * Sets a scope of named values to be used by scripts.  The possible scopes are:
247      *<br><br>
248      * <ul>
249      * <li><code>ScriptContext.ENGINE_SCOPE</code> - The specified <code>Bindings</code> replaces the
250      * engine scope of the <code>ScriptEngine</code>.
251      * </li>
252      * <li><code>ScriptContext.GLOBAL_SCOPE</code> - The specified <code>Bindings</code> must be visible
253      * as the <code>GLOBAL_SCOPE</code>.
254      * </li>
255      * <li>Any other value of scope defined in the default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
256      *</li>
257      * </ul>
258      * <br><br>
259      * The method must have the same effect as calling the <code>setBindings</code> method of
260      * <code>ScriptContext</code> with the corresponding value of <code>scope</code> on the default
261      * <code>ScriptContext</code> of the <code>ScriptEngine</code>.
262      *
263      * @param bindings The <code>Bindings</code> for the specified scope.
264      * @param scope The specified scope.  Either <code>ScriptContext.ENGINE_SCOPE</code>,
265      * <code>ScriptContext.GLOBAL_SCOPE</code>, or any other valid value of scope.
266      *
267      * @throws IllegalArgumentException if the scope is invalid
268      * @throws NullPointerException if the bindings is null and the scope is
269      * <code>ScriptContext.ENGINE_SCOPE</code>
270      */
271     public void setBindings(Bindings bindings, int scope);
272     
273     
274     /**
275      * Returns an uninitialized <code>Bindings</code>.
276      *
277      * @return A <code>Bindings</code> that can be used to replace the state of this <code>ScriptEngine</code>.
278      **/
279     public Bindings createBindings();
280     
281     
282     /**
283      * Returns the default <code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader
284      * and Writers are used for script executions when no <code>ScriptContext</code> is specified.
285      *
286      * @return The default <code>ScriptContext</code> of the <code>ScriptEngine</code>.
287      */
288     public ScriptContext getContext();
289     
290     /**
291      * Sets the default <code>ScriptContext</code> of the <code>ScriptEngine</code> whose Bindings, Reader
292      * and Writers are used for script executions when no <code>ScriptContext</code> is specified.
293      *
294      * @param context A <code>ScriptContext</code> that will replace the default <code>ScriptContext</code> in
295      * the <code>ScriptEngine</code>.
296      * @throws NullPointerException if context is null.
297      */
298     public void setContext(ScriptContext context);
299     
300     /**
301      * Returns a <code>ScriptEngineFactory</code> for the class to which this <code>ScriptEngine</code> belongs.
302      *
303      * @return The <code>ScriptEngineFactory</code>
304      */
305     public ScriptEngineFactory getFactory();
306 }
307
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags