Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
JavaFXScriptEngine |
|
| 0.0;0 |
1 | /* | |
2 | * Copyright 2007 Sun Microsystems, Inc. All Rights Reserved. | |
3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
4 | * | |
5 | * This code is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU General Public License version 2 only, as | |
7 | * published by the Free Software Foundation. Sun designates this | |
8 | * particular file as subject to the "Classpath" exception as provided | |
9 | * by Sun in the LICENSE file that accompanied this code. | |
10 | * | |
11 | * This code is distributed in the hope that it will be useful, but WITHOUT | |
12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
14 | * version 2 for more details (a copy is included in the LICENSE file that | |
15 | * accompanied this code). | |
16 | * | |
17 | * You should have received a copy of the GNU General Public License version | |
18 | * 2 along with this work; if not, write to the Free Software Foundation, | |
19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
20 | * | |
21 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, | |
22 | * CA 95054 USA or visit www.sun.com if you need additional information or | |
23 | * have any questions. | |
24 | */ | |
25 | ||
26 | package com.sun.javafx.api; | |
27 | ||
28 | import java.io.Reader; | |
29 | import javax.script.Bindings; | |
30 | import javax.script.Compilable; | |
31 | import javax.script.CompiledScript; | |
32 | import javax.script.Invocable; | |
33 | import javax.script.ScriptContext; | |
34 | import javax.script.ScriptEngine; | |
35 | import javax.script.ScriptException; | |
36 | import javax.tools.DiagnosticListener; | |
37 | import javax.tools.JavaFileObject; | |
38 | ||
39 | /** | |
40 | * The interface to the JavaFX Script scripting engine API. Its use is | |
41 | * optional, as full script functionality is available via the javax.script | |
42 | * API. In addition to the full script API, this interface defines versions | |
43 | * of the <code>eval</code> and <code>compile</code> <code>ScriptEngine</code> | |
44 | * methods which take a <code>DiagnosticListener</code> for accessing warning | |
45 | * and error diagnostics reported during script parsing. | |
46 | * | |
47 | * @author Tom Ball | |
48 | */ | |
49 | public interface JavaFXScriptEngine extends ScriptEngine, Compilable, Invocable { | |
50 | ||
51 | /** | |
52 | * Causes the immediate execution of the script whose source is the String | |
53 | * passed as the first argument. The script may be reparsed or recompiled | |
54 | * before execution. State left in the engine from previous executions, | |
55 | * including variable values and compiled procedures may be visible during | |
56 | * this execution. | |
57 | * | |
58 | * @param script The script to be executed by the script engine. | |
59 | * @param context A <code>ScriptContext</code> exposing sets of attributes in | |
60 | * different scopes. The meanings of the scopes | |
61 | * <code>ScriptContext.GLOBAL_SCOPE</code>, and | |
62 | * <code>ScriptContext.ENGINE_SCOPE</code> are defined in the | |
63 | * JSR-223 specification. | |
64 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
65 | * errors found during script parsing are reported. | |
66 | * @return The value returned from the execution of the script. | |
67 | * @throws ScriptException: if an error occurs in script. ScriptEngines | |
68 | * should create and throw ScriptException wrappers for checked | |
69 | * Exceptions thrown by underlying scripting implementations. | |
70 | * @throws NullPointerException: if either argument is null. | |
71 | */ | |
72 | Object eval(String script, ScriptContext context, | |
73 | DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
74 | ||
75 | /** | |
76 | * Same as <code>eval(String, ScriptContext, DiagnosticListener)</code> | |
77 | * where the source of the script is read from a Reader. | |
78 | * | |
79 | * @param reader The source of the script to be executed by the script engine. | |
80 | * @param context A <code>ScriptContext</code> exposing sets of attributes in | |
81 | * different scopes. The meanings of the scopes | |
82 | * <code>ScriptContext.GLOBAL_SCOPE</code>, and | |
83 | * <code>ScriptContext.ENGINE_SCOPE</code> are defined in the | |
84 | * JSR-223 specification. | |
85 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
86 | * errors found during script parsing are reported. | |
87 | * @return The value returned from the execution of the script. | |
88 | * @throws ScriptException: if an error occurs in script. ScriptEngines | |
89 | * should create and throw ScriptException wrappers for checked | |
90 | * Exceptions thrown by underlying scripting implementations. | |
91 | * @throws NullPointerException: if either argument is null. | |
92 | */ | |
93 | Object eval(Reader reader, ScriptContext context, | |
94 | DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
95 | ||
96 | /** | |
97 | * Executes the specified script. The default <code>ScriptContext</code> | |
98 | * for the <code>ScriptEngine</code> is used. | |
99 | * | |
100 | * @param script The script to be executed by the script engine. | |
101 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
102 | * errors found during script parsing are reported. | |
103 | * @return The value returned from the execution of the script. | |
104 | * @throws ScriptException: if an error occurs in script. ScriptEngines | |
105 | * should create and throw ScriptException wrappers for checked | |
106 | * Exceptions thrown by underlying scripting implementations. | |
107 | * @throws NullPointerException: if either argument is null. | |
108 | */ | |
109 | Object eval(String script, DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
110 | ||
111 | /** | |
112 | * Same as <code>eval(String)</code> except that the source of | |
113 | * the script is provided as a <code>Reader.</code> | |
114 | * | |
115 | * @param script The script to be executed by the script engine. | |
116 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
117 | * errors found during script parsing are reported. | |
118 | * @return The value returned from the execution of the script. | |
119 | * @throws ScriptException: if an error occurs in script. ScriptEngines | |
120 | * should create and throw ScriptException wrappers for checked | |
121 | * Exceptions thrown by underlying scripting implementations. | |
122 | * @throws NullPointerException: if either argument is null. | |
123 | */ | |
124 | Object eval(Reader script, DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
125 | ||
126 | /** | |
127 | * Executes the script using the <code>Bindings</code> argument as the | |
128 | * <code>ENGINE_SCOPE Bindings</code> of the <code>ScriptEngine</code> | |
129 | * during the script execution. The <code>Reader</code>, <code>Writer</code> | |
130 | * and non-<code>ENGINE_SCOPE Bindings</code> of the default | |
131 | * <code>ScriptContext</code> are used. The <code>ENGINE_SCOPE Bindings</code> | |
132 | * of the <code>ScriptEngine</code> is not changed, and its mappings are | |
133 | * unaltered by the script execution. | |
134 | * | |
135 | * @param script The source for the script. | |
136 | * @param bindings The Bindings of attributes to be used for script execution. | |
137 | * @return The value returned by the script. | |
138 | * @throws ScriptException: if an error occurrs in script. | |
139 | * @throws NullPointerException: if either argument is null. | |
140 | */ | |
141 | Object eval(String script, Bindings bindings, | |
142 | DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
143 | ||
144 | /** | |
145 | * Same as <code>eval(String, Bindings)</code> except that the source of | |
146 | * the script is provided as a <code>Reader.</code> | |
147 | * | |
148 | * @param reader The source for the script. | |
149 | * @param bindings The Bindings of attributes to be used for script execution. | |
150 | * @return The value returned by the script. | |
151 | * @throws ScriptException: if an error occurrs in script. | |
152 | * @throws NullPointerException: if either argument is null. | |
153 | */ | |
154 | Object eval(Reader reader, Bindings bindings, | |
155 | DiagnosticListener<JavaFileObject> listener) throws ScriptException; | |
156 | ||
157 | /** | |
158 | * Compiles the script (source represented as a <code>String</code>) for | |
159 | * later execution. | |
160 | * | |
161 | * @param script The source of the script, represented as a <code>String</code>. | |
162 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
163 | * errors found during script parsing are reported. | |
164 | * @return An subclass of <code>CompiledScript</code> to be executed later | |
165 | * using one of the eval methods of <code>CompiledScript</code>. | |
166 | * @throws ScriptException: if compilation fails. | |
167 | * @throws NullPointerException: if the argument is null. | |
168 | */ | |
169 | CompiledScript compile(String script, DiagnosticListener<JavaFileObject> listener) | |
170 | throws ScriptException; | |
171 | ||
172 | /** | |
173 | * Compiles the script (source read from <code>Reader</code>) for later | |
174 | * execution. Functionality is identical to <code>compile(String)</code> | |
175 | * other than the way in which the source is passed. | |
176 | * | |
177 | * @param script The reader from which the script source is obtained. | |
178 | * @param listener A <code>DiagnosticListener</code> to which warnings and | |
179 | * errors found during script parsing are reported. | |
180 | * @return An subclass of <code>CompiledScript</code> to be executed later | |
181 | * using one of the eval methods of <code>CompiledScript</code>. | |
182 | * @throws ScriptException: if compilation fails. | |
183 | * @throws NullPointerException: if the argument is null. | |
184 | */ | |
185 | CompiledScript compile(Reader script, DiagnosticListener<JavaFileObject> listener) | |
186 | throws ScriptException; | |
187 | } |