jdk-sandbox: doc/nashorn/JavaScriptingProgrammersGuide.html@1251d78fafbf (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>
47290 2853531b2c8c 8180274: Fix links in nashorn documentation sundar parents: 47216 diff changeset	130	<p><span>The Java Scripting functionality is in the <code><a href="http://docs.oracle.com/javase/9/docs/api/javax/script/package-summary.html">javax.script</a></code>
16212 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>
18615 3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	230	<p>
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	231	Nashorn script engine pre-defines two global variables named "context"
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	232	and "engine". The "context" variable is of type javax.script.ScriptContext
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	233	and refers to the current ScriptContext instance passed to script engine's
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	234	eval method. The "engine" variable is of type javax.script.ScriptEngine and
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	235	refers to the current nashorn script engine instance evaluating the script.
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	236	Both of these variables are non-writable, non-enumerable and non-configurable
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	237	- which implies script code can not write overwrite the value, for..loop iteration
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	238	on global object will not iterate these variables and these variables can not be
3f6e6adcbc1a 8015969: Needs to enforce and document that global "context" and "engine" can't be modified when running via jsr223 sundar parents: 17758 diff changeset	239	deleted by script.
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	240	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	241	// <a href="source/ScriptVars.java">ScriptVars.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	242
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	243	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	244	import java.io.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	245
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	246	public class ScriptVars {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	247	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	248	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	249	ScriptEngine engine = manager.getEngineByName("nashorn");
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	File f = new File("test.txt");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	252	// expose File object as variable to script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	253	engine.<span class="methodref">put</span>("file", f);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	254
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	255	// evaluate a script string. The script accesses "file"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	256	// variable and calls method on it
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	257	engine.eval("print(file.getAbsolutePath())");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	258	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	259	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	260
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	261	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	262	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	263	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	264	<a name="invoke" id="invoke"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	265	<h3>Invoking Script Functions and Methods</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	266	<p>Sometimes you may want to call a specific scripting function
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	267	repeatedly - for example, your application menu functionality might
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	268	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	269	may want to call a specific script function. The following example
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	270	demonstrates invoking a specific script function from Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	271	code.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	272	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	273	// <a href="source/InvokeScriptFunction.java">InvokeScriptFunction.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	274
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	275	import javax.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	public class InvokeScriptFunction {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	278	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	279	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	280	ScriptEngine engine = manager.getEngineByName("nashorn");
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	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	283	String script = "function hello(name) { print('Hello, ' + name); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	284	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	285	engine.eval(script);
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>javax.script.Invocable</code> is an optional interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	288	// Check whether your script engine implements it or not!
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	289	// Note that the JavaScript engine implements Invocable interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	290	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	291
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	292	// invoke the global function named "hello"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	293	inv.<span class="methodref">invokeFunction</span>("hello", "Scripting!!" );
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	}
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	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	298	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	299	<p>If your scripting language is object based (like JavaScript) or
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	300	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	301	object.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	302	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	303	// <a href="source/InvokeScriptMethod.java">InvokeScriptMethod.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	304
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	305	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	306
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	307	public class InvokeScriptMethod {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	308	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	309	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	310	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	311
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	312	// 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	313	// with one method called 'hello'.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	314	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	315	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	316	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	317
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	318	// <code>javax.script.Invocable</code> is an optional interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	319	// Check whether your script engine implements or not!
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	320	// Note that the JavaScript engine implements Invocable interface.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	321	<span class="classref">Invocable</span> inv = (Invocable) engine;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	322
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	323	// get script object on which we want to call the method
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	324	Object obj = engine.<span class="methodref">get</span>("obj");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	325
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	326	// invoke the method named "hello" on the script object "obj"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	327	inv.<span class="methodref">invokeMethod</span>(obj, "hello", "Script Method !!" );
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	328	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	329	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	330
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	331	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	332	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	333	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	334	<a name="interfaces" id="interfaces"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	335	<h3>Implementing Java Interfaces by Scripts</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	336	<p>Instead of calling specific script functions from Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	337	sometimes it is convenient to implement a Java interface by script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	338	functions or methods. Also, by using interfaces we can avoid having
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	339	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	340	an interface implementor object and pass it to various Java APIs.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	341	The following example demonstrates implementing the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	342	<code>java.lang.Runnable</code> interface with a script.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	343	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	344	// <a href="source/RunnableImpl.java">RunnableImpl.java</a>
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	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	347
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	348	public class RunnableImpl {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	349	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	350	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	351	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	352
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	353	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	354	String script = "function run() { print('run called'); }";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	355
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	356	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	357	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	358
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	359	<span class="classref">Invocable</span> inv = (Invocable) engine;
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	// get Runnable interface object from engine. This interface methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	362	// are implemented by script functions with the matching name.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	363	Runnable r = inv.<span class="methodref">getInterface</span>(Runnable.class);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	364
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	365	// start a new thread that runs the script implemented
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	366	// runnable interface
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	367	Thread th = new Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	368	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	369	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	370	}
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	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	373	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	374	<p>If your scripting language is object-based or object-oriented,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	375	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	376	script objects. This avoids having to call script global functions
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	377	for interface methods. The script object can store the "state"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	378	associated with the interface implementor.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	379	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	380	// <a href="source/RunnableImplObject.java">RunnableImplObject.java</a>
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	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	383
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	384	public class RunnableImplObject {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	385	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	386	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	387	ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	388
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	389	// JavaScript code in a String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	390	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	391
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	392	// evaluate script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	393	engine.eval(script);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	394
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	395	// 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	396	Object obj = engine.<span class="methodref">get</span>("obj");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	397
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	398	<span class="classref">Invocable</span> inv = (Invocable) engine;
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	// get Runnable interface object from engine. This interface methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	401	// are implemented by script methods of object 'obj'
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	402	Runnable r = inv.<span class="methodref">getInterface</span>(obj, Runnable.class);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	403
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	404	// start a new thread that runs the script implemented
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	405	// runnable interface
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	406	Thread th = new Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	407	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	408	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	409	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	410	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	411	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	412	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	413	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	414	<a name="scopes" id="scopes"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	415	<h3>Multiple Scopes for Scripts</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	416	<p>In the <a href="#scriptvars">script variables</a> example, we
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	417	saw how to expose application objects as script global variables.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	418	It is possible to expose multiple global "scopes" for scripts. A
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	419	single scope is an instance of <code>javax.script.Bindings</code>.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	420	This interface is derived from <code>java.util.Map<String,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	421	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	422	any non-empty, non-null String.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	423	<code>javax.script.ScriptContext</code> interface supports multiple
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	424	scopes with associated Bindings for each
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	425	scope. By default, every script engine has a default script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	426	context. The default script context has atleast one scope called
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	427	"ENGINE_SCOPE". Various scopes supported by a script context are
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	428	available through <code>getScopes</code> method.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	429	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	430	// <a href="source/MultiScopes.java">MultiScopes.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	431
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	432	import javax.script.*;
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	public class MultiScopes {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	435	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	436	ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	437	ScriptEngine engine = manager.getEngineByName("nashorn");
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	engine.put("x", "hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	440	// print global variable "x"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	441	engine.eval("print(x);");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	442	// the above line prints "hello"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	443
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	444	// Now, pass a different script context
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	445	<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	446	newContext.setBindings(engine.createBindings(), ScriptContext.ENGINE_SCOPE);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	447	<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	448
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	449	// add new variable "x" to the new engineScope
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	450	engineScope.<span class="methodref">put</span>("x", "world");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	451
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	452	// 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	453	engine.eval("print(x);", newContext);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	454	// the above line prints "world"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	455	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	456	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	457
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	458	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	459	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	460	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	461	<a name="jsengine" id="jsengine"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	462	<h2>JavaScript Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	463	<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	464	script engine.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	465	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	466	<a name="jstojava" id="jstojava"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	467	<h2>JavaScript to Java Communication</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	468	<p>For the most part, accessing Java classes, objects and methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	469	is straightforward. In particular field and method access from
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	470	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	471	aspects of JavaScript Java access here.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	472	The following examples are JavaScript snippets accessing Java. This
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	473	section requires knowledge of JavaScript. This section can be
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	474	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	475	language rather than JavaScript.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	476	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	477	<a name="jsjavaclass" id=jsjavalass"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	478	<h3>Accessing Java Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	479	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	480	<code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	481	// <a href="source/javatypes.js">javatypes.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	482
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	483	var arrayListType = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	484	var intType = Java.type("int")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	485	var stringArrayType = Java.type("java.lang.String[]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	486	var int2DArrayType = Java.type("int[][]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	487	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	488	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	489
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	490	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	491
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	492	<pre><code>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	493	var anArrayList = new (Java.type("java.util.ArrayList"))
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	494	</code></pre>
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	or
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	497
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	498	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	499	var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	500	var anArrayList = new ArrayList
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	501	var anArrayListWithSize = new ArrayList(16)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	502	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	503
18846 4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	504	In the special case of inner classes, you can either use the JVM fully qualified name, meaning using the dollar sign in the class name, or you can use the dot:
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	505
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	506	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	507	var ftype = Java.type("java.awt.geom.Arc2D$Float")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	508	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	509
18846 4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	510	and
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	511
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	512	<pre><code>
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	513	var ftype = Java.type("java.awt.geom.Arc2D.Float")
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	514	</code></pre>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	515
18846 4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type attila parents: 18615 diff changeset	516	both work. Note however that using the dollar sign is faster, as Java.type first tries to resolve the class name as it is originally specified, and the internal JVM names for inner classes use the dollar sign. If you use the dot, Java.type will internally get a ClassNotFoundException and subsequently retry by changing the last dot to dollar sign. As a matter of fact, it'll keep replacing dots with dollar signs until it either successfully loads the class or runs out of all dots in the name. This way it can correctly resolve and load even multiply nested inner classes with the dot notation. Again, this will be slower than using the dollar signs in the name. An alternative way to access the inner class is as a property of the outer class:
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	517
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	518	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	519	var arctype = Java.type("java.awt.geom.Arc2D")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	520	var ftype = arctype.Float
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	521	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	522	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	523	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	524	</p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	525	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	526	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	527	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	528	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	529	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	530	File.createTempFile("nashorn", ".tmp")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	531	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	532	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	533	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	534	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	535	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	536	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	537	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	538	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	539	var a = new ArrayList
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	540
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	541	// 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	542	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	543	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	544	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	545	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	546	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	547	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	548	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	549	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	550	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	551	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	552	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	553	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	554	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	555	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	556	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	557	<a name="jsimport" id="jsimport"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	558	<h3>Importing Java Packages, Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	559	<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	560	<code>importClass</code> can be used to import Java packages and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	561	classes.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	562	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	563
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	564	// <a href="source/importpackageclass.js">importpackageclass.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	565
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	566	// load compatibility script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	567	load("nashorn:mozilla_compat.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	568	// Import Java packages and classes
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	569	// like import package.*; in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	570	<span class="functionref">importPackage</span>(java.awt);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	571	// like import java.awt.Frame in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	572	<span class="functionref">importClass</span>(java.awt.Frame);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	573	// Create Java Objects by "new ClassName"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	574	var frame = new java.awt.Frame("hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	575	// Call Java public methods from script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	576	frame.setVisible(true);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	577	// Access "JavaBean" properties like "fields"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	578	print(frame.title);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	579	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	580	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	581	<p>The <span class="objectref">Packages</span> global variable can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	582	be used to access Java packages. Examples:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	583	<code>Packages.java.util.Vector</code>,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	584	<code>Packages.javax.swing.JFrame</code>. Please note that "java"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	585	is a shortcut for "Packages.java". There are equivalent shortcuts
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	586	for javax, org, edu, com, net prefixes, so pratically all JDK
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	587	platform classes can be accessed without the "Packages" prefix.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	588	<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	589	because that would result in conflicts with JavaScript's built-in
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	590	Object, Boolean, Math and so on.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	591	<p><code>importPackage</code> and <code>importClass</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	592	functions "pollute" the global variable scope of JavaScript. To
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	593	avoid that, you may use <span class="functionref">JavaImporter</span>.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	594	<pre><code>
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	// <a href="source/javaimporter.js">javaimporter.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	597
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	598	// create JavaImporter with specific packages and classes to import
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	599
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	600	var SwingGui = new <span class="functionref">JavaImporter</span>(javax.swing,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	601	javax.swing.event,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	602	javax.swing.border,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	603	java.awt.event);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	604	with (SwingGui) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	605	// within this 'with' statement, we can access Swing and AWT
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	606	// classes by unqualified (simple) names.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	607
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	608	var mybutton = new JButton("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	609	var myframe = new JFrame("test");
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
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	612	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	613	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	614	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	615	<a name="jsarrays" id="jsarrays"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	616	<h3>Creating, Converting and Using Java Arrays</h3>
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	617	<p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	618	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	619	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	620	// <a href="source/javaarray.js">javaarray.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	621
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	622	// create Java String array of 5 elements
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	623	var StringArray = Java.type("java.lang.String[]");
d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	624	var a = new StringArray(5);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	625
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	626	// Accessing elements and length access is by usual Java syntax
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	627	a[0] = "scripting is great!";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	628	print(a.length);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	629	print(a[0]);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	630	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	631	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	632	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	633	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	634	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	635	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	636	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	637	var anArray = [1, "13", false]
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	638	var javaIntArray = Java.to(anArray, "int[]")
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	639	print(javaIntArray[0]) // prints 1
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	640	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	641	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	642	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	643	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	644	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	645	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	646	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	647	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	648	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	649	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	650	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	651	var File = Java.type("java.io.File");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	652	var listCurDir = new File(".").listFiles();
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	653	var jsList = Java.from(listCurDir);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	654	print(jsList);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	655	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	656	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	657	<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	658	<h3>Implementing Java interfaces</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	659	<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	660	Java anonymous class-like syntax:</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	661	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	662	// <a href="source/runnable.js">runnable.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	663
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	664	var r = new java.lang.Runnable() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	665	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	666	print("running...\n");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	667	}
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	// "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	671	var th = new java.lang.Thread(r);
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	<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	677	a script function directly.(auto conversion)</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	678	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	679	// <a href="source/samfunc.js">samfunc.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	680
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	681	function func() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	682	print("I am func!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	683	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	684
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	685	// pass script function for java.lang.Runnable argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	686	var th = new java.lang.Thread(func);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	687	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	688	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	689	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	690	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	691	<hr>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	692	<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	693	<h3>Extending Abstract Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	694	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	695	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	696	</p>
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	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	699	var TimerTask = Java.type("java.util.TimerTask")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	700	var task = new TimerTask({ run: function() { print("Hello World!") } })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	701	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	702
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	703	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	704
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	705	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	706	var task = new TimerTask {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	707	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	708	print("Hello World!")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	709	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	710	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	711	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	712
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	713	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	714
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	715	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	716	var task = new TimerTask(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	717	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	718
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	719	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	720	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	721	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	722	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	723	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	724	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	725	<code><pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	726	Java.type("java.util.Timer")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	727	timer.schedule(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	728	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	729
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	730	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	731
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	732	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	733	<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	734	<h3>Extending Concrete Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	735	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	736	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	737	<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	738	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	739	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	740	// <a href="source/javaextend.js">javaextend.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	741
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	742	var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	743	var ArrayListExtender = Java.extend(ArrayList)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	744	var printSizeInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	745	size: function() { print("size invoked!"); }
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	746	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	747	var printAddInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	748	add: function(x, y) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	749	if(typeof(y) === "undefined") {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	750	print("add(e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	751	} else {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	752	print("add(i, e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	753	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	754	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	755	};
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	756	printSizeInvokedArrayList.size();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	757	printAddInvokedArrayList.add(33, 33);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	758	</code></pre>
17747 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	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	761	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	762	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	763	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	764	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	765	</code></pre>
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	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	768	<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	769	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	770	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	771	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	772	<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	773	<h3>Implementing Multiple Interfaces</h3>
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	<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	776	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	777	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	778	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	779	<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	780	<h3>Class-Bound Implementations</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	781	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	782	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	783	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	784	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	785	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	786	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	787	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	788	different JavaScript implementation objects:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	789	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	790	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	791	var Runnable = java.lang.Runnable;
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	792	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	793	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	794	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	795	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	796	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	797	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	798	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	799	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	800	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	801	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	802	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	803	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	804	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	805	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	806	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	807	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	808	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	809	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	810	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	811	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	812	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	813	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	814	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	815	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	816	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	817	are indeed different:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	818	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	819	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	820	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	821	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	822	var r1 = new RunnableImpl1()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	823	var r2 = new RunnableImpl2()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	824	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	825	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	826	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	827	</code></pre>
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	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	830	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	831	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	832	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	833	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	834	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	835	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	836	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	837	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	838	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	839	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	840	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	841	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	842	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	843	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	844	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	845	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	846	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	847	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	848	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	849	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	850	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	851	var r1 = new RunnableImpl()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	852	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	853	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	854	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	855	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	856	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	857	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	858	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	859	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	860	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	861	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	862	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	863	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	864	</code></pre>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	865	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	866	<a name="jsoverload" id="jsoverload"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	867	<h3>Overload Resolution</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	868	<p>Java methods can be overloaded by argument types. In Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	869	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	870	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	871	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	872	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	873	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	874	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	875	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	876	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	877	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	878	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	879	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	880	You can invoke them like this:</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	881	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	882	// <a href="source/overload.js">overload.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	883
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	884	var out = java.lang.System.out;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	885
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	886	// 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	887	out["println(Object)"]("hello");
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	888	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	889	</pre>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	890	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	891	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	892	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	893	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	894	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	895	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	896	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	897	class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	898	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	899	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	900	<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	901	<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	902	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	903	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	904	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	905	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	906	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	907	</p>
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	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	910	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	911	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	912	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	913	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	914	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	915	<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	916	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	917	<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	918	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	919	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	920	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	921	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	922	conversions.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	923	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	924	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	925	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	926	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	927	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	928	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	929	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	930	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	931	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	932	<a name="engineimpl" id="engineimpl"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	933	<h2>Implementing Your Own Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	934	<p>We will not cover implementation of JSR-223 compliant script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	935	engines in detail. Minimally, you need to implement the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	936	<code>javax.script.ScriptEngine</code> and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	937	<code>javax.script.ScriptEngineFactory</code> interfaces. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	938	abstract class <code>javax.script.AbstractScriptEngine</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	939	provides useful defaults for a few methods of the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	940	<code>ScriptEngine</code> interface.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	941	<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	942	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	943	project. This project maintains JSR-223 implementations for many
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	944	popular open source scripting languages.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	945	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	946	<a name="refs" id="refs"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	947	<h2>References</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	948	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	949	<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	950	for the Java Platform</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	951	<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	952	</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	953	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	954
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	955
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	956
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	957	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	958	<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	959	<tbody><tr valign="TOP">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	960	<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	961	<font size="+1"> <i>Java Technology</i></font> </td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	962
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	963	<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	964	<p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	965	<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	966	</font></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	967	</td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	968	<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	969	<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	970	</font></td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	971	</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	972	</tbody></table>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	973	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	974	</div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	975
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	976	<!-- Start SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	977	<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	978	<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	979
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	980	<!-- ******** DO NOT ALTER ANYTHING BELOW THIS LINE ! ********* -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	981	<!-- Below code will send the info to Omniture server -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	982	<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	983
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	984	<!-- End SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	985
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	986
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	987
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	988	</body></html>

author	eosterlund
	Tue, 12 Nov 2019 20:14:49 +0000
changeset 59040	1251d78fafbf
parent 47290	2853531b2c8c
permissions	-rw-r--r--