|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
2 <html class=" regenabled gecko radius jsenabled regloaded" xmlns="http://www.w3.org/1999/xhtml"><head> |
|
3 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"> |
|
4 <title>Java Scripting Programmer's Guide</title> |
|
5 |
|
6 <!-- ============ --> |
|
7 <!-- MAIN CONTENT --> |
|
8 <!-- ============ --> |
|
9 <table summary="layout" border="0" width="100%"> |
|
10 <tbody><tr> |
|
11 <td> |
|
12 |
|
13 <div id="sharepage" class="smallpagetitle"><h1>Java Scripting Programmer's Guide</h1><div class="sharepage"> <div class="sharepagew1 share-mailto"> <table summary="" cellpadding="0" cellspacing="0"><tbody><tr> <td id="share-mailto"><a href="mailto:?subject=Java%20Documentation%20Page:%20Java%20Scripting%20Programmer%27s%20Guide&body=Check%20out%20this%20page:%20%0A%0Ahttp%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink mailto" title="Email this page to a friend"></a></td> <td id="share-technorati"><a href="http://technorati.com/search/http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink technorati" title="See who links to this page on Technorati"></a></td> <td id="share-delicious"><a href="http://del.icio.us/post?v=4;url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html;title=Java%20Scripting%20Programmer%27s%20Guide" class="sharelink delicious" title="Bookmark this page in del.icio.us"></a></td> <td id="share-digg"><a href="http://digg.com/submit?phase=2&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html&title=Java%20Scripting%20Programmer%27s%20Guide" class="sharelink digg" title="Submit this page to Digg"></a></td> <td id="share-slashdot"><a href="http://slashdot.org/bookmark.pl?title=Java%20Scripting%20Programmer%27s%20Guide&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink slashdot" title="Submit this page to Slashdot"></a></td> <td id="share-blank"> </td></tr></tbody></table></div></div></div> |
|
14 |
|
15 </td> |
|
16 </tr> |
|
17 </tbody></table> |
|
18 <!-- Body text begins here --> |
|
19 <ul> |
|
20 <li><span><a href="#who">Who is the Java Scripting API |
|
21 For?</a></span></li> |
|
22 <li><span><a href="#package">Scripting Package</a></span></li> |
|
23 <li><span><a href="#examples">Examples</a></span> |
|
24 <ul> |
|
25 <li><span><a href="#helloworld">"Hello, World"</a></span></li> |
|
26 <li><span><a href="#evalfile">Evaluating a Script |
|
27 File</a></span></li> |
|
28 <li><span><a href="#scriptvars">Script Variables</a></span></li> |
|
29 <li><span><a href="#invoke">Invoking Script Functions and |
|
30 Methods</a></span></li> |
|
31 <li><span><a href="#interfaces">Implementing Java Interfaces by |
|
32 Scripts</a></span></li> |
|
33 <li><span><a href="#scopes">Multiple Scopes for |
|
34 Scripts</a></span></li> |
|
35 </ul> |
|
36 </li> |
|
37 <li><span><a href="#jsengine">JavaScript Script |
|
38 Engine</a></span></li> |
|
39 <li><span><a href="#jstojava">JavaScript to Java |
|
40 Communication</a></span> |
|
41 <ul> |
|
42 <li><span><a href="#jsjavaclass">Accessing Java |
|
43 Classes</a></span></li> |
|
44 <li><span><a href="#jsimport">Importing Java Packages, |
|
45 Classes</a></span></li> |
|
46 <li><span><a href="#jsarrays">Creating, Converting and Using Java |
|
47 Arrays</a></span></li> |
|
48 <li><span><a href="#jsimplement">Implementing Java |
|
49 Interfaces</a></span></li> |
|
50 <li><span><a href="#jsextend">Extending Java classes |
|
51 </a></span></li> |
|
52 <li><span><a href="#jsoverload">Overload Resolution</a></span></li> |
|
53 </ul> |
|
54 </li> |
|
55 <li><span><a href="#engineimpl">Implementing Your Own Script |
|
56 Engine</a></span></li> |
|
57 <li><span><a href="#refs">References</a></span></li> |
|
58 </ul> |
|
59 <span><a name="who" id="who"></a></span> |
|
60 <h2><span>Who is the Java Scripting API For?</span></h2> |
|
61 <span>Some useful characteristics of scripting languages |
|
62 are:</span> |
|
63 <ul> |
|
64 <li><span><b>Convenience</b>: Most scripting languages are |
|
65 dynamically typed. You can usually create new variables without |
|
66 declaring the variable type, and you can reuse variables to store |
|
67 objects of different types. Also, scripting languages tend to |
|
68 perform many type conversions automatically, for example, |
|
69 converting the number 10 to the text "10" as necessary.</span></li> |
|
70 <li><span><b>Developing rapid prototypes</b>: You can avoid the |
|
71 edit-compile-run cycle and just use edit-run!</span></li> |
|
72 <li><span><b>Application extension/customization</b>: You can |
|
73 "externalize" parts of your application - like configuration |
|
74 scripts, business logic/rules and math expressions for financial |
|
75 applications.</span></li> |
|
76 <li><span><b>"Command line" shells for applications</b> -for |
|
77 debugging, runtime/deploy time configuration etc. Most applications |
|
78 have a web-based GUI configuaration tool these days. But |
|
79 sysadmins/deployers frequently prefer command line tools. Instead |
|
80 of inventing ad-hoc scripting language for that purpose, a |
|
81 "standard" scripting language can be used.</span></li> |
|
82 </ul> |
|
83 <p><span>The Java<font size="-1"><sup>TM</sup></font> Scripting API |
|
84 is a scripting language indepedent framework for using script |
|
85 engines from Java code. With the Java Scripting API, it is possible |
|
86 to write customizable/extendable applications in the Java language |
|
87 and leave the customization scripting language choice to the end |
|
88 user. The Java application developer need not choose the extension |
|
89 language during development. If you write your application with |
|
90 JSR-223 API, then your users can use any JSR-223 compliant |
|
91 scripting language.</span></p> |
|
92 <hr> |
|
93 <span><a name="package" id="package"></a></span> |
|
94 <h2><span>Scripting Package</span></h2> |
|
95 <p><span>The Java Scripting functionality is in the <code><a href="http://docs.oracle.com/javase/6/docs/api/javax/script/package-summary.html">javax.script</a></code> |
|
96 package. This is a relatively small, simple API. The starting point |
|
97 of the scripting API is the <code>ScriptEngineManager</code> class. |
|
98 A ScriptEngineManager object can discover script engines through |
|
99 the jar file service discovery mechanism. It can also instantiate |
|
100 ScriptEngine objects that interpret scripts written in a specific |
|
101 scripting language. The simplest way to use the scripting API is as |
|
102 follows:</span></p> |
|
103 <ol> |
|
104 <li><span>Create a <code>ScriptEngineManager</code> |
|
105 object.</span></li> |
|
106 <li><span>Get a <code>ScriptEngine</code> object from the |
|
107 manager.</span></li> |
|
108 <li><span>Evaluate script using the <code>ScriptEngine</code>'s |
|
109 <code>eval</code> methods.</span></li> |
|
110 </ol> |
|
111 <p><span>Now, it is time to look at some sample code. While it is |
|
112 not mandatory, it may be useful to know a bit of JavaScript to read |
|
113 these examples.</span></p> |
|
114 <hr> |
|
115 <span><a name="examples" id="examples"></a></span> |
|
116 <h2><span>Examples</span></h2> |
|
117 <span><a name="helloworld" id="helloworld"></a></span> |
|
118 <h3><span>"Hello, World"</span></h3> |
|
119 <p><span>From the <code>ScriptEngineManager</code> instance, we |
|
120 request a JavaScript engine instance using |
|
121 <code>getEngineByName</code> method. On the script engine, the |
|
122 <code>eval</code> method is called to execute a given String as |
|
123 JavaScript code! For brevity, in this as well as in subsequent |
|
124 examples, we have not shown exception handling. There are checked |
|
125 and runtime exceptions thrown from <code>javax.script</code> API. |
|
126 Needless to say, you have to handle the exceptions |
|
127 appropriately.</span></p> |
|
128 <pre> |
|
129 <span><code> |
|
130 // <a href="source/EvalScript.java">EvalScript.java</a> |
|
131 |
|
132 import javax.script.*; |
|
133 public class EvalScript { |
|
134 public static void main(String[] args) throws Exception { |
|
135 // create a script engine manager |
|
136 <span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager(); |
|
137 // create a JavaScript engine |
|
138 <span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn"); |
|
139 // evaluate JavaScript code from String |
|
140 engine.<span class="methodref">eval</span>("print('Hello, World')"); |
|
141 } |
|
142 } |
|
143 </code></span> |
|
144 </pre> |
|
145 <hr> |
|
146 <a name="evalfile" id="evalfile"></a> |
|
147 <h3>Evaluating a Script File</h3> |
|
148 <p>In this example, we call the <code>eval</code> method that |
|
149 accepts <code>java.io.Reader</code> for the input source. The |
|
150 script read by the given reader is executed. This way it is |
|
151 possible to execute scripts from files, URLs and resources by |
|
152 wrapping the relevant input stream objects as readers.</p> |
|
153 <pre> |
|
154 <code> |
|
155 // <a href="source/EvalFile.java">EvalFile.java</a> |
|
156 |
|
157 import javax.script.*; |
|
158 |
|
159 public class EvalFile { |
|
160 public static void main(String[] args) throws Exception { |
|
161 // create a script engine manager |
|
162 <span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager(); |
|
163 // create JavaScript engine |
|
164 <span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn"); |
|
165 // evaluate JavaScript code from given file - specified by first argument |
|
166 engine.<span class="methodref">eval</span>(new java.io.FileReader(args[0])); |
|
167 } |
|
168 } |
|
169 </code> |
|
170 </pre> |
|
171 Let us assume that we have the file named <a href="source/test.js">test.js</a> with the |
|
172 following text: |
|
173 <pre><code> |
|
174 print("This is hello from test.js"); |
|
175 </code> |
|
176 </pre> |
|
177 We can run the above Java as |
|
178 <pre><code> |
|
179 java EvalFile test.js |
|
180 </code> |
|
181 </pre> |
|
182 <hr> |
|
183 <a name="scriptvars" id="scriptvars"></a> |
|
184 <h3>Script Variables</h3> |
|
185 <p>When you embed script engines and scripts with your Java |
|
186 application, you may want to expose your application objects as |
|
187 global variables to scripts. This example demonstrates how you can |
|
188 expose your application objects as global variables to a script. We |
|
189 create a <code>java.io.File</code> in the application and expose |
|
190 the same as a global variable with the name "file". The script can |
|
191 access the variable - for example, it can call public methods on |
|
192 it. Note that the syntax to access Java objects, methods and fields |
|
193 is dependent on the scripting language. JavaScript supports the |
|
194 most "natural" Java-like syntax.</p> |
|
195 <pre><code> |
|
196 // <a href="source/ScriptVars.java">ScriptVars.java</a> |
|
197 |
|
198 import javax.script.*; |
|
199 import java.io.*; |
|
200 |
|
201 public class ScriptVars { |
|
202 public static void main(String[] args) throws Exception { |
|
203 ScriptEngineManager manager = new ScriptEngineManager(); |
|
204 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
205 |
|
206 File f = new File("test.txt"); |
|
207 // expose File object as variable to script |
|
208 engine.<span class="methodref">put</span>("file", f); |
|
209 |
|
210 // evaluate a script string. The script accesses "file" |
|
211 // variable and calls method on it |
|
212 engine.eval("print(file.getAbsolutePath())"); |
|
213 } |
|
214 } |
|
215 |
|
216 </code> |
|
217 </pre> |
|
218 <hr> |
|
219 <a name="invoke" id="invoke"></a> |
|
220 <h3>Invoking Script Functions and Methods</h3> |
|
221 <p>Sometimes you may want to call a specific scripting function |
|
222 repeatedly - for example, your application menu functionality might |
|
223 be implemented by a script. In your menu's action event handler you |
|
224 may want to call a specific script function. The following example |
|
225 demonstrates invoking a specific script function from Java |
|
226 code.</p> |
|
227 <pre><code> |
|
228 // <a href="source/InvokeScriptFunction.java">InvokeScriptFunction.java</a> |
|
229 |
|
230 import javax.script.*; |
|
231 |
|
232 public class InvokeScriptFunction { |
|
233 public static void main(String[] args) throws Exception { |
|
234 ScriptEngineManager manager = new ScriptEngineManager(); |
|
235 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
236 |
|
237 // JavaScript code in a String |
|
238 String script = "function hello(name) { print('Hello, ' + name); }"; |
|
239 // evaluate script |
|
240 engine.eval(script); |
|
241 |
|
242 // <code>javax.script.Invocable</code> is an optional interface. |
|
243 // Check whether your script engine implements it or not! |
|
244 // Note that the JavaScript engine implements Invocable interface. |
|
245 <span class="classref">Invocable</span> inv = (Invocable) engine; |
|
246 |
|
247 // invoke the global function named "hello" |
|
248 inv.<span class="methodref">invokeFunction</span>("hello", "Scripting!!" ); |
|
249 } |
|
250 } |
|
251 |
|
252 </code> |
|
253 </pre> |
|
254 <p>If your scripting language is object based (like JavaScript) or |
|
255 object-oriented, then you can invoke a script method on a script |
|
256 object.</p> |
|
257 <pre><code> |
|
258 // <a href="source/InvokeScriptMethod.java">InvokeScriptMethod.java</a> |
|
259 |
|
260 import javax.script.*; |
|
261 |
|
262 public class InvokeScriptMethod { |
|
263 public static void main(String[] args) throws Exception { |
|
264 ScriptEngineManager manager = new ScriptEngineManager(); |
|
265 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
266 |
|
267 // JavaScript code in a String. This code defines a script object 'obj' |
|
268 // with one method called 'hello'. |
|
269 String script = "var obj = new Object(); obj.hello = function(name) { print('Hello, ' + name); }"; |
|
270 // evaluate script |
|
271 engine.eval(script); |
|
272 |
|
273 // <code>javax.script.Invocable</code> is an optional interface. |
|
274 // Check whether your script engine implements or not! |
|
275 // Note that the JavaScript engine implements Invocable interface. |
|
276 <span class="classref">Invocable</span> inv = (Invocable) engine; |
|
277 |
|
278 // get script object on which we want to call the method |
|
279 Object obj = engine.<span class="methodref">get</span>("obj"); |
|
280 |
|
281 // invoke the method named "hello" on the script object "obj" |
|
282 inv.<span class="methodref">invokeMethod</span>(obj, "hello", "Script Method !!" ); |
|
283 } |
|
284 } |
|
285 |
|
286 </code> |
|
287 </pre> |
|
288 <hr> |
|
289 <a name="interfaces" id="interfaces"></a> |
|
290 <h3>Implementing Java Interfaces by Scripts</h3> |
|
291 <p>Instead of calling specific script functions from Java, |
|
292 sometimes it is convenient to implement a Java interface by script |
|
293 functions or methods. Also, by using interfaces we can avoid having |
|
294 to use the <code>javax.script</code> API in many places. We can get |
|
295 an interface implementor object and pass it to various Java APIs. |
|
296 The following example demonstrates implementing the |
|
297 <code>java.lang.Runnable</code> interface with a script.</p> |
|
298 <pre><code> |
|
299 // <a href="source/RunnableImpl.java">RunnableImpl.java</a> |
|
300 |
|
301 import javax.script.*; |
|
302 |
|
303 public class RunnableImpl { |
|
304 public static void main(String[] args) throws Exception { |
|
305 ScriptEngineManager manager = new ScriptEngineManager(); |
|
306 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
307 |
|
308 // JavaScript code in a String |
|
309 String script = "function run() { print('run called'); }"; |
|
310 |
|
311 // evaluate script |
|
312 engine.eval(script); |
|
313 |
|
314 <span class="classref">Invocable</span> inv = (Invocable) engine; |
|
315 |
|
316 // get Runnable interface object from engine. This interface methods |
|
317 // are implemented by script functions with the matching name. |
|
318 Runnable r = inv.<span class="methodref">getInterface</span>(Runnable.class); |
|
319 |
|
320 // start a new thread that runs the script implemented |
|
321 // runnable interface |
|
322 Thread th = new Thread(r); |
|
323 th.start(); |
|
324 th.join(); |
|
325 } |
|
326 } |
|
327 </code> |
|
328 </pre> |
|
329 <p>If your scripting language is object-based or object-oriented, |
|
330 it is possible to implement a Java interface by script methods on |
|
331 script objects. This avoids having to call script global functions |
|
332 for interface methods. The script object can store the "state" |
|
333 associated with the interface implementor.</p> |
|
334 <pre><code> |
|
335 // <a href="source/RunnableImplObject.java">RunnableImplObject.java</a> |
|
336 |
|
337 import javax.script.*; |
|
338 |
|
339 public class RunnableImplObject { |
|
340 public static void main(String[] args) throws Exception { |
|
341 ScriptEngineManager manager = new ScriptEngineManager(); |
|
342 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
343 |
|
344 // JavaScript code in a String |
|
345 String script = "var obj = new Object(); obj.run = function() { print('run method called'); }"; |
|
346 |
|
347 // evaluate script |
|
348 engine.eval(script); |
|
349 |
|
350 // get script object on which we want to implement the interface with |
|
351 Object obj = engine.<span class="methodref">get</span>("obj"); |
|
352 |
|
353 <span class="classref">Invocable</span> inv = (Invocable) engine; |
|
354 |
|
355 // get Runnable interface object from engine. This interface methods |
|
356 // are implemented by script methods of object 'obj' |
|
357 Runnable r = inv.<span class="methodref">getInterface</span>(obj, Runnable.class); |
|
358 |
|
359 // start a new thread that runs the script implemented |
|
360 // runnable interface |
|
361 Thread th = new Thread(r); |
|
362 th.start(); |
|
363 th.join(); |
|
364 } |
|
365 } |
|
366 </code> |
|
367 </pre> |
|
368 <hr> |
|
369 <a name="scopes" id="scopes"></a> |
|
370 <h3>Multiple Scopes for Scripts</h3> |
|
371 <p>In the <a href="#scriptvars">script variables</a> example, we |
|
372 saw how to expose application objects as script global variables. |
|
373 It is possible to expose multiple global "scopes" for scripts. A |
|
374 single scope is an instance of <code>javax.script.Bindings</code>. |
|
375 This interface is derived from <code>java.util.Map<String, |
|
376 Object></code>. A scope a set of name-value pairs where name is |
|
377 any non-empty, non-null String. |
|
378 <code>javax.script.ScriptContext</code> interface supports multiple |
|
379 scopes with associated Bindings for each |
|
380 scope. By default, every script engine has a default script |
|
381 context. The default script context has atleast one scope called |
|
382 "ENGINE_SCOPE". Various scopes supported by a script context are |
|
383 available through <code>getScopes</code> method.</p> |
|
384 <pre><code> |
|
385 // <a href="source/MultiScopes.java">MultiScopes.java</a> |
|
386 |
|
387 import javax.script.*; |
|
388 |
|
389 public class MultiScopes { |
|
390 public static void main(String[] args) throws Exception { |
|
391 ScriptEngineManager manager = new ScriptEngineManager(); |
|
392 ScriptEngine engine = manager.getEngineByName("nashorn"); |
|
393 |
|
394 engine.put("x", "hello"); |
|
395 // print global variable "x" |
|
396 engine.eval("print(x);"); |
|
397 // the above line prints "hello" |
|
398 |
|
399 // Now, pass a different script context |
|
400 <span class="classref">ScriptContext</span> newContext = new <span class="classref">SimpleScriptContext</span>(); |
|
401 newContext.setBindings(engine.createBindings(), ScriptContext.ENGINE_SCOPE); |
|
402 <span class="classref">Bindings</span> engineScope = newContext.<span class="methodref">getBindings</span>(ScriptContext.ENGINE_SCOPE); |
|
403 |
|
404 // add new variable "x" to the new engineScope |
|
405 engineScope.<span class="methodref">put</span>("x", "world"); |
|
406 |
|
407 // execute the same script - but this time pass a different script context |
|
408 engine.eval("print(x);", newContext); |
|
409 // the above line prints "world" |
|
410 } |
|
411 } |
|
412 |
|
413 </code> |
|
414 </pre> |
|
415 <hr> |
|
416 <a name="jsengine" id="jsengine"></a> |
|
417 <h2>JavaScript Script Engine</h2> |
|
418 <p>Oracle's implementation of JDK 8 is co-bundled with the Nashorn ECMAScript |
|
419 script engine. |
|
420 <hr> |
|
421 <a name="jstojava" id="jstojava"></a> |
|
422 <h2>JavaScript to Java Communication</h2> |
|
423 <p>For the most part, accessing Java classes, objects and methods |
|
424 is straightforward. In particular field and method access from |
|
425 JavaScript is the same as it is from Java. We highlight important |
|
426 aspects of JavaScript Java access here. |
|
427 The following examples are JavaScript snippets accessing Java. This |
|
428 section requires knowledge of JavaScript. This section can be |
|
429 skipped if you are planning to use some other JSR-223 scripting |
|
430 language rather than JavaScript.</p> |
|
431 <hr> |
|
432 <a name="jsjavaclass" id=jsjavalass"></a> |
|
433 <h3>Accessing Java Classes</h3> |
|
434 <pre> |
|
435 <code> |
|
436 // <a href="source/javatypes.js">javatypes.js</a> |
|
437 |
|
438 var arrayListType = Java.type("java.util.ArrayList") |
|
439 var intType = Java.type("int") |
|
440 var stringArrayType = Java.type("java.lang.String[]") |
|
441 var int2DArrayType = Java.type("int[][]") |
|
442 </code> |
|
443 </pre> |
|
444 |
|
445 Note that the name of the type is always a string for a fully qualified name. You can use any of these types to create new instances, e.g.: |
|
446 |
|
447 <pre><code> |
|
448 var anArrayList = new Java.type("java.util.ArrayList") |
|
449 </code></pre> |
|
450 |
|
451 or |
|
452 |
|
453 <pre><code> |
|
454 var ArrayList = Java.type("java.util.ArrayList") |
|
455 var anArrayList = new ArrayList |
|
456 var anArrayListWithSize = new ArrayList(16) |
|
457 </code></pre> |
|
458 |
|
459 In the special case of inner classes, you need to use the JVM fully qualified name, meaning using $ sign in the class name: |
|
460 |
|
461 <pre><code> |
|
462 var ftype = Java.type("java.awt.geom.Arc2D$Float") |
|
463 </code></pre> |
|
464 |
|
465 |
|
466 However, once you retrieved the outer class, you can access the inner class as a property on it: |
|
467 |
|
468 <pre><code> |
|
469 var arctype = Java.type("java.awt.geom.Arc2D") |
|
470 var ftype = arctype.Float |
|
471 </code></pre> |
|
472 <p> |
|
473 You can access both static and non-static inner classes. If you want to create an instance of a non-static inner class, remember to pass an instance of its outer class as the first argument to the constructor. |
|
474 </p> |
|
475 <hr> |
|
476 <a name="jsimport" id="jsimport"></a> |
|
477 <h3>Importing Java Packages, Classes</h3> |
|
478 <p>The built-in functions <code>importPackage</code> (in compatibility script) and |
|
479 <code>importClass</code> can be used to import Java packages and |
|
480 classes.</p> |
|
481 <pre><code> |
|
482 |
|
483 // <a href="source/importpackageclass.js">importpackageclass.js</a> |
|
484 |
|
485 // load compatibility script |
|
486 load("nashorn:mozilla_compat.js"); |
|
487 // Import Java packages and classes |
|
488 // like import package.*; in Java |
|
489 <span class="functionref">importPackage</span>(java.awt); |
|
490 // like import java.awt.Frame in Java |
|
491 <span class="functionref">importClass</span>(java.awt.Frame); |
|
492 // Create Java Objects by "new ClassName" |
|
493 var frame = new java.awt.Frame("hello"); |
|
494 // Call Java public methods from script |
|
495 frame.setVisible(true); |
|
496 // Access "JavaBean" properties like "fields" |
|
497 print(frame.title); |
|
498 </code> |
|
499 </pre> |
|
500 <p>The <span class="objectref">Packages</span> global variable can |
|
501 be used to access Java packages. Examples: |
|
502 <code>Packages.java.util.Vector</code>, |
|
503 <code>Packages.javax.swing.JFrame</code>. Please note that "java" |
|
504 is a shortcut for "Packages.java". There are equivalent shortcuts |
|
505 for javax, org, edu, com, net prefixes, so pratically all JDK |
|
506 platform classes can be accessed without the "Packages" prefix.</p> |
|
507 <p>Note that java.lang is not imported by default (unlike Java) |
|
508 because that would result in conflicts with JavaScript's built-in |
|
509 Object, Boolean, Math and so on.</p> |
|
510 <p><code>importPackage</code> and <code>importClass</code> |
|
511 functions "pollute" the global variable scope of JavaScript. To |
|
512 avoid that, you may use <span class="functionref">JavaImporter</span>.</p> |
|
513 <pre><code> |
|
514 |
|
515 // <a href="source/javaimporter.js">javaimporter.js</a> |
|
516 |
|
517 // create JavaImporter with specific packages and classes to import |
|
518 |
|
519 var SwingGui = new <span class="functionref">JavaImporter</span>(javax.swing, |
|
520 javax.swing.event, |
|
521 javax.swing.border, |
|
522 java.awt.event); |
|
523 with (SwingGui) { |
|
524 // within this 'with' statement, we can access Swing and AWT |
|
525 // classes by unqualified (simple) names. |
|
526 |
|
527 var mybutton = new JButton("test"); |
|
528 var myframe = new JFrame("test"); |
|
529 } |
|
530 |
|
531 </code> |
|
532 </pre> |
|
533 <hr> |
|
534 <a name="jsarrays" id="jsarrays"></a> |
|
535 <h3>Creating, Converting and Using Java Arrays</h3> |
|
536 <p>While creating a Java object is the same as in Java, to create |
|
537 Java arrays in JavaScript we can use Java reflection |
|
538 explicitly. But once created the element access or length access is |
|
539 the same as in Java. Also, a script array can be used when a Java |
|
540 method expects a Java array (auto conversion). So in most cases we |
|
541 don't have to create Java arrays explicitly.</p> |
|
542 <pre><code> |
|
543 // <a href="source/javaarray.js">javaarray.js</a> |
|
544 |
|
545 // create Java String array of 5 elements |
|
546 var a = java.lang.reflect.Array.newInstance(java.lang.String.class, 5); |
|
547 |
|
548 // Accessing elements and length access is by usual Java syntax |
|
549 a[0] = "scripting is great!"; |
|
550 print(a.length); |
|
551 print(a[0]); |
|
552 </code> |
|
553 </pre> |
|
554 <p> |
|
555 It is also possible to convert between JavaScript and Java arrays. |
|
556 Given a JavaScript array and a Java type, <code>Java.toJavaArray</code> returns a Java array with the same initial contents, and with the specified component type. |
|
557 </p> |
|
558 <pre><code> |
|
559 var anArray = [1, "13", false] |
|
560 var javaIntArray = Java.toJavaArray(anArray, "int") |
|
561 print(javaIntArray[0]) // prints 1 |
|
562 print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion |
|
563 print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion |
|
564 </code></pre> |
|
565 <p> |
|
566 Given a Java array or Collection, <code>Java.toJavaScriptArray</code> returns a JavaScript array with a shallow copy of its contents. Note that in most cases, you can use Java arrays and lists natively in Nashorn; in cases where for some reason you need to have an actual JavaScript native array (e.g. to work with the array comprehensions functions), you will want to use this method.i |
|
567 </p> |
|
568 <pre><code> |
|
569 var File = Java.type("java.io.File"); |
|
570 var listCurDir = new File(".").listFiles(); |
|
571 var jsList = Java.toJavaScriptArray(listCurDir); |
|
572 print(jsList); |
|
573 </code></pre> |
|
574 <hr> |
|
575 <a name="jsimplement" id="jsimplement"></a> |
|
576 <h3>Implementing Java Interfaces</h3> |
|
577 <p>A Java interface can be implemented in JavaScript by using a |
|
578 Java anonymous class-like syntax:</p> |
|
579 <pre><code> |
|
580 // <a href="source/runnable.js">runnable.js</a> |
|
581 |
|
582 var r = new java.lang.Runnable() { |
|
583 run: function() { |
|
584 print("running...\n"); |
|
585 } |
|
586 }; |
|
587 |
|
588 // "r" can be passed to Java methods that expect java.lang.Runnable |
|
589 var th = new java.lang.Thread(r); |
|
590 th.start(); |
|
591 th.join(); |
|
592 </code> |
|
593 </pre> |
|
594 <p>When an interface with a single method is expected, you can pass |
|
595 a script function directly.(auto conversion)</p> |
|
596 <pre><code> |
|
597 // <a href="source/samfunc.js">samfunc.js</a> |
|
598 |
|
599 function func() { |
|
600 print("I am func!"); |
|
601 } |
|
602 |
|
603 // pass script function for java.lang.Runnable argument |
|
604 var th = new java.lang.Thread(func); |
|
605 th.start(); |
|
606 th.join(); |
|
607 </code> |
|
608 </pre> |
|
609 <hr> |
|
610 <a name="jsextend" id="jsextend"></a> |
|
611 <h3>Extending Java classes</h3> |
|
612 <p> |
|
613 If a Java class is abstract, you can instantiate an anonymous subclass of it using an argument list that is applicable to any of its public or protected constructors, but inserting a JavaScript object with functions properties that provide JavaScript implementations of the abstract methods. If method names are overloaded, the JavaScript function will provide implementation for all overloads. E.g.: |
|
614 </p> |
|
615 |
|
616 <pre><code> |
|
617 var TimerTask = Java.type("java.util.TimerTask") |
|
618 var task = new TimerTask({ run: function() { print("Hello World!") } }) |
|
619 </code></pre> |
|
620 |
|
621 Nashorn supports a syntactic extension where a "new" expression followed by an argument is identical to invoking the constructor and passing the argument to it, so you can write the above example also as: |
|
622 |
|
623 <pre><code> |
|
624 var task = new TimerTask { |
|
625 run: function() { |
|
626 print("Hello World!") |
|
627 } |
|
628 } |
|
629 </code></pre> |
|
630 |
|
631 which is very similar to Java anonymous inner class definition. On the other hand, if the type is an abstract type with a single abstract method (commonly referred to as a "SAM type") or all abstract methods it has share the same overloaded name), then instead of an object, you can just pass a function, so the above example can become even more simplified to: |
|
632 |
|
633 <pre><code> |
|
634 var task = new TimerTask(function() { print("Hello World!") }) |
|
635 </code></pre> |
|
636 |
|
637 <p> |
|
638 Note that in every one of these cases if you are trying to instantiate an abstract class that has constructors that take some arguments, you can invoke those simply by specifying the arguments after the initial implementation object or function. |
|
639 </p> |
|
640 <p> |
|
641 The use of functions can be taken even further; if you are invoking a Java method that takes a SAM type, you can just pass in a function object, and Nashorn will know what you meant: |
|
642 </p> |
|
643 <code><pre> |
|
644 Java.type("java.util.Timer") |
|
645 timer.schedule(function() { print("Hello World!") }) |
|
646 </code></pre> |
|
647 |
|
648 Here, <code>Timer.schedule()</code> expects a <code>TimerTask</code> as its argument, so Nashorn creates an instance of a TimerTask subclass and uses the passed function to implement its only abstract method, run(). In this usage though, you can't use non-default constructors; the type must be either an interface, or must have a protected or public no-arg constructor. |
|
649 |
|
650 <p> |
|
651 To extend a concrete Java class, you have to use <code>Java.extend</code> function. |
|
652 <code>Java.extend</code> returns a type object for a subclass of the specified Java class (or implementation of the specified interface) that acts as a script-to-Java adapter for it. |
|
653 </p> |
|
654 <pre><code> |
|
655 // <a href="source/javaextend.js">javaextend.js</a> |
|
656 |
|
657 var ArrayList = Java.type("java.util.ArrayList") |
|
658 var ArrayListExtender = Java.extend(ArrayList) |
|
659 var printSizeInvokedArrayList = new ArrayListExtender() { |
|
660 size: function() { print("size invoked!"); } |
|
661 } |
|
662 var printAddInvokedArrayList = new ArrayListExtender() { |
|
663 add: function(x, y) { |
|
664 if(typeof(y) === "undefined") { |
|
665 print("add(e) invoked!"); |
|
666 } else { |
|
667 print("add(i, e) invoked!"); |
|
668 } |
|
669 } |
|
670 }; |
|
671 printSizeInvokedArrayList.size(); |
|
672 printAddInvokedArrayList.add(33, 33); |
|
673 </code></pre> |
|
674 <hr> |
|
675 <a name="jsoverload" id="jsoverload"></a> |
|
676 <h3>Overload Resolution</h3> |
|
677 <p>Java methods can be overloaded by argument types. In Java, |
|
678 overload resolution occurs at compile time (performed by javac). |
|
679 When calling Java methods from a script, the script |
|
680 interpreter/compiler needs to select the appropriate method. With |
|
681 the JavaScript engine, you do not need to do anything special - the |
|
682 correct Java method overload variant is selected based on the |
|
683 argument types. But, sometimes you may want (or have) to explicitly |
|
684 select a particular overload variant.</p> |
|
685 <pre><code> |
|
686 // <a href="source/overload.js">overload.js</a> |
|
687 |
|
688 var out = java.lang.System.out; |
|
689 |
|
690 // select a particular print function |
|
691 out["println(java.lang.Object)"]("hello"); |
|
692 </code> |
|
693 </pre> |
|
694 <hr> |
|
695 <a name="engineimpl" id="engineimpl"></a> |
|
696 <h2>Implementing Your Own Script Engine</h2> |
|
697 <p>We will not cover implementation of JSR-223 compliant script |
|
698 engines in detail. Minimally, you need to implement the |
|
699 <code>javax.script.ScriptEngine</code> and |
|
700 <code>javax.script.ScriptEngineFactory</code> interfaces. The |
|
701 abstract class <code>javax.script.AbstractScriptEngine</code> |
|
702 provides useful defaults for a few methods of the |
|
703 <code>ScriptEngine</code> interface.</p> |
|
704 <p>Before starting to implement a JSR-223 engine, you may want to |
|
705 check <a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting</a> |
|
706 project. This project maintains JSR-223 implementations for many |
|
707 popular open source scripting languages.</p> |
|
708 <hr> |
|
709 <a name="refs" id="refs"></a> |
|
710 <h2>References</h2> |
|
711 <ul> |
|
712 <li><a href="http://jcp.org/en/jsr/detail?id=223">JSR-223 Scripting |
|
713 for the Java Platform</a></li> |
|
714 <li><a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting |
|
715 </a></li> |
|
716 </ul> |
|
717 |
|
718 |
|
719 |
|
720 <div class="hr"><hr></div> |
|
721 <table summary="layout" border="0" width="100%"> |
|
722 <tbody><tr valign="TOP"> |
|
723 <td width="30%"> <img src="Java%20Scripting%20Programmer%27s%20Guide_files/logo_oracle_footer.gif" alt="Oracle and/or its affiliates" border="0" height="29" width="100"><br> |
|
724 <font size="+1"> <i>Java Technology</i></font> </td> |
|
725 |
|
726 <td width="30%"> |
|
727 <p><font size="-2"> |
|
728 <a href="http://docs.oracle.com/javase/6/docs/legal/cpyr.html">Copyright ©</a> 2013, Oracle and/or its affiliates. All rights reserved. |
|
729 </font></p> |
|
730 </td> |
|
731 <td width="30%"> |
|
732 <p align="right"><font size="-2"><a href="http://download.oracle.com/javase/feedback.html">Contact Us</a></font></p><font size="-2"> |
|
733 </font></td> |
|
734 </tr> |
|
735 </tbody></table> |
|
736 <div class="hr"><hr></div> |
|
737 </div> |
|
738 |
|
739 <!-- Start SiteCatalyst code --> |
|
740 <script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code_download.js"></script> |
|
741 <script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code.js"></script> |
|
742 |
|
743 <!-- ********** DO NOT ALTER ANYTHING BELOW THIS LINE ! *********** --> |
|
744 <!-- Below code will send the info to Omniture server --> |
|
745 <script language="javascript">var s_code=s.t();if(s_code)document.write(s_code)</script> |
|
746 |
|
747 <!-- End SiteCatalyst code --> |
|
748 |
|
749 |
|
750 |
|
751 </body></html> |