<divid="sharepage"class="smallpagetitle"><h1>Java Scripting Programmer's Guide</h1><divclass="sharepage"><divclass="sharepagew1 share-mailto"><tablesummary=""cellpadding="0"cellspacing="0"><tbody><tr><tdid="share-mailto"><ahref="mailto:?subject=Java%20Documentation%20Page:%20Java%20Scripting%20Programmer%27s%20Guide&body=Check%20out%20this%20page:%20%0A%0Ahttp%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html"class="sharelink mailto"title="Email this page to a friend"></a></td><tdid="share-technorati"><ahref="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><tdid="share-delicious"><ahref="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><tdid="share-digg"><ahref="http://digg.com/submit?phase=2&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html&title=Java%20Scripting%20Programmer%27s%20Guide"class="sharelink digg"title="Submit this page to Digg"></a></td><tdid="share-slashdot"><ahref="http://slashdot.org/bookmark.pl?title=Java%20Scripting%20Programmer%27s%20Guide&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html"class="sharelink slashdot"title="Submit this page to Slashdot"></a></td><tdid="share-blank"></td></tr></tbody></table></div></div></div>
</td>
</tr>
</tbody></table>
<!-- Body text begins here -->
<ul>
<li><span><ahref="#who">Who is the Java Scripting API
<h2><span>Who is the Java Scripting API For?</span></h2>
<span>Some useful characteristics of scripting languages
are:</span>
<ul>
<li><span><b>Convenience</b>: Most scripting languages are
dynamically typed. You can usually create new variables without
declaring the variable type, and you can reuse variables to store
objects of different types. Also, scripting languages tend to
perform many type conversions automatically, for example,
converting the number 10 to the text "10" as necessary.</span></li>
<li><span><b>Developing rapid prototypes</b>: You can avoid the
edit-compile-run cycle and just use edit-run!</span></li>
<li><span><b>Application extension/customization</b>: You can
"externalize" parts of your application - like configuration
scripts, business logic/rules and math expressions for financial
applications.</span></li>
<li><span><b>"Command line" shells for applications</b> -for
debugging, runtime/deploy time configuration etc. Most applications
have a web-based GUI configuaration tool these days. But
sysadmins/deployers frequently prefer command line tools. Instead
of inventing ad-hoc scripting language for that purpose, a
"standard" scripting language can be used.</span></li>
</ul>
<p><span>The Java<fontsize="-1"><sup>TM</sup></font> Scripting API
is a scripting language indepedent framework for using script
engines from Java code. With the Java Scripting API, it is possible
to write customizable/extendable applications in the Java language
and leave the customization scripting language choice to the end
user. The Java application developer need not choose the extension
language during development. If you write your application with
JSR-223 API, then your users can use any JSR-223 compliant
scripting language.</span></p>
<hr>
<span><aname="package"id="package"></a></span>
<h2><span>Scripting Package</span></h2>
<p><span>The Java Scripting functionality is in the <code><ahref="http://docs.oracle.com/javase/6/docs/api/javax/script/package-summary.html">javax.script</a></code>
package. This is a relatively small, simple API. The starting point
of the scripting API is the <code>ScriptEngineManager</code> class.
A ScriptEngineManager object can discover script engines through
the jar file service discovery mechanism. It can also instantiate
ScriptEngine objects that interpret scripts written in a specific
scripting language. The simplest way to use the scripting API is as
follows:</span></p>
<ol>
<li><span>Create a <code>ScriptEngineManager</code>
object.</span></li>
<li><span>Get a <code>ScriptEngine</code> object from the
manager.</span></li>
<li><span>Evaluate script using the <code>ScriptEngine</code>'s
<code>eval</code> methods.</span></li>
</ol>
<p><span>Now, it is time to look at some sample code. While it is
not mandatory, it may be useful to know a bit of JavaScript to read
In the special case of inner classes, you need to use the JVM fully qualified name, meaning using $ sign in the class name:
<pre><code>
var ftype = Java.type("java.awt.geom.Arc2D$Float")
</code></pre>
However, once you retrieved the outer class, you can access the inner class as a property on it:
<pre><code>
var arctype = Java.type("java.awt.geom.Arc2D")
var ftype = arctype.Float
</code></pre>
<p>
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.
In addition to creating new instances, the type objects returned from <code>Java.type</code> calls can also be used to access the
static fields and methods of the classes:
<pre><code>
var File = Java.type("java.io.File")
File.createTempFile("nashorn", ".tmp")
</code></pre>
<p>
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.
</p>
<p>
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.
<pre><code>
var ArrayList = Java.type("java.util.ArrayList")
var a = new ArrayList
// All of the following print true:
print("Type acts as target of instanceof: " + (a instanceof ArrayList))
print("Class doesn't act as target of instanceof: " + !(a instanceof a.getClass()))
print("Type is not same as instance's getClass(): " + (a.getClass() !== ArrayList))
print("Type's `class` property is same as instance getClass(): " + (a.getClass() === ArrayList.class))
print("Type is same as instance getClass()'s `static` property: " + (a.getClass().static === ArrayList))
</code></pre>
<p>
You can think of the type object as similar to the class names as used in Java source code: you use them as the
arguments to the <code>new</code> and <code>instanceof</code> operators and as the namespace for the static fields
and methods, but they are different than the runtime <code>Class</code> objects returned by <code>getClass()</code> calls.
Syntactically and semantically, this separation produces code that is most similar to Java code, where a distinction
between compile-time class expressions and runtime class objects also exists. (Also, Java can't have the equivalent of <code>static</code>
property on a <code>Class</code> object since compile-time class expressions are never reified as objects).
// Accessing elements and length access is by usual Java syntax
a[0] = "scripting is great!";
print(a.length);
print(a[0]);
</code>
</pre>
<p>
It is also possible to convert between JavaScript and Java arrays.
Given a JavaScript array and a Java type, <code>Java.toJavaArray</code> returns a Java array with the same initial contents, and with the specified component type.
</p>
<pre><code>
var anArray = [1, "13", false]
var javaIntArray = Java.toJavaArray(anArray, "int")
print(javaIntArray[0]) // prints 1
print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion
print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion
You can use either a string or a type object returned from <code>Java.type()</code> to specify the component type of the array.
You can also omit the array type, in which case a <code>Object[]</code> will be created.
</p>
<p>
Given a Java array or Collection, <code>Java.toJavaScriptArray</code> returns a JavaScript array with a shallow copy of its contents. Note that in most cases, you can use Java arrays and lists natively in Nashorn; in cases where for some reason you need to have an actual JavaScript native array (e.g. to work with the array comprehensions functions), you will want to use this method.
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.:
</p>
<pre><code>
var TimerTask = Java.type("java.util.TimerTask")
var task = new TimerTask({ run: function() { print("Hello World!") } })
</code></pre>
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:
<pre><code>
var task = new TimerTask {
run: function() {
print("Hello World!")
}
}
</code></pre>
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:
<pre><code>
var task = new TimerTask(function() { print("Hello World!") })
</code></pre>
<p>
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.
</p>
<p>
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:
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.
To extend a concrete Java class, you have to use <code>Java.extend</code> function.
<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.
<tdwidth="30%"><imgsrc="Java%20Scripting%20Programmer%27s%20Guide_files/logo_oracle_footer.gif"alt="Oracle and/or its affiliates"border="0"height="29"width="100"><br>
<fontsize="+1"><i>Java Technology</i></font></td>
<tdwidth="30%">
<p><fontsize="-2">
<ahref="http://docs.oracle.com/javase/6/docs/legal/cpyr.html">Copyright <20></a> 2013, Oracle and/or its affiliates. All rights reserved.
