jdk-sandbox: nashorn/docs/JavaScriptingProgrammersGuide.html@f326fa317a81 (annotated)

16784 ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	1	<!--
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	2	Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	3	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	4
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	5	This code is free software; you can redistribute it and/or modify it
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	6	under the terms of the GNU General Public License version 2 only, as
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	7	published by the Free Software Foundation. Oracle designates this
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	8	particular file as subject to the "Classpath" exception as provided
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	9	by Oracle in the LICENSE file that accompanied this code.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	10
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	11	This code is distributed in the hope that it will be useful, but WITHOUT
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	12	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	13	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	14	version 2 for more details (a copy is included in the LICENSE file that
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	15	accompanied this code).
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	16
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	17	You should have received a copy of the GNU General Public License version
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	18	2 along with this work; if not, write to the Free Software Foundation,
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	19	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	20
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	21	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	22	or visit www.oracle.com if you need additional information or have any
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	23	questions.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	24	-->
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	25	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	26	<html class=" regenabled gecko radius jsenabled regloaded" xmlns="http://www.w3.org/1999/xhtml"><head>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	27	<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	28	<title>Java Scripting Programmer's Guide</title>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	29
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	30	<!-- ============ -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	31	<!-- MAIN CONTENT -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	32	<!-- ============ -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	33	<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	34	<tbody><tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	35	<td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	36
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	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>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	38
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	39	</td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	40	</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	41	</tbody></table>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	42	<!-- Body text begins here -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	43	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	44	<li><span><a href="#who">Who is the Java Scripting API
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	45	For?</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	46	<li><span><a href="#package">Scripting Package</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	47	<li><span><a href="#examples">Examples</a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	48	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	49	<li><span><a href="#helloworld">"Hello, World"</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	50	<li><span><a href="#evalfile">Evaluating a Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	51	File</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	52	<li><span><a href="#scriptvars">Script Variables</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	53	<li><span><a href="#invoke">Invoking Script Functions and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	54	Methods</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	55	<li><span><a href="#interfaces">Implementing Java Interfaces by
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	56	Scripts</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	57	<li><span><a href="#scopes">Multiple Scopes for
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	58	Scripts</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	59	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	60	</li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	61	<li><span><a href="#jsengine">JavaScript Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	62	Engine</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	63	<li><span><a href="#jstojava">JavaScript to Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	64	Communication</a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	65	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	66	<li><span><a href="#jsjavaclass">Accessing Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	67	Classes</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	68	<li><span><a href="#jsimport">Importing Java Packages,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	69	Classes</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	70	<li><span><a href="#jsarrays">Creating, Converting and Using Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	71	Arrays</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	72	<li><span><a href="#jsimplement">Implementing Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	73	Interfaces</a></span></li>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	74	<li><span><a href="#jsextendabstract">Extending Abstract Java Classes
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	75	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	76	<li><span><a href="#jsextendconcrete">Extending Concrete Java Classes
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	77	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	78	<li><span><a href="#jsimplementmultiple">Implementing Multiple Java Interfaces
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	79	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	80	<li><span><a href="#classBoundImplementations">Class-Bound Implementations
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	81	</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	82	<li><span><a href="#jsoverload">Overload Resolution</a></span></li>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	83	<li><span><a href="#dataTypeMapping">Mapping of Data Types Between Java
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	84	and JavaScript</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	85
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	86
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	87
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	88	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	89	</li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	90	<li><span><a href="#engineimpl">Implementing Your Own Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	91	Engine</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	92	<li><span><a href="#refs">References</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	93	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	94	<span><a name="who" id="who"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	95	<h2><span>Who is the Java Scripting API For?</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	96	<span>Some useful characteristics of scripting languages
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	97	are:</span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	98	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	99	<li><span><b>Convenience</b>: Most scripting languages are
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	100	dynamically typed. You can usually create new variables without
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	101	declaring the variable type, and you can reuse variables to store
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	102	objects of different types. Also, scripting languages tend to
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	103	perform many type conversions automatically, for example,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	104	converting the number 10 to the text "10" as necessary.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	105	<li><span><b>Developing rapid prototypes</b>: You can avoid the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	106	edit-compile-run cycle and just use edit-run!</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	107	<li><span><b>Application extension/customization</b>: You can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	108	"externalize" parts of your application - like configuration
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	109	scripts, business logic/rules and math expressions for financial
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	110	applications.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	111	<li><span><b>"Command line" shells for applications</b> -for
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	112	debugging, runtime/deploy time configuration etc. Most applications
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	113	have a web-based GUI configuaration tool these days. But
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	114	sysadmins/deployers frequently prefer command line tools. Instead
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	115	of inventing ad-hoc scripting language for that purpose, a
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	116	"standard" scripting language can be used.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	117	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	118	<p><span>The Java<font size="-1"><sup>TM</sup></font> Scripting API
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	119	is a scripting language indepedent framework for using script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	120	engines from Java code. With the Java Scripting API, it is possible
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	121	to write customizable/extendable applications in the Java language
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	122	and leave the customization scripting language choice to the end
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	123	user. The Java application developer need not choose the extension
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	124	language during development. If you write your application with
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	125	JSR-223 API, then your users can use any JSR-223 compliant
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	126	scripting language.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	127	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	128	<span><a name="package" id="package"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	129	<h2><span>Scripting Package</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	130	<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>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	131	package. This is a relatively small, simple API. The starting point
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	132	of the scripting API is the <code>ScriptEngineManager</code> class.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	133	A ScriptEngineManager object can discover script engines through
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	134	the jar file service discovery mechanism. It can also instantiate
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	135	ScriptEngine objects that interpret scripts written in a specific
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	136	scripting language. The simplest way to use the scripting API is as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	137	follows:</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	138	<ol>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	139	<li><span>Create a <code>ScriptEngineManager</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	140	object.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	141	<li><span>Get a <code>ScriptEngine</code> object from the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	142	manager.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	143	<li><span>Evaluate script using the <code>ScriptEngine</code>'s
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	144	<code>eval</code> methods.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	145	</ol>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	146	<p><span>Now, it is time to look at some sample code. While it is
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	147	not mandatory, it may be useful to know a bit of JavaScript to read
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	148	these examples.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	149	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	150	<span><a name="examples" id="examples"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	151	<h2><span>Examples</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	152	<span><a name="helloworld" id="helloworld"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	153	<h3><span>"Hello, World"</span></h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	154	<p><span>From the <code>ScriptEngineManager</code> instance, we
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	155	request a JavaScript engine instance using
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	156	<code>getEngineByName</code> method. On the script engine, the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	157	<code>eval</code> method is called to execute a given String as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	158	JavaScript code! For brevity, in this as well as in subsequent
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	159	examples, we have not shown exception handling. There are checked
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	160	and runtime exceptions thrown from <code>javax.script</code> API.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	161	Needless to say, you have to handle the exceptions
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	162	appropriately.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	163	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	164	<span><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	165	// <a href="source/EvalScript.java">EvalScript.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	166
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	167	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	168	public class EvalScript {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	169	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	170	// create a script engine manager
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	171	<span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	172	// create a JavaScript engine
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	173	<span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	174	// evaluate JavaScript code from String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	175	engine.<span class="methodref">eval</span>("print('Hello, World')");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	176	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	177	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	178	</code></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	179	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	180	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	181	<a name="evalfile" id="evalfile"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	182	<h3>Evaluating a Script File</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	183	<p>In this example, we call the <code>eval</code> method that
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	184	accepts <code>java.io.Reader</code> for the input source. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	185	script read by the given reader is executed. This way it is
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	186	possible to execute scripts from files, URLs and resources by
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	187	wrapping the relevant input stream objects as readers.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	188	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	189	<code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	190	// <a href="source/EvalFile.java">EvalFile.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	191
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	192	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	193
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	194	public class EvalFile {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	195	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	196	// create a script engine manager
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	197	<span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	198	// create JavaScript engine
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	199	<span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	200	// evaluate JavaScript code from given file - specified by first argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	201	engine.<span class="methodref">eval</span>(new java.io.FileReader(args[0]));
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	202	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	203	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	204	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	205	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	206	Let us assume that we have the file named <a href="source/test.js">test.js</a> with the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	207	following text:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	208	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	209	print("This is hello from test.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	210	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	211	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	212	We can run the above Java as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	213	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	214	java EvalFile test.js
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	215	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	216	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	217	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	218	<a name="scriptvars" id="scriptvars"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	219	<h3>Script Variables</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	220	<p>When you embed script engines and scripts with your Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	221	application, you may want to expose your application objects as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	222	global variables to scripts. This example demonstrates how you can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	223	expose your application objects as global variables to a script. We
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	224	create a <code>java.io.File</code> in the application and expose
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	225	the same as a global variable with the name "file". The script can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	226	access the variable - for example, it can call public methods on
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	227	it. Note that the syntax to access Java objects, methods and fields
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	228	is dependent on the scripting language. JavaScript supports the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	229	most "natural" Java-like syntax.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	230	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	231	// <a href="source/ScriptVars.java">ScriptVars.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	232
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	233	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	234	import java.io.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	235
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	236	public class ScriptVars {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	237	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	238	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	239	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	240
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	241	File f = new File("test.txt");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	242	// expose File object as variable to script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	243	engine.<span class="methodref">put</span>("file", f);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	244
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	245	// evaluate a script string. The script accesses "file"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	246	// variable and calls method on it
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	247	engine.eval("print(file.getAbsolutePath())");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	248	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	249	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	250
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	251	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	252	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	253	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	254	<a name="invoke" id="invoke"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	255	<h3>Invoking Script Functions and Methods</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	256	<p>Sometimes you may want to call a specific scripting function
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	257	repeatedly - for example, your application menu functionality might
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	258	be implemented by a script. In your menu's action event handler you
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	259	may want to call a specific script function. The following example
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	260	demonstrates invoking a specific script function from Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	261	code.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	262	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	263	// <a href="source/InvokeScriptFunction.java">InvokeScriptFunction.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	264
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	265	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	266
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	267	public class InvokeScriptFunction {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	268	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	269	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	270	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	271
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	272	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	273	String script = "function hello(name) { print('Hello, ' + name); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	274	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	275	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	276
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	277	// <code>javax.script.Invocable</code> is an optional interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	278	// Check whether your script engine implements it or not!
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	279	// Note that the JavaScript engine implements Invocable interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	280	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	281
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	282	// invoke the global function named "hello"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	283	inv.<span class="methodref">invokeFunction</span>("hello", "Scripting!!" );
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	284	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	285	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	286
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	287	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	288	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	289	<p>If your scripting language is object based (like JavaScript) or
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	290	object-oriented, then you can invoke a script method on a script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	291	object.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	292	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	293	// <a href="source/InvokeScriptMethod.java">InvokeScriptMethod.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	294
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	295	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	296
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	297	public class InvokeScriptMethod {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	298	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	299	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	300	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	301
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	302	// JavaScript code in a String. This code defines a script object 'obj'
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	303	// with one method called 'hello'.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	304	String script = "var obj = new Object(); obj.hello = function(name) { print('Hello, ' + name); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	305	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	306	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	307
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	308	// <code>javax.script.Invocable</code> is an optional interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	309	// Check whether your script engine implements or not!
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	310	// Note that the JavaScript engine implements Invocable interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	311	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	312
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	313	// get script object on which we want to call the method
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	314	Object obj = engine.<span class="methodref">get</span>("obj");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	315
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	316	// invoke the method named "hello" on the script object "obj"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	317	inv.<span class="methodref">invokeMethod</span>(obj, "hello", "Script Method !!" );
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	318	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	319	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	320
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	321	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	322	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	323	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	324	<a name="interfaces" id="interfaces"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	325	<h3>Implementing Java Interfaces by Scripts</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	326	<p>Instead of calling specific script functions from Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	327	sometimes it is convenient to implement a Java interface by script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	328	functions or methods. Also, by using interfaces we can avoid having
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	329	to use the <code>javax.script</code> API in many places. We can get
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	330	an interface implementor object and pass it to various Java APIs.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	331	The following example demonstrates implementing the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	332	<code>java.lang.Runnable</code> interface with a script.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	333	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	334	// <a href="source/RunnableImpl.java">RunnableImpl.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	335
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	336	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	337
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	338	public class RunnableImpl {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	339	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	340	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	341	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	342
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	343	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	344	String script = "function run() { print('run called'); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	345
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	346	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	347	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	348
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	349	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	350
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	351	// get Runnable interface object from engine. This interface methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	352	// are implemented by script functions with the matching name.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	353	Runnable r = inv.<span class="methodref">getInterface</span>(Runnable.class);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	354
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	355	// start a new thread that runs the script implemented
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	356	// runnable interface
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	357	Thread th = new Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	358	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	359	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	360	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	361	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	362	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	363	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	364	<p>If your scripting language is object-based or object-oriented,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	365	it is possible to implement a Java interface by script methods on
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	366	script objects. This avoids having to call script global functions
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	367	for interface methods. The script object can store the "state"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	368	associated with the interface implementor.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	369	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	370	// <a href="source/RunnableImplObject.java">RunnableImplObject.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	371
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	372	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	373
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	374	public class RunnableImplObject {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	375	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	376	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	377	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	378
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	379	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	380	String script = "var obj = new Object(); obj.run = function() { print('run method called'); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	381
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	382	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	383	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	384
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	385	// get script object on which we want to implement the interface with
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	386	Object obj = engine.<span class="methodref">get</span>("obj");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	387
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	388	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	389
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	390	// get Runnable interface object from engine. This interface methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	391	// are implemented by script methods of object 'obj'
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	392	Runnable r = inv.<span class="methodref">getInterface</span>(obj, Runnable.class);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	393
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	394	// start a new thread that runs the script implemented
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	395	// runnable interface
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	396	Thread th = new Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	397	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	398	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	399	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	400	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	401	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	402	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	403	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	404	<a name="scopes" id="scopes"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	405	<h3>Multiple Scopes for Scripts</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	406	<p>In the <a href="#scriptvars">script variables</a> example, we
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	407	saw how to expose application objects as script global variables.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	408	It is possible to expose multiple global "scopes" for scripts. A
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	409	single scope is an instance of <code>javax.script.Bindings</code>.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	410	This interface is derived from <code>java.util.Map<String,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	411	Object></code>. A scope a set of name-value pairs where name is
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	412	any non-empty, non-null String.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	413	<code>javax.script.ScriptContext</code> interface supports multiple
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	414	scopes with associated Bindings for each
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	415	scope. By default, every script engine has a default script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	416	context. The default script context has atleast one scope called
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	417	"ENGINE_SCOPE". Various scopes supported by a script context are
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	418	available through <code>getScopes</code> method.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	419	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	420	// <a href="source/MultiScopes.java">MultiScopes.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	421
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	422	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	423
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	424	public class MultiScopes {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	425	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	426	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	427	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	428
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	429	engine.put("x", "hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	430	// print global variable "x"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	431	engine.eval("print(x);");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	432	// the above line prints "hello"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	433
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	434	// Now, pass a different script context
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	435	<span class="classref">ScriptContext</span> newContext = new <span class="classref">SimpleScriptContext</span>();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	436	newContext.setBindings(engine.createBindings(), ScriptContext.ENGINE_SCOPE);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	437	<span class="classref">Bindings</span> engineScope = newContext.<span class="methodref">getBindings</span>(ScriptContext.ENGINE_SCOPE);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	438
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	439	// add new variable "x" to the new engineScope
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	440	engineScope.<span class="methodref">put</span>("x", "world");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	441
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	442	// execute the same script - but this time pass a different script context
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	443	engine.eval("print(x);", newContext);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	444	// the above line prints "world"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	445	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	446	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	447
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	448	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	449	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	450	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	451	<a name="jsengine" id="jsengine"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	452	<h2>JavaScript Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	453	<p>Oracle's implementation of JDK 8 is co-bundled with the Nashorn ECMAScript
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	454	script engine.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	455	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	456	<a name="jstojava" id="jstojava"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	457	<h2>JavaScript to Java Communication</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	458	<p>For the most part, accessing Java classes, objects and methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	459	is straightforward. In particular field and method access from
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	460	JavaScript is the same as it is from Java. We highlight important
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	461	aspects of JavaScript Java access here.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	462	The following examples are JavaScript snippets accessing Java. This
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	463	section requires knowledge of JavaScript. This section can be
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	464	skipped if you are planning to use some other JSR-223 scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	465	language rather than JavaScript.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	466	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	467	<a name="jsjavaclass" id=jsjavalass"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	468	<h3>Accessing Java Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	469	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	470	<code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	471	// <a href="source/javatypes.js">javatypes.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	472
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	473	var arrayListType = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	474	var intType = Java.type("int")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	475	var stringArrayType = Java.type("java.lang.String[]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	476	var int2DArrayType = Java.type("int[][]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	477	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	478	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	479
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	480	Note that the name of the type is always a string for a fully qualified name. You can use any of these expressions to create new instances, e.g.:
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	481
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	482	<pre><code>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	483	var anArrayList = new (Java.type("java.util.ArrayList"))
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	484	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	485
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	486	or
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	487
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	488	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	489	var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	490	var anArrayList = new ArrayList
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	491	var anArrayListWithSize = new ArrayList(16)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	492	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	493
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	494	In the special case of inner classes, you need to use the JVM fully qualified name, meaning using $ sign in the class name:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	495
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	496	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	497	var ftype = Java.type("java.awt.geom.Arc2D$Float")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	498	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	499
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	500
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	501	However, once you retrieved the outer class, you can access the inner class as a property on it:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	502
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	503	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	504	var arctype = Java.type("java.awt.geom.Arc2D")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	505	var ftype = arctype.Float
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	506	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	507	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	508	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.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	509	</p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	510	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	511	In addition to creating new instances, the type objects returned from <code>Java.type</code> calls can also be used to access the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	512	static fields and methods of the classes:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	513	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	514	var File = Java.type("java.io.File")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	515	File.createTempFile("nashorn", ".tmp")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	516	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	517	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	518	Methods with names of the form <code>isXxx()</code>, <code>getXxx()</code>, and <code>setXxx()</code> can also be used as properties, for both instances and statics.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	519	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	520	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	521	A type object returned from <code>Java.type</code> is distinct from a <code>java.lang.Class</code> object. You can obtain one from the other using properties <code>class</code> and <code>static</code> on them.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	522	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	523	var ArrayList = Java.type("java.util.ArrayList")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	524	var a = new ArrayList
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	525
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	526	// All of the following print true:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	527	print("Type acts as target of instanceof: " + (a instanceof ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	528	print("Class doesn't act as target of instanceof: " + !(a instanceof a.getClass()))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	529	print("Type is not same as instance's getClass(): " + (a.getClass() !== ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	530	print("Type's `class` property is same as instance getClass(): " + (a.getClass() === ArrayList.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	531	print("Type is same as instance getClass()'s `static` property: " + (a.getClass().static === ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	532	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	533	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	534	You can think of the type object as similar to the class names as used in Java source code: you use them as the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	535	arguments to the <code>new</code> and <code>instanceof</code> operators and as the namespace for the static fields
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	536	and methods, but they are different than the runtime <code>Class</code> objects returned by <code>getClass()</code> calls.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	537	Syntactically and semantically, this separation produces code that is most similar to Java code, where a distinction
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	538	between compile-time class expressions and runtime class objects also exists. (Also, Java can't have the equivalent of <code>static</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	539	property on a <code>Class</code> object since compile-time class expressions are never reified as objects).
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	540	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	541	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	542	<a name="jsimport" id="jsimport"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	543	<h3>Importing Java Packages, Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	544	<p>The built-in functions <code>importPackage</code> (in compatibility script) and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	545	<code>importClass</code> can be used to import Java packages and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	546	classes.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	547	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	548
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	549	// <a href="source/importpackageclass.js">importpackageclass.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	550
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	551	// load compatibility script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	552	load("nashorn:mozilla_compat.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	553	// Import Java packages and classes
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	554	// like import package.*; in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	555	<span class="functionref">importPackage</span>(java.awt);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	556	// like import java.awt.Frame in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	557	<span class="functionref">importClass</span>(java.awt.Frame);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	558	// Create Java Objects by "new ClassName"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	559	var frame = new java.awt.Frame("hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	560	// Call Java public methods from script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	561	frame.setVisible(true);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	562	// Access "JavaBean" properties like "fields"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	563	print(frame.title);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	564	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	565	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	566	<p>The <span class="objectref">Packages</span> global variable can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	567	be used to access Java packages. Examples:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	568	<code>Packages.java.util.Vector</code>,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	569	<code>Packages.javax.swing.JFrame</code>. Please note that "java"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	570	is a shortcut for "Packages.java". There are equivalent shortcuts
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	571	for javax, org, edu, com, net prefixes, so pratically all JDK
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	572	platform classes can be accessed without the "Packages" prefix.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	573	<p>Note that java.lang is not imported by default (unlike Java)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	574	because that would result in conflicts with JavaScript's built-in
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	575	Object, Boolean, Math and so on.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	576	<p><code>importPackage</code> and <code>importClass</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	577	functions "pollute" the global variable scope of JavaScript. To
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	578	avoid that, you may use <span class="functionref">JavaImporter</span>.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	579	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	580
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	581	// <a href="source/javaimporter.js">javaimporter.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	582
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	583	// create JavaImporter with specific packages and classes to import
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	584
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	585	var SwingGui = new <span class="functionref">JavaImporter</span>(javax.swing,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	586	javax.swing.event,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	587	javax.swing.border,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	588	java.awt.event);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	589	with (SwingGui) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	590	// within this 'with' statement, we can access Swing and AWT
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	591	// classes by unqualified (simple) names.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	592
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	593	var mybutton = new JButton("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	594	var myframe = new JFrame("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	595	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	596
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	597	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	598	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	599	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	600	<a name="jsarrays" id="jsarrays"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	601	<h3>Creating, Converting and Using Java Arrays</h3>
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	602	<p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	603	Array element access or length access is the same as in Java.</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	604	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	605	// <a href="source/javaarray.js">javaarray.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	606
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	607	// create Java String array of 5 elements
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	608	var StringArray = Java.type("java.lang.String[]");
d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	609	var a = new StringArray(5);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	610
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	611	// Accessing elements and length access is by usual Java syntax
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	612	a[0] = "scripting is great!";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	613	print(a.length);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	614	print(a[0]);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	615	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	616	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	617	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	618	It is also possible to convert between JavaScript and Java arrays.
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	619	Given a JavaScript array and a Java type, <code>Java.to</code> returns a Java array with the same initial contents, and with the specified array type.
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	620	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	621	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	622	var anArray = [1, "13", false]
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	623	var javaIntArray = Java.to(anArray, "int[]")
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	624	print(javaIntArray[0]) // prints 1
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	625	print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	626	print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	627	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	628	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	629	You can use either a string or a type object returned from <code>Java.type()</code> to specify the type of the array.
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	630	You can also omit the array type, in which case a <code>Object[]</code> will be created.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	631	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	632	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	633	Given a Java array or Collection, <code>Java.from</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.
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	634	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	635	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	636	var File = Java.type("java.io.File");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	637	var listCurDir = new File(".").listFiles();
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	638	var jsList = Java.from(listCurDir);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	639	print(jsList);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	640	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	641	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	642	<a name="jsimplement" id="jsimplement"></a>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	643	<h3>Implementing Java interfaces</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	644	<p>A Java interface can be implemented in JavaScript by using a
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	645	Java anonymous class-like syntax:</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	646	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	647	// <a href="source/runnable.js">runnable.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	648
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	649	var r = new java.lang.Runnable() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	650	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	651	print("running...\n");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	652	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	653	};
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	654
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	655	// "r" can be passed to Java methods that expect java.lang.Runnable
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	656	var th = new java.lang.Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	657	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	658	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	659	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	660	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	661	<p>When an interface with a single method is expected, you can pass
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	662	a script function directly.(auto conversion)</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	663	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	664	// <a href="source/samfunc.js">samfunc.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	665
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	666	function func() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	667	print("I am func!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	668	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	669
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	670	// pass script function for java.lang.Runnable argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	671	var th = new java.lang.Thread(func);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	672	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	673	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	674	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	675	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	676	<hr>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	677	<a name="jsextendabstract" id="jsextendabstract"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	678	<h3>Extending Abstract Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	679	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	680	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.:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	681	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	682
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	683	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	684	var TimerTask = Java.type("java.util.TimerTask")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	685	var task = new TimerTask({ run: function() { print("Hello World!") } })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	686	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	687
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	688	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:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	689
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	690	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	691	var task = new TimerTask {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	692	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	693	print("Hello World!")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	694	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	695	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	696	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	697
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	698	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:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	699
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	700	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	701	var task = new TimerTask(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	702	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	703
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	704	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	705	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.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	706	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	707	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	708	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:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	709	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	710	<code><pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	711	Java.type("java.util.Timer")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	712	timer.schedule(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	713	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	714
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	715	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.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	716
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	717	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	718	<a name="jsextendconcrete" id="jsextendconcrete"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	719	<h3>Extending Concrete Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	720	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	721	To extend a concrete Java class, you have to use <code>Java.extend</code> function.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	722	<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.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	723	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	724	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	725	// <a href="source/javaextend.js">javaextend.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	726
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	727	var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	728	var ArrayListExtender = Java.extend(ArrayList)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	729	var printSizeInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	730	size: function() { print("size invoked!"); }
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	731	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	732	var printAddInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	733	add: function(x, y) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	734	if(typeof(y) === "undefined") {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	735	print("add(e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	736	} else {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	737	print("add(i, e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	738	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	739	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	740	};
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	741	printSizeInvokedArrayList.size();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	742	printAddInvokedArrayList.add(33, 33);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	743	</code></pre>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	744	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	745	The reason you must use <code>Java.extend()</code> with concrete classes is that with concrete classes, there can be a
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	746	syntactic ambiguity if you just invoke their constructor. Consider this example:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	747	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	748	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	749	var t = new java.lang.Thread({ run: function() { print("Hello!") } })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	750	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	751	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	752	If we allowed subclassing of concrete classes with constructor syntax, Nashorn couldn't tell if you're creating a new
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	753	<code>Thread</code> and passing it a <code>Runnable</code> at this point, or you are subclassing <code>Thread</code> and
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	754	passing it a new implementation for its own <code>run()</code> method.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	755	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	756	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	757	<a name="jsimplementmultiple" id="jsimplementmultiple"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	758	<h3>Implementing Multiple Interfaces</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	759	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	760	<code>Java.extend</code> can in fact take a list of multiple types. At most one of the types can be a class, and the rest must
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	761	be interfaces (the class doesn't have to be the first in the list). You will get back an object that extends the class and
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	762	implements all the interfaces. (Obviously, if you only specify interfaces and no class, the object will extend <code>java.lang.Object</code>).
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	763	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	764	<a name="classBoundImplementations" id="classBoundImplementations"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	765	<h3>Class-Bound Implementations</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	766	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	767	The methods shown so far for extending Java classes and implementing interfaces – passing an implementation JavaScript object
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	768	or function to a constructor, or using <code>Java.extend</code> with <code>new</code> – all produce classes that take an
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	769	extra JavaScript object parameter in their constructors that specifies the implementation. The implementation is therefore always bound
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	770	to the actual instance being created with <code>new</code>, and not to the whole class. This has some advantages, for example in the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	771	memory footprint of the runtime, as Nashorn can just create a single "universal adapter" for every combination of types being implemented.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	772	In reality, the below code shows that different instantiations of, say, <code>Runnable</code> have the same class regardless of them having
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	773	different JavaScript implementation objects:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	774	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	775	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	776	var Runnable = java.lang.Runnable;
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	777	var r1 = new Runnable(function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	778	var r2 = new Runnable(function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	779	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	780	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	781	print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	782	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	783	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	784	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	785	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	786	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	787	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	788	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	789	We share the same class: true
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	790	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	791	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	792	Sometimes, however, you'll want to extend a Java class or implement an interface with implementation bound to the class, not to
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	793	its instances. Such a need arises, for example, when you need to pass the class for instantiation to an external API; prime example
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	794	of this is the JavaFX framework where you need to pass an Application class to the FX API and let it instantiate it.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	795	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	796	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	797	Fortunately, there's a solution for that: <code>Java.extend()</code> – aside from being able to take any number of type parameters
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	798	denoting a class to extend and interfaces to implement – can also take one last argument that has to be a JavaScript object
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	799	that serves as the implementation for the methods. In this case, <code>Java.extend()</code> will create a class that has the same
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	800	constructors as the original class had, as they don't need to take an an extra implementation object parameter. The example below
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	801	shows how you can create class-bound implementations, and shows that in this case, the implementation classes for different invocations
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	802	are indeed different:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	803	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	804	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	805	var RunnableImpl1 = Java.extend(java.lang.Runnable, function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	806	var RunnableImpl2 = Java.extend(java.lang.Runnable, function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	807	var r1 = new RunnableImpl1()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	808	var r2 = new RunnableImpl2()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	809	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	810	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	811	print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	812	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	813	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	814	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	815	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	816	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	817	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	818	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	819	We share the same class: false
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	820	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	821	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	822	As you can see, the major difference here is that we moved the implementation object into the invocation of <code>Java.extend</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	823	from the constructor invocations – indeed the constructor invocations now don't even need to take an extra parameter! Since
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	824	the implementations are bound to a class, the two classes obviously can't be the same, and we indeed see that the two runnables no
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	825	longer share the same class – every invocation of <code>Java.extend()</code> with a class-specific implementation object triggers
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	826	the creation of a new Java adapter class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	827	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	828	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	829	Finally, the adapter classes with class-bound implementations can <i>still</i> take an additional constructor parameter to further
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	830	override the behavior on a per-instance basis. Thus, you can even combine the two approaches: you can provide part of the implementation
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	831	in a class-based JavaScript implementation object passed to <code>Java.extend</code>, and part in another object passed to the constructor.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	832	Whatever functions are provided by the constructor-passed object will override the functions in the class-bound object.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	833	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	834	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	835	var RunnableImpl = Java.extend(java.lang.Runnable, function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	836	var r1 = new RunnableImpl()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	837	var r2 = new RunnableImpl(function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	838	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	839	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	840	print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	841	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	842	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	843	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	844	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	845	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	846	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	847	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	848	We share the same class: true
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	849	</code></pre>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	850	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	851	<a name="jsoverload" id="jsoverload"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	852	<h3>Overload Resolution</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	853	<p>Java methods can be overloaded by argument types. In Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	854	overload resolution occurs at compile time (performed by javac).
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	855	When calling Java methods from Nashorn, the appropriate method will be
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	856	selected based on the argument types at invocation time. You do not need
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	857	to do anything special – the correct Java method overload variant
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	858	is selected based automatically. You still have the option of explicitly
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	859	specifying a particular overload variant. Reasons for this include
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	860	either running into a genuine ambiguity with actual argument types, or
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	861	rarely reasons of performance – if you specify the actual overload
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	862	then the engine doesn't have to perform resolution during invocation.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	863	Individual overloads of a Java methods are exposed as special properties
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	864	with the name of the method followed with its signature in parentheses.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	865	You can invoke them like this:</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	866	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	867	// <a href="source/overload.js">overload.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	868
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	869	var out = java.lang.System.out;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	870
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	871	// select a particular print function
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	872	out["println(Object)"]("hello");
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	873	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	874	</pre>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	875	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	876	Note that you normally don't even have to use qualified class names in
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	877	the signatures as long as the unqualified name of the type is sufficient
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	878	for uniquely identifying the signature. In practice this means that only
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	879	in the extremely unlikely case that two overloads only differ in
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	880	parameter types that have identical unqualified names but come from
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	881	different packages would you need to use the fully qualified name of the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	882	class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	883	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	884	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	885	<a name="dataTypeMapping" id="dataTypeMapping"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	886	<h3>Mapping of Data Types Between Java and JavaScript</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	887	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	888	We have previously shown some of the data type mappings between Java and JavaScript.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	889	We saw that arrays need to be explicitly converted. We have also shown that JavaScript functions
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	890	are automatically converted to SAM types when passed as parameters to Java methods. Most other
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	891	conversions work as you would expect.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	892	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	893	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	894	Every JavaScript object is also a <code>java.util.Map</code> so APIs receiving maps will receive them directly.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	895	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	896	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	897	When numbers are passed to a Java API, they will be converted to the expected target numeric type, either boxed or
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	898	primitive, but if the target type is less specific, say <code>Number</code> or <code>Object</code>, you can only
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	899	count on them being a <code>Number</code>, and have to test specifically for whether it's a boxed <code>Double</code>,
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	900	<code>Integer</code>, <code>Long</code>, etc. – it can be any of these due to internal optimizations. Also, you
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	901	can pass any JavaScript value to a Java API expecting either a boxed or primitive number; the JavaScript specification's
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	902	<code>ToNumber</code> conversion algorithm will be applied to the value.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	903	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	904	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	905	In a similar vein, if a Java method expects a <code>String</code> or a <code>Boolean</code>, the values will be
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	906	converted using all conversions allowed by the JavaScript specification's <code>ToString</code> and <code>ToBoolean</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	907	conversions.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	908	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	909	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	910	Finally, a word of caution about strings. Due to internal performance optimizations of string operations, JavaScript strings are
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	911	not always necessarily of type <code>java.lang.String</code>, but they will always be of type <code>java.lang.CharSequence</code>.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	912	If you pass them to a Java method that expects a <code>java.lang.String</code> parameter, then you will naturally receive a Java
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	913	String, but if the signature of your method is more generic, i.e. it receives a <code>java.lang.Object</code> parameter, you can
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	914	end up with an object of private engine implementation class that implements <code>CharSequence</code> but is not a Java String.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	915	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	916	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	917	<a name="engineimpl" id="engineimpl"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	918	<h2>Implementing Your Own Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	919	<p>We will not cover implementation of JSR-223 compliant script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	920	engines in detail. Minimally, you need to implement the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	921	<code>javax.script.ScriptEngine</code> and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	922	<code>javax.script.ScriptEngineFactory</code> interfaces. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	923	abstract class <code>javax.script.AbstractScriptEngine</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	924	provides useful defaults for a few methods of the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	925	<code>ScriptEngine</code> interface.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	926	<p>Before starting to implement a JSR-223 engine, you may want to
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	927	check <a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	928	project. This project maintains JSR-223 implementations for many
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	929	popular open source scripting languages.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	930	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	931	<a name="refs" id="refs"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	932	<h2>References</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	933	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	934	<li><a href="http://jcp.org/en/jsr/detail?id=223">JSR-223 Scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	935	for the Java Platform</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	936	<li><a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	937	</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	938	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	939
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	940
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	941
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	942	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	943	<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	944	<tbody><tr valign="TOP">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	945	<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>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	946	<font size="+1"> <i>Java Technology</i></font> </td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	947
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	948	<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	949	<p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	950	<a href="http://docs.oracle.com/javase/6/docs/legal/cpyr.html">Copyright �</a> 2013, Oracle and/or its affiliates. All rights reserved.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	951	</font></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	952	</td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	953	<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	954	<p align="right"><font size="-2"><a href="http://download.oracle.com/javase/feedback.html">Contact Us</a></font></p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	955	</font></td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	956	</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	957	</tbody></table>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	958	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	959	</div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	960
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	961	<!-- Start SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	962	<script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code_download.js"></script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	963	<script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code.js"></script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	964
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	965	<!-- ******** DO NOT ALTER ANYTHING BELOW THIS LINE ! ********* -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	966	<!-- Below code will send the info to Omniture server -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	967	<script language="javascript">var s_code=s.t();if(s_code)document.write(s_code)</script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	968
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	969	<!-- End SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	970
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	971
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	972
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	973	</body></html>

author	erikj
	Tue, 25 Jun 2013 09:37:46 +0200
changeset 18052	f326fa317a81
parent 17758	2b056941e4dd
child 18615	3f6e6adcbc1a
permissions	-rw-r--r--