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

16784 ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	1	<!--
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	2	Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	3	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	4
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	5	This code is free software; you can redistribute it and/or modify it
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	6	under the terms of the GNU General Public License version 2 only, as
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	7	published by the Free Software Foundation. Oracle designates this
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	8	particular file as subject to the "Classpath" exception as provided
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	9	by Oracle in the LICENSE file that accompanied this code.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	10
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	11	This code is distributed in the hope that it will be useful, but WITHOUT
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	12	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	13	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	14	version 2 for more details (a copy is included in the LICENSE file that
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	15	accompanied this code).
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	16
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	17	You should have received a copy of the GNU General Public License version
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	18	2 along with this work; if not, write to the Free Software Foundation,
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	19	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	20
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	21	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	22	or visit www.oracle.com if you need additional information or have any
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	23	questions.
ba0dd689dd98 8012048: JDK8 b85 source with GPL header errors katleman parents: 16522 diff changeset	24	-->
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	25	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	26	<html class=" regenabled gecko radius jsenabled regloaded" xmlns="http://www.w3.org/1999/xhtml"><head>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	27	<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	28	<title>Java Scripting Programmer's Guide</title>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	29
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	30	<!-- ============ -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	31	<!-- MAIN CONTENT -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	32	<!-- ============ -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	33	<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	34	<tbody><tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	35	<td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	36
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	37	<div id="sharepage" class="smallpagetitle"><h1>Java Scripting Programmer's Guide</h1><div class="sharepage"> <div class="sharepagew1 share-mailto"> <table summary="" cellpadding="0" cellspacing="0"><tbody><tr> <td id="share-mailto"><a href="mailto:?subject=Java%20Documentation%20Page:%20Java%20Scripting%20Programmer%27s%20Guide&body=Check%20out%20this%20page:%20%0A%0Ahttp%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink mailto" title="Email this page to a friend"></a></td> <td id="share-technorati"><a href="http://technorati.com/search/http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink technorati" title="See who links to this page on Technorati"></a></td> <td id="share-delicious"><a href="http://del.icio.us/post?v=4;url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html;title=Java%20Scripting%20Programmer%27s%20Guide" class="sharelink delicious" title="Bookmark this page in del.icio.us"></a></td> <td id="share-digg"><a href="http://digg.com/submit?phase=2&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html&title=Java%20Scripting%20Programmer%27s%20Guide" class="sharelink digg" title="Submit this page to Digg"></a></td> <td id="share-slashdot"><a href="http://slashdot.org/bookmark.pl?title=Java%20Scripting%20Programmer%27s%20Guide&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html" class="sharelink slashdot" title="Submit this page to Slashdot"></a></td> <td id="share-blank"> </td></tr></tbody></table></div></div></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	38
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	39	</td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	40	</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	41	</tbody></table>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	42	<!-- Body text begins here -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	43	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	44	<li><span><a href="#who">Who is the Java Scripting API
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	45	For?</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	46	<li><span><a href="#package">Scripting Package</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	47	<li><span><a href="#examples">Examples</a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	48	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	49	<li><span><a href="#helloworld">"Hello, World"</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	50	<li><span><a href="#evalfile">Evaluating a Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	51	File</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	52	<li><span><a href="#scriptvars">Script Variables</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	53	<li><span><a href="#invoke">Invoking Script Functions and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	54	Methods</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	55	<li><span><a href="#interfaces">Implementing Java Interfaces by
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	56	Scripts</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	57	<li><span><a href="#scopes">Multiple Scopes for
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	58	Scripts</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	59	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	60	</li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	61	<li><span><a href="#jsengine">JavaScript Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	62	Engine</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	63	<li><span><a href="#jstojava">JavaScript to Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	64	Communication</a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	65	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	66	<li><span><a href="#jsjavaclass">Accessing Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	67	Classes</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	68	<li><span><a href="#jsimport">Importing Java Packages,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	69	Classes</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	70	<li><span><a href="#jsarrays">Creating, Converting and Using Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	71	Arrays</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	72	<li><span><a href="#jsimplement">Implementing Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	73	Interfaces</a></span></li>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	74	<li><span><a href="#jsextendabstract">Extending Abstract Java Classes
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	75	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	76	<li><span><a href="#jsextendconcrete">Extending Concrete Java Classes
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	77	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	78	<li><span><a href="#jsimplementmultiple">Implementing Multiple Java Interfaces
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	79	</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	80	<li><span><a href="#classBoundImplementations">Class-Bound Implementations
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	81	</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	82	<li><span><a href="#jsoverload">Overload Resolution</a></span></li>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	83	<li><span><a href="#dataTypeMapping">Mapping of Data Types Between Java
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	84	and JavaScript</a></span></li>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	85
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	86
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	87
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	88	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	89	</li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	90	<li><span><a href="#engineimpl">Implementing Your Own Script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	91	Engine</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	92	<li><span><a href="#refs">References</a></span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	93	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	94	<span><a name="who" id="who"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	95	<h2><span>Who is the Java Scripting API For?</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	96	<span>Some useful characteristics of scripting languages
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	97	are:</span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	98	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	99	<li><span><b>Convenience</b>: Most scripting languages are
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	100	dynamically typed. You can usually create new variables without
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	101	declaring the variable type, and you can reuse variables to store
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	102	objects of different types. Also, scripting languages tend to
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	103	perform many type conversions automatically, for example,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	104	converting the number 10 to the text "10" as necessary.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	105	<li><span><b>Developing rapid prototypes</b>: You can avoid the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	106	edit-compile-run cycle and just use edit-run!</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	107	<li><span><b>Application extension/customization</b>: You can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	108	"externalize" parts of your application - like configuration
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	109	scripts, business logic/rules and math expressions for financial
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	110	applications.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	111	<li><span><b>"Command line" shells for applications</b> -for
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	112	debugging, runtime/deploy time configuration etc. Most applications
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	113	have a web-based GUI configuaration tool these days. But
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	114	sysadmins/deployers frequently prefer command line tools. Instead
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	115	of inventing ad-hoc scripting language for that purpose, a
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	116	"standard" scripting language can be used.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	117	</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	118	<p><span>The Java<font size="-1"><sup>TM</sup></font> Scripting API
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	119	is a scripting language indepedent framework for using script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	120	engines from Java code. With the Java Scripting API, it is possible
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	121	to write customizable/extendable applications in the Java language
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	122	and leave the customization scripting language choice to the end
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	123	user. The Java application developer need not choose the extension
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	124	language during development. If you write your application with
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	125	JSR-223 API, then your users can use any JSR-223 compliant
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	126	scripting language.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	127	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	128	<span><a name="package" id="package"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	129	<h2><span>Scripting Package</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	130	<p><span>The Java Scripting functionality is in the <code><a href="http://docs.oracle.com/javase/6/docs/api/javax/script/package-summary.html">javax.script</a></code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	131	package. This is a relatively small, simple API. The starting point
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	132	of the scripting API is the <code>ScriptEngineManager</code> class.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	133	A ScriptEngineManager object can discover script engines through
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	134	the jar file service discovery mechanism. It can also instantiate
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	135	ScriptEngine objects that interpret scripts written in a specific
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	136	scripting language. The simplest way to use the scripting API is as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	137	follows:</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	138	<ol>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	139	<li><span>Create a <code>ScriptEngineManager</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	140	object.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	141	<li><span>Get a <code>ScriptEngine</code> object from the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	142	manager.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	143	<li><span>Evaluate script using the <code>ScriptEngine</code>'s
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	144	<code>eval</code> methods.</span></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	145	</ol>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	146	<p><span>Now, it is time to look at some sample code. While it is
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	147	not mandatory, it may be useful to know a bit of JavaScript to read
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	148	these examples.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	149	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	150	<span><a name="examples" id="examples"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	151	<h2><span>Examples</span></h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	152	<span><a name="helloworld" id="helloworld"></a></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	153	<h3><span>"Hello, World"</span></h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	154	<p><span>From the <code>ScriptEngineManager</code> instance, we
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	155	request a JavaScript engine instance using
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	156	<code>getEngineByName</code> method. On the script engine, the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	157	<code>eval</code> method is called to execute a given String as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	158	JavaScript code! For brevity, in this as well as in subsequent
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	159	examples, we have not shown exception handling. There are checked
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	160	and runtime exceptions thrown from <code>javax.script</code> API.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	161	Needless to say, you have to handle the exceptions
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	162	appropriately.</span></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	163	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	164	<span><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	165	// <a href="source/EvalScript.java">EvalScript.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	166
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	167	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	168	public class EvalScript {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	169	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	170	// create a script engine manager
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	171	<span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	172	// create a JavaScript engine
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	173	<span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	174	// evaluate JavaScript code from String
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	175	engine.<span class="methodref">eval</span>("print('Hello, World')");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	176	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	177	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	178	</code></span>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	179	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	180	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	181	<a name="evalfile" id="evalfile"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	182	<h3>Evaluating a Script File</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	183	<p>In this example, we call the <code>eval</code> method that
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	184	accepts <code>java.io.Reader</code> for the input source. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	185	script read by the given reader is executed. This way it is
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	186	possible to execute scripts from files, URLs and resources by
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	187	wrapping the relevant input stream objects as readers.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	188	<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	189	<code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	190	// <a href="source/EvalFile.java">EvalFile.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	191
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	192	import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	193
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	194	public class EvalFile {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	195	public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	196	// create a script engine manager
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	197	<span class="classref">ScriptEngineManager</span> factory = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	198	// create JavaScript engine
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	199	<span class="classref">ScriptEngine</span> engine = factory.<span class="methodref">getEngineByName</span>("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	200	// evaluate JavaScript code from given file - specified by first argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	201	engine.<span class="methodref">eval</span>(new java.io.FileReader(args[0]));
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	202	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	203	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	204	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	205	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	206	Let us assume that we have the file named <a href="source/test.js">test.js</a> with the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	207	following text:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	208	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	209	print("This is hello from test.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	210	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	211	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	212	We can run the above Java as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	213	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	214	java EvalFile test.js
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	215	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	216	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	217	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	218	<a name="scriptvars" id="scriptvars"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	219	<h3>Script Variables</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	220	<p>When you embed script engines and scripts with your Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	221	application, you may want to expose your application objects as
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	222	global variables to scripts. This example demonstrates how you can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	223	expose your application objects as global variables to a script. We
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	224	create a <code>java.io.File</code> in the application and expose
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	225	the same as a global variable with the name "file". The script can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	226	access the variable - for example, it can call public methods on
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	227	it. Note that the syntax to access Java objects, methods and fields
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	228	is dependent on the scripting language. JavaScript supports the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	229	most "natural" Java-like syntax.</p>
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
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	504	In the special case of inner classes, you need to use the JVM fully qualified name, meaning using $ sign in the class name:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	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
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	510
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	511	However, once you retrieved the outer class, you can access the inner class as a property on it:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	512
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	513	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	514	var arctype = Java.type("java.awt.geom.Arc2D")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	515	var ftype = arctype.Float
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	516	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	517	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	518	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	519	</p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	520	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	521	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	522	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	523	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	524	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	525	File.createTempFile("nashorn", ".tmp")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	526	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	527	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	528	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	529	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	530	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	531	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	532	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	533	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	534	var a = new ArrayList
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	535
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	536	// 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	537	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	538	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	539	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	540	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	541	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	542	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	543	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	544	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	545	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	546	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	547	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	548	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	549	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	550	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	551	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	552	<a name="jsimport" id="jsimport"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	553	<h3>Importing Java Packages, Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	554	<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	555	<code>importClass</code> can be used to import Java packages and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	556	classes.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	557	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	558
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	559	// <a href="source/importpackageclass.js">importpackageclass.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	560
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	561	// load compatibility script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	562	load("nashorn:mozilla_compat.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	563	// Import Java packages and classes
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	564	// like import package.*; in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	565	<span class="functionref">importPackage</span>(java.awt);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	566	// like import java.awt.Frame in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	567	<span class="functionref">importClass</span>(java.awt.Frame);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	568	// Create Java Objects by "new ClassName"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	569	var frame = new java.awt.Frame("hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	570	// Call Java public methods from script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	571	frame.setVisible(true);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	572	// Access "JavaBean" properties like "fields"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	573	print(frame.title);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	574	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	575	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	576	<p>The <span class="objectref">Packages</span> global variable can
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	577	be used to access Java packages. Examples:
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	578	<code>Packages.java.util.Vector</code>,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	579	<code>Packages.javax.swing.JFrame</code>. Please note that "java"
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	580	is a shortcut for "Packages.java". There are equivalent shortcuts
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	581	for javax, org, edu, com, net prefixes, so pratically all JDK
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	582	platform classes can be accessed without the "Packages" prefix.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	583	<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	584	because that would result in conflicts with JavaScript's built-in
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	585	Object, Boolean, Math and so on.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	586	<p><code>importPackage</code> and <code>importClass</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	587	functions "pollute" the global variable scope of JavaScript. To
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	588	avoid that, you may use <span class="functionref">JavaImporter</span>.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	589	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	590
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	591	// <a href="source/javaimporter.js">javaimporter.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	592
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	593	// create JavaImporter with specific packages and classes to import
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	594
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	595	var SwingGui = new <span class="functionref">JavaImporter</span>(javax.swing,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	596	javax.swing.event,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	597	javax.swing.border,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	598	java.awt.event);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	599	with (SwingGui) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	600	// within this 'with' statement, we can access Swing and AWT
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	601	// classes by unqualified (simple) names.
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	602
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	603	var mybutton = new JButton("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	604	var myframe = new JFrame("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	605	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	606
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	607	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	608	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	609	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	610	<a name="jsarrays" id="jsarrays"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	611	<h3>Creating, Converting and Using Java Arrays</h3>
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	612	<p>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	613	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	614	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	615	// <a href="source/javaarray.js">javaarray.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	616
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	617	// create Java String array of 5 elements
16522 d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	618	var StringArray = Java.type("java.lang.String[]");
d643e3ee819c 8009757: Package access clean up and refactoring sundar parents: 16212 diff changeset	619	var a = new StringArray(5);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	620
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	621	// Accessing elements and length access is by usual Java syntax
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	622	a[0] = "scripting is great!";
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	623	print(a.length);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	624	print(a[0]);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	625	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	626	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	627	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	628	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	629	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	630	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	631	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	632	var anArray = [1, "13", false]
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	633	var javaIntArray = Java.to(anArray, "int[]")
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	634	print(javaIntArray[0]) // prints 1
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	635	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	636	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	637	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	638	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	639	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	640	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	641	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	642	<p>
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	643	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	644	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	645	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	646	var File = Java.type("java.io.File");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	647	var listCurDir = new File(".").listFiles();
17758 2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively. attila parents: 17747 diff changeset	648	var jsList = Java.from(listCurDir);
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	649	print(jsList);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	650	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	651	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	652	<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	653	<h3>Implementing Java interfaces</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	654	<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	655	Java anonymous class-like syntax:</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	656	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	657	// <a href="source/runnable.js">runnable.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	658
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	659	var r = new java.lang.Runnable() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	660	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	661	print("running...\n");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	662	}
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
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	665	// "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	666	var th = new java.lang.Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	667	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	668	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	669	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	670	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	671	<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	672	a script function directly.(auto conversion)</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	673	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	674	// <a href="source/samfunc.js">samfunc.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	675
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	676	function func() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	677	print("I am func!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	678	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	679
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	680	// pass script function for java.lang.Runnable argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	681	var th = new java.lang.Thread(func);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	682	th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	683	th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	684	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	685	</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	686	<hr>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	687	<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	688	<h3>Extending Abstract Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	689	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	690	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	691	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	692
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	693	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	694	var TimerTask = Java.type("java.util.TimerTask")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	695	var task = new TimerTask({ run: function() { print("Hello World!") } })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	696	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	697
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	698	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	699
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	700	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	701	var task = new TimerTask {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	702	run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	703	print("Hello World!")
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	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	706	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	707
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	708	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	709
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	710	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	711	var task = new TimerTask(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	712	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	713
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	714	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	715	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	716	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	717	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	718	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	719	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	720	<code><pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	721	Java.type("java.util.Timer")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	722	timer.schedule(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	723	</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	724
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	725	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	726
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	727	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	728	<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	729	<h3>Extending Concrete Java Classes</h3>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	730	<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	731	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	732	<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	733	</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	734	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	735	// <a href="source/javaextend.js">javaextend.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	736
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	737	var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	738	var ArrayListExtender = Java.extend(ArrayList)
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	739	var printSizeInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	740	size: function() { print("size invoked!"); }
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 printAddInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	743	add: function(x, y) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	744	if(typeof(y) === "undefined") {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	745	print("add(e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	746	} else {
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	747	print("add(i, e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	748	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	749	}
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	750	};
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	751	printSizeInvokedArrayList.size();
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	752	printAddInvokedArrayList.add(33, 33);
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	753	</code></pre>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	754	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	755	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	756	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	757	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	758	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	759	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	760	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	761	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	762	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	763	<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	764	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	765	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	766	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	767	<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	768	<h3>Implementing Multiple Interfaces</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	769	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	770	<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	771	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	772	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	773	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	774	<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	775	<h3>Class-Bound Implementations</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	776	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	777	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	778	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	779	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	780	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	781	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	782	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	783	different JavaScript implementation objects:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	784	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	785	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	786	var Runnable = java.lang.Runnable;
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	787	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	788	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	789	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	790	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	791	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	792	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	793	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	794	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	795	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	796	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	797	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	798	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	799	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	800	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	801	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	802	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	803	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	804	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	805	</p>
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	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	808	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	809	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	810	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	811	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	812	are indeed different:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	813	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	814	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	815	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	816	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	817	var r1 = new RunnableImpl1()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	818	var r2 = new RunnableImpl2()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	819	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	820	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	821	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	822	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	823	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	824	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	825	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	826	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	827	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	828	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	829	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	830	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	831	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	832	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	833	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	834	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	835	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	836	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	837	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	838	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	839	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	840	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	841	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	842	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	843	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	844	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	845	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	846	var r1 = new RunnableImpl()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	847	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	848	r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	849	r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	850	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	851	</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	852	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	853	prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	854	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	855	<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	856	I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	857	I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	858	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	859	</code></pre>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	860	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	861	<a name="jsoverload" id="jsoverload"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	862	<h3>Overload Resolution</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	863	<p>Java methods can be overloaded by argument types. In Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	864	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	865	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	866	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	867	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	868	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	869	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	870	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	871	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	872	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	873	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	874	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	875	You can invoke them like this:</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	876	<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	877	// <a href="source/overload.js">overload.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	878
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	879	var out = java.lang.System.out;
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	880
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	881	// 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	882	out["println(Object)"]("hello");
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	883	</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	884	</pre>
17747 57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	885	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	886	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	887	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	888	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	889	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	890	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	891	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	892	class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	893	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	894	<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	895	<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	896	<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	897	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	898	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	899	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	900	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	901	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	902	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	903	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	904	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	905	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	906	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	907	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	908	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	909	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	910	<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	911	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	912	<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	913	</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	914	<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide attila parents: 16784 diff changeset	915	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	916	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	917	conversions.
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	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	921	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	922	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	923	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	924	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	925	</p>
16212 363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	926	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	927	<a name="engineimpl" id="engineimpl"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	928	<h2>Implementing Your Own Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	929	<p>We will not cover implementation of JSR-223 compliant script
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	930	engines in detail. Minimally, you need to implement the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	931	<code>javax.script.ScriptEngine</code> and
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	932	<code>javax.script.ScriptEngineFactory</code> interfaces. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	933	abstract class <code>javax.script.AbstractScriptEngine</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	934	provides useful defaults for a few methods of the
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	935	<code>ScriptEngine</code> interface.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	936	<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	937	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	938	project. This project maintains JSR-223 implementations for many
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	939	popular open source scripting languages.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	940	<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	941	<a name="refs" id="refs"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	942	<h2>References</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	943	<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	944	<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	945	for the Java Platform</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	946	<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	947	</a></li>
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
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	950
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	951
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	952	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	953	<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	954	<tbody><tr valign="TOP">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	955	<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	956	<font size="+1"> <i>Java Technology</i></font> </td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	957
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	958	<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	959	<p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	960	<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	961	</font></p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	962	</td>
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 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	965	</font></td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	966	</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	967	</tbody></table>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	968	<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	969	</div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	970
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	971	<!-- Start SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	972	<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	973	<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	974
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	975	<!-- ******** DO NOT ALTER ANYTHING BELOW THIS LINE ! ********* -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	976	<!-- Below code will send the info to Omniture server -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	977	<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	978
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	979	<!-- End SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	980
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	981
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	982
363737d0d757 8007452: add scripting programmers doc changes for nashorn sundar parents: diff changeset	983	</body></html>

author	cl
	Thu, 18 Jul 2013 03:39:39 -0700
changeset 18837	d0545441225e
parent 18615	3f6e6adcbc1a
child 18846	4ef5f2321c67
permissions	-rw-r--r--