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