nashorn/docs/JavaScriptingProgrammersGuide.html
author psandoz
Tue, 13 Aug 2013 11:16:37 +0200
changeset 19424 c4524285927f
parent 18846 4ef5f2321c67
permissions -rw-r--r--
8022797: Clarify spliterator characteristics for collections containing no elements Reviewed-by: alanb, mduigou
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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&amp;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&amp;url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html&amp;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&amp;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&lt;String,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   421
Object&gt;</code>. A scope a set of name-value pairs where name is
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   422
any non-empty, non-null String.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   423
<code>javax.script.ScriptContext</code> interface supports multiple
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   424
scopes with associated Bindings for each
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   425
scope. By default, every script engine has a default script
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   426
context. The default script context has atleast one scope called
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   427
"ENGINE_SCOPE". Various scopes supported by a script context are
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   428
available through <code>getScopes</code> method.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   429
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   430
// <a href="source/MultiScopes.java">MultiScopes.java</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   431
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   432
import javax.script.*;
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   433
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   434
public class MultiScopes {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   435
    public static void main(String[] args) throws Exception {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   436
        ScriptEngineManager manager = new ScriptEngineManager();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   437
        ScriptEngine engine = manager.getEngineByName("nashorn");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   438
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   439
        engine.put("x", "hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   440
        // print global variable "x"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   441
        engine.eval("print(x);");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   442
        // the above line prints "hello"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   443
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   444
        // Now, pass a different script context
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   445
        <span class="classref">ScriptContext</span> newContext = new <span class="classref">SimpleScriptContext</span>();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   446
        newContext.setBindings(engine.createBindings(), ScriptContext.ENGINE_SCOPE);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   447
        <span class="classref">Bindings</span> engineScope = newContext.<span class="methodref">getBindings</span>(ScriptContext.ENGINE_SCOPE);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   448
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   449
        // add new variable "x" to the new engineScope        
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   450
        engineScope.<span class="methodref">put</span>("x", "world");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   451
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   452
        // execute the same script - but this time pass a different script context
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   453
        engine.eval("print(x);", newContext);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   454
        // the above line prints "world"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   455
    }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   456
}
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   457
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   458
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   459
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   460
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   461
<a name="jsengine" id="jsengine"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   462
<h2>JavaScript Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   463
<p>Oracle's implementation of JDK 8 is co-bundled with the Nashorn ECMAScript
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   464
script engine.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   465
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   466
<a name="jstojava" id="jstojava"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   467
<h2>JavaScript to Java Communication</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   468
<p>For the most part, accessing Java classes, objects and methods
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   469
is straightforward. In particular field and method access from
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   470
JavaScript is the same as it is from Java. We highlight important
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   471
aspects of JavaScript Java access here. 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   472
The following examples are JavaScript snippets accessing Java. This
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   473
section requires knowledge of JavaScript. This section can be
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   474
skipped if you are planning to use some other JSR-223 scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   475
language rather than JavaScript.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   476
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   477
<a name="jsjavaclass" id=jsjavalass"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   478
<h3>Accessing Java Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   479
<pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   480
<code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   481
// <a href="source/javatypes.js">javatypes.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   482
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   483
 var arrayListType = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   484
 var intType = Java.type("int")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   485
 var stringArrayType = Java.type("java.lang.String[]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   486
 var int2DArrayType = Java.type("int[][]")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   487
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   488
</pre> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   489
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   490
Note that the name of the type is always a string for a fully qualified name. You can use any of these expressions to create new instances, e.g.:
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   491
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   492
<pre><code>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   493
 var anArrayList = new (Java.type("java.util.ArrayList"))
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   494
</code></pre> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   495
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   496
or
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   497
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   498
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   499
 var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   500
 var anArrayList = new ArrayList
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   501
 var anArrayListWithSize = new ArrayList(16)
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   502
</code></pre> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   503
18846
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   504
In the special case of inner classes, you can either use the JVM fully qualified name, meaning using the dollar sign in the class name, or you can use the dot:
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   505
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   506
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   507
 var ftype = Java.type("java.awt.geom.Arc2D$Float")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   508
</code></pre> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   509
 
18846
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   510
and
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   511
 
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   512
<pre><code>
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   513
 var ftype = Java.type("java.awt.geom.Arc2D.Float")
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   514
</code></pre> 
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   515
18846
4ef5f2321c67 8017768: allow dot as inner class name separator for Java.type
attila
parents: 18615
diff changeset
   516
both work. Note however that using the dollar sign is faster, as Java.type first tries to resolve the class name as it is originally specified, and the internal JVM names for inner classes use the dollar sign. If you use the dot, Java.type will internally get a ClassNotFoundException and subsequently retry by changing the last dot to dollar sign. As a matter of fact, it'll keep replacing dots with dollar signs until it either successfully loads the class or runs out of all dots in the name. This way it can correctly resolve and load even multiply nested inner classes with the dot notation. Again, this will be slower than using the dollar signs in the name. An alternative way to access the inner class is as a property of the outer class:
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   517
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   518
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   519
 var arctype = Java.type("java.awt.geom.Arc2D")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   520
 var ftype = arctype.Float
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   521
</code></pre> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   522
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   523
You can access both static and non-static inner classes. If you want to create an instance of a non-static inner class, remember to pass an instance of its outer class as the first argument to the constructor.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   524
</p>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   525
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   526
In addition to creating new instances, the type objects returned from <code>Java.type</code> calls can also be used to access the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   527
static fields and methods of the classes:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   528
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   529
 var File = Java.type("java.io.File")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   530
 File.createTempFile("nashorn", ".tmp")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   531
</code></pre> 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   532
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   533
Methods with names of the form <code>isXxx()</code>, <code>getXxx()</code>, and <code>setXxx()</code> can also be used as properties, for both instances and statics.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   534
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   535
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   536
A type object returned from <code>Java.type</code> is distinct from a <code>java.lang.Class</code> object. You can obtain one from the other using properties <code>class</code> and <code>static</code> on them.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   537
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   538
 var ArrayList = Java.type("java.util.ArrayList")
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   539
 var a = new ArrayList
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   540
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   541
 // All of the following print true:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   542
 print("Type acts as target of instanceof: " + (a instanceof ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   543
 print("Class doesn't act as target of instanceof: " + !(a instanceof a.getClass()))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   544
 print("Type is not same as instance's getClass(): " + (a.getClass() !== ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   545
 print("Type's `class` property is same as instance getClass(): " + (a.getClass() === ArrayList.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   546
 print("Type is same as instance getClass()'s `static` property: " + (a.getClass().static === ArrayList))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   547
</code></pre> 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   548
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   549
You can think of the type object as similar to the class names as used in Java source code: you use them as the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   550
arguments to the <code>new</code> and <code>instanceof</code> operators and as the namespace for the static fields
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   551
and methods, but they are different than the runtime <code>Class</code> objects returned by <code>getClass()</code> calls.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   552
Syntactically and semantically, this separation produces code that is most similar to Java code, where a distinction
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   553
between compile-time class expressions and runtime class objects also exists. (Also, Java can't have the equivalent of <code>static</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   554
property on a <code>Class</code> object since compile-time class expressions are never reified as objects).
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   555
</p>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   556
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   557
<a name="jsimport" id="jsimport"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   558
<h3>Importing Java Packages, Classes</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   559
<p>The built-in functions <code>importPackage</code> (in compatibility script) and
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   560
<code>importClass</code> can be used to import Java packages and
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   561
classes.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   562
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   563
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   564
// <a href="source/importpackageclass.js">importpackageclass.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   565
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   566
// load compatibility script
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   567
load("nashorn:mozilla_compat.js");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   568
// Import Java packages and classes 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   569
// like import package.*; in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   570
<span class="functionref">importPackage</span>(java.awt);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   571
// like import java.awt.Frame in Java
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   572
<span class="functionref">importClass</span>(java.awt.Frame);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   573
// Create Java Objects by "new ClassName"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   574
var frame = new java.awt.Frame("hello");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   575
// Call Java public methods from script
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   576
frame.setVisible(true);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   577
// Access "JavaBean" properties like "fields"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   578
print(frame.title);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   579
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   580
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   581
<p>The <span class="objectref">Packages</span> global variable can
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   582
be used to access Java packages. Examples:
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   583
<code>Packages.java.util.Vector</code>,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   584
<code>Packages.javax.swing.JFrame</code>. Please note that "java"
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   585
is a shortcut for "Packages.java". There are equivalent shortcuts
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   586
for javax, org, edu, com, net prefixes, so pratically all JDK
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   587
platform classes can be accessed without the "Packages" prefix.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   588
<p>Note that java.lang is not imported by default (unlike Java)
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   589
because that would result in conflicts with JavaScript's built-in
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   590
Object, Boolean, Math and so on.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   591
<p><code>importPackage</code> and <code>importClass</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   592
functions "pollute" the global variable scope of JavaScript. To
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   593
avoid that, you may use <span class="functionref">JavaImporter</span>.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   594
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   595
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   596
// <a href="source/javaimporter.js">javaimporter.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   597
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   598
// create JavaImporter with specific packages and classes to import
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   599
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   600
var SwingGui = new <span class="functionref">JavaImporter</span>(javax.swing,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   601
                            javax.swing.event,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   602
                            javax.swing.border,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   603
                            java.awt.event);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   604
with (SwingGui) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   605
    // within this 'with' statement, we can access Swing and AWT
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   606
    // classes by unqualified (simple) names.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   607
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   608
    var mybutton = new JButton("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   609
    var myframe = new JFrame("test");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   610
}
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   611
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   612
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   613
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   614
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   615
<a name="jsarrays" id="jsarrays"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   616
<h3>Creating, Converting and Using Java Arrays</h3>
16522
d643e3ee819c 8009757: Package access clean up and refactoring
sundar
parents: 16212
diff changeset
   617
<p>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   618
Array element access or length access is the same as in Java.</p>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   619
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   620
// <a href="source/javaarray.js">javaarray.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   621
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   622
// create Java String array of 5 elements
16522
d643e3ee819c 8009757: Package access clean up and refactoring
sundar
parents: 16212
diff changeset
   623
var StringArray = Java.type("java.lang.String[]");
d643e3ee819c 8009757: Package access clean up and refactoring
sundar
parents: 16212
diff changeset
   624
var a = new StringArray(5);
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   625
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   626
// Accessing elements and length access is by usual Java syntax
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   627
a[0] = "scripting is great!";
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   628
print(a.length);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   629
print(a[0]);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   630
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   631
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   632
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   633
It is also possible to convert between JavaScript and Java arrays.
17758
2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively.
attila
parents: 17747
diff changeset
   634
Given a JavaScript array and a Java type, <code>Java.to</code> returns a Java array with the same initial contents, and with the specified array type. 
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   635
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   636
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   637
 var anArray = [1, "13", false]
17758
2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively.
attila
parents: 17747
diff changeset
   638
 var javaIntArray = Java.to(anArray, "int[]")
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   639
 print(javaIntArray[0]) // prints 1
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   640
 print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   641
 print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   642
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   643
<p>
17758
2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively.
attila
parents: 17747
diff changeset
   644
You can use either a string or a type object returned from <code>Java.type()</code> to specify the type of the array. 
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   645
You can also omit the array type, in which case a <code>Object[]</code> will be created.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   646
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   647
<p>
17758
2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively.
attila
parents: 17747
diff changeset
   648
Given a Java array or Collection, <code>Java.from</code> returns a JavaScript array with a shallow copy of its contents. Note that in most cases, you can use Java arrays and lists natively in Nashorn; in cases where for some reason you need to have an actual JavaScript native array (e.g. to work with the array comprehensions functions), you will want to use this method.
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   649
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   650
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   651
var File = Java.type("java.io.File");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   652
var listCurDir = new File(".").listFiles();
17758
2b056941e4dd 8014797: rename Java.toJavaArray/toJavaScriptArray to Java.to/from, respectively.
attila
parents: 17747
diff changeset
   653
var jsList = Java.from(listCurDir);
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   654
print(jsList);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   655
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   656
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   657
<a name="jsimplement" id="jsimplement"></a>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   658
<h3>Implementing Java interfaces</h3>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   659
<p>A Java interface can be implemented in JavaScript by using a
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   660
Java anonymous class-like syntax:</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   661
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   662
// <a href="source/runnable.js">runnable.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   663
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   664
var r  = new java.lang.Runnable() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   665
    run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   666
        print("running...\n");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   667
    }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   668
};
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   669
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   670
// "r" can be passed to Java methods that expect java.lang.Runnable
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   671
var th = new java.lang.Thread(r);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   672
th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   673
th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   674
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   675
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   676
<p>When an interface with a single method is expected, you can pass
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   677
a script function directly.(auto conversion)</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   678
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   679
// <a href="source/samfunc.js">samfunc.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   680
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   681
function func() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   682
     print("I am func!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   683
}
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   684
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   685
// pass script function for java.lang.Runnable argument
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   686
var th = new java.lang.Thread(func);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   687
th.start();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   688
th.join();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   689
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   690
</pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   691
<hr>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   692
<a name="jsextendabstract" id="jsextendabstract"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   693
<h3>Extending Abstract Java Classes</h3>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   694
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   695
If a Java class is abstract, you can instantiate an anonymous subclass of it using an argument list that is applicable to any of its public or protected constructors, but inserting a JavaScript object with functions properties that provide JavaScript implementations of the abstract methods. If method names are overloaded, the JavaScript function will provide implementation for all overloads. E.g.:
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   696
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   697
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   698
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   699
 var TimerTask =  Java.type("java.util.TimerTask")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   700
 var task = new TimerTask({ run: function() { print("Hello World!") } })
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   701
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   702
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   703
Nashorn supports a syntactic extension where a "new" expression followed by an argument is identical to invoking the constructor and passing the argument to it, so you can write the above example also as:
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   704
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   705
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   706
 var task = new TimerTask {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   707
     run: function() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   708
       print("Hello World!")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   709
     }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   710
 }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   711
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   712
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   713
which is very similar to Java anonymous inner class definition. On the other hand, if the type is an abstract type with a single abstract method (commonly referred to as a "SAM type") or all abstract methods it has share the same overloaded name), then instead of an object, you can just pass a function, so the above example can become even more simplified to:
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   714
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   715
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   716
 var task = new TimerTask(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   717
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   718
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   719
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   720
Note that in every one of these cases if you are trying to instantiate an abstract class that has constructors that take some arguments, you can invoke those simply by specifying the arguments after the initial implementation object or function.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   721
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   722
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   723
The use of functions can be taken even further; if you are invoking a Java method that takes a SAM type, you can just pass in a function object, and Nashorn will know what you meant:
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   724
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   725
<code><pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   726
 Java.type("java.util.Timer")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   727
 timer.schedule(function() { print("Hello World!") })
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   728
</code></pre>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   729
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   730
Here, <code>Timer.schedule()</code> expects a <code>TimerTask</code> as its argument, so Nashorn creates an instance of a TimerTask subclass and uses the passed function to implement its only abstract method, run(). In this usage though, you can't use non-default constructors; the type must be either an interface, or must have a protected or public no-arg constructor.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   731
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   732
<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   733
<a name="jsextendconcrete" id="jsextendconcrete"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   734
<h3>Extending Concrete Java Classes</h3>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   735
<p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   736
To extend a concrete Java class, you have to use <code>Java.extend</code> function.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   737
<code>Java.extend</code> returns a type object for a subclass of the specified Java class (or implementation of the specified interface) that acts as a script-to-Java adapter for it.  
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   738
</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   739
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   740
// <a href="source/javaextend.js">javaextend.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   741
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   742
var ArrayList = Java.type("java.util.ArrayList")
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   743
var ArrayListExtender = Java.extend(ArrayList)
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   744
var printSizeInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   745
    size: function() { print("size invoked!"); }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   746
}
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   747
var printAddInvokedArrayList = new ArrayListExtender() {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   748
    add: function(x, y) {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   749
        if(typeof(y) === "undefined") {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   750
            print("add(e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   751
        } else {
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   752
            print("add(i, e) invoked!");
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   753
        }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   754
    }
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   755
};
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   756
printSizeInvokedArrayList.size();
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   757
printAddInvokedArrayList.add(33, 33);
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   758
</code></pre>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   759
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   760
The reason you must use <code>Java.extend()</code> with concrete classes is that with concrete classes, there can be a 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   761
syntactic ambiguity if you just invoke their constructor. Consider this example:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   762
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   763
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   764
var t = new java.lang.Thread({ run: function() { print("Hello!") } })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   765
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   766
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   767
If we allowed subclassing of concrete classes with constructor syntax, Nashorn couldn't tell if you're creating a new 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   768
<code>Thread</code> and passing it a <code>Runnable</code> at this point, or you are subclassing <code>Thread</code> and
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   769
passing it a new implementation for its own <code>run()</code> method.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   770
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   771
<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   772
<a name="jsimplementmultiple" id="jsimplementmultiple"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   773
<h3>Implementing Multiple Interfaces</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   774
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   775
<code>Java.extend</code> can in fact take a list of multiple types. At most one of the types can be a class, and the rest must
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   776
be interfaces (the class doesn't have to be the first in the list). You will get back an object that extends the class and 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   777
implements all the interfaces. (Obviously, if you only specify interfaces and no class, the object will extend <code>java.lang.Object</code>).
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   778
<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   779
<a name="classBoundImplementations" id="classBoundImplementations"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   780
<h3>Class-Bound Implementations</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   781
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   782
The methods shown so far for extending Java classes and implementing interfaces &ndash; passing an implementation JavaScript object 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   783
or function to a constructor, or using <code>Java.extend</code> with <code>new</code> &ndash; all produce classes that take an
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   784
extra JavaScript object parameter in their constructors that specifies the implementation. The implementation is therefore always bound
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   785
to the actual instance being created with <code>new</code>, and not to the whole class. This has some advantages, for example in the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   786
memory footprint of the runtime, as Nashorn can just create a single "universal adapter" for every combination of types being implemented.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   787
In reality, the below code shows that different instantiations of, say, <code>Runnable</code> have the same class regardless of them having
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   788
different JavaScript implementation objects:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   789
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   790
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   791
var Runnable = java.lang.Runnable;
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   792
var r1 = new Runnable(function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   793
var r2 = new Runnable(function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   794
r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   795
r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   796
print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   797
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   798
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   799
prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   800
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   801
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   802
I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   803
I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   804
We share the same class: true
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   805
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   806
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   807
Sometimes, however, you'll want to extend a Java class or implement an interface with implementation bound to the class, not to
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   808
its instances. Such a need arises, for example, when you need to pass the class for instantiation to an external API; prime example
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   809
of this is the JavaFX framework where you need to pass an Application class to the FX API and let it instantiate it.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   810
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   811
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   812
Fortunately, there's a solution for that: <code>Java.extend()</code> &ndash; aside from being able to take any number of type parameters
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   813
denoting a class to extend and interfaces to implement &ndash; can also take one last argument that has to be a JavaScript object
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   814
that serves as the implementation for the methods. In this case, <code>Java.extend()</code> will create a class that has the same
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   815
constructors as the original class had, as they don't need to take an an extra implementation object parameter. The example below
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   816
shows how you can create class-bound implementations, and shows that in this case, the implementation classes for different invocations
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   817
are indeed different:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   818
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   819
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   820
var RunnableImpl1 = Java.extend(java.lang.Runnable, function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   821
var RunnableImpl2 = Java.extend(java.lang.Runnable, function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   822
var r1 = new RunnableImpl1()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   823
var r2 = new RunnableImpl2()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   824
r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   825
r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   826
print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   827
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   828
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   829
prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   830
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   831
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   832
I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   833
I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   834
We share the same class: false
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   835
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   836
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   837
As you can see, the major difference here is that we moved the implementation object into the invocation of <code>Java.extend</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   838
from the constructor invocations &ndash; indeed the constructor invocations now don't even need to take an extra parameter! Since
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   839
the implementations are bound to a class, the two classes obviously can't be the same, and we indeed see that the two runnables no
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   840
longer share the same class &ndash; every invocation of <code>Java.extend()</code> with a class-specific implementation object triggers
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   841
the creation of a new Java adapter class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   842
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   843
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   844
Finally, the adapter classes with class-bound implementations can <i>still</i> take an additional constructor parameter to further
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   845
override the behavior on a per-instance basis. Thus, you can even combine the two approaches: you can provide part of the implementation
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   846
in a class-based JavaScript implementation object passed to <code>Java.extend</code>, and part in another object passed to the constructor.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   847
Whatever functions are provided by the constructor-passed object will override the functions in the class-bound object.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   848
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   849
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   850
var RunnableImpl = Java.extend(java.lang.Runnable, function() { print("I'm runnable 1!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   851
var r1 = new RunnableImpl()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   852
var r2 = new RunnableImpl(function() { print("I'm runnable 2!") })
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   853
r1.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   854
r2.run()
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   855
print("We share the same class: " + (r1.class === r2.class))
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   856
</code></pre>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   857
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   858
prints:
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   859
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   860
<pre><code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   861
I'm runnable 1!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   862
I'm runnable 2!
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   863
We share the same class: true
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   864
</code></pre>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   865
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   866
<a name="jsoverload" id="jsoverload"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   867
<h3>Overload Resolution</h3>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   868
<p>Java methods can be overloaded by argument types. In Java,
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   869
overload resolution occurs at compile time (performed by javac).
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   870
When calling Java methods from Nashorn, the appropriate method will be
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   871
selected based on the argument types at invocation time. You do not need
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   872
to do anything special &ndash; the correct Java method overload variant 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   873
is selected based automatically. You still have the option of explicitly
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   874
specifying a particular overload variant. Reasons for this include 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   875
either running into a genuine ambiguity with actual argument types, or 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   876
rarely reasons of performance &ndash; if you specify the actual overload
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   877
then the engine doesn't have to perform resolution during invocation.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   878
Individual overloads of a Java methods are exposed as special properties
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   879
with the name of the method followed with its signature in parentheses. 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   880
You can invoke them like this:</p>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   881
<pre><code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   882
// <a href="source/overload.js">overload.js</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   883
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   884
var out = java.lang.System.out;
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   885
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   886
// select a particular print function 
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   887
out["println(Object)"]("hello");
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   888
</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   889
</pre>
17747
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   890
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   891
Note that you normally don't even have to use qualified class names in 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   892
the signatures as long as the unqualified name of the type is sufficient
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   893
for uniquely identifying the signature. In practice this means that only
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   894
in the extremely unlikely case that two overloads only differ in 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   895
parameter types that have identical unqualified names but come from 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   896
different packages would you need to use the fully qualified name of the
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   897
class.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   898
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   899
<hr>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   900
<a name="dataTypeMapping" id="dataTypeMapping"></a>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   901
<h3>Mapping of Data Types Between Java and JavaScript</h3>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   902
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   903
We have previously shown some of the data type mappings between Java and JavaScript.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   904
We saw that arrays need to be explicitly converted. We have also shown that JavaScript functions
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   905
are automatically converted to SAM types when passed as parameters to Java methods. Most other
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   906
conversions work as you would expect.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   907
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   908
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   909
Every JavaScript object is also a <code>java.util.Map</code> so APIs receiving maps will receive them directly.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   910
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   911
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   912
When numbers are passed to a Java API, they will be converted to the expected target numeric type, either boxed or
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   913
primitive, but if the target type is less specific, say <code>Number</code> or <code>Object</code>, you can only
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   914
count on them being a <code>Number</code>, and have to test specifically for whether it's a boxed <code>Double</code>,
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   915
<code>Integer</code>, <code>Long</code>, etc. &ndash; it can be any of these due to internal optimizations. Also, you 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   916
can pass any JavaScript value to a Java API expecting either a boxed or primitive number; the JavaScript specification's
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   917
<code>ToNumber</code> conversion algorithm will be applied to the value.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   918
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   919
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   920
In a similar vein, if a Java method expects a <code>String</code> or a <code>Boolean</code>, the values will be
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   921
converted using all conversions allowed by the JavaScript specification's <code>ToString</code> and <code>ToBoolean</code>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   922
conversions.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   923
</p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   924
<p>
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   925
Finally, a word of caution about strings. Due to internal performance optimizations of string operations, JavaScript strings are
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   926
not always necessarily of type <code>java.lang.String</code>, but they will always be of type <code>java.lang.CharSequence</code>.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   927
If you pass them to a Java method that expects a <code>java.lang.String</code> parameter, then you will naturally receive a Java
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   928
String, but if the signature of your method is more generic, i.e. it receives a <code>java.lang.Object</code> parameter, you can 
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   929
end up with an object of private engine implementation class that implements <code>CharSequence</code> but is not a Java String.
57c9166de06e 8014646: Update the Java interop documentation in the Java Scripting Programmer's Guide
attila
parents: 16784
diff changeset
   930
</p>
16212
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   931
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   932
<a name="engineimpl" id="engineimpl"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   933
<h2>Implementing Your Own Script Engine</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   934
<p>We will not cover implementation of JSR-223 compliant script
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   935
engines in detail. Minimally, you need to implement the
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   936
<code>javax.script.ScriptEngine</code> and
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   937
<code>javax.script.ScriptEngineFactory</code> interfaces. The
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   938
abstract class <code>javax.script.AbstractScriptEngine</code>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   939
provides useful defaults for a few methods of the
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   940
<code>ScriptEngine</code> interface.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   941
<p>Before starting to implement a JSR-223 engine, you may want to
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   942
check <a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting</a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   943
project. This project maintains JSR-223 implementations for many
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   944
popular open source scripting languages.</p>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   945
<hr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   946
<a name="refs" id="refs"></a>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   947
<h2>References</h2>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   948
<ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   949
<li><a href="http://jcp.org/en/jsr/detail?id=223">JSR-223 Scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   950
for the Java Platform</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   951
<li><a href="http://java.net/projects/Scripting">http://java.net/projects/Scripting
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   952
</a></li>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   953
</ul>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   954
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   955
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   956
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   957
<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   958
<table summary="layout" border="0" width="100%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   959
<tbody><tr valign="TOP">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   960
<td width="30%"> <img src="Java%20Scripting%20Programmer%27s%20Guide_files/logo_oracle_footer.gif" alt="Oracle and/or its affiliates" border="0" height="29" width="100"><br>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   961
<font size="+1"> <i>Java Technology</i></font> </td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   962
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   963
<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   964
<p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   965
<a href="http://docs.oracle.com/javase/6/docs/legal/cpyr.html">Copyright ©</a> 2013, Oracle and/or its affiliates. All rights reserved.
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   966
</font></p> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   967
</td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   968
<td width="30%">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   969
<p align="right"><font size="-2"><a href="http://download.oracle.com/javase/feedback.html">Contact Us</a></font></p><font size="-2">
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   970
</font></td>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   971
</tr>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   972
</tbody></table> 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   973
<div class="hr"><hr></div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   974
</div>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   975
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   976
<!-- Start SiteCatalyst code   -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   977
<script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code_download.js"></script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   978
<script language="JavaScript" src="Java%20Scripting%20Programmer%27s%20Guide_files/s_code.js"></script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   979
 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   980
<!-- ********** DO NOT ALTER ANYTHING BELOW THIS LINE ! *********** -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   981
<!--  Below code will send the info to Omniture server -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   982
<script language="javascript">var s_code=s.t();if(s_code)document.write(s_code)</script>
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   983
 
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   984
<!-- End SiteCatalyst code -->
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   985
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   986
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   987
363737d0d757 8007452: add scripting programmers doc changes for nashorn
sundar
parents:
diff changeset
   988
</body></html>