This commit is contained in:
Lana Steuck 2017-01-05 19:46:28 +00:00
commit e0fa88d6fa
7 changed files with 269 additions and 339 deletions
nashorn
READMERELEASE_README
make
src
jdk.dynalink/share/classes
jdk.scripting.nashorn/share/classes

@ -24,33 +24,33 @@ and downlaoded using
You can clone Nashorn Mercurial forest using this command:
hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8
hg fclone http://hg.openjdk.java.net/nashorn/jdk9 nashorn~jdk9
To update your copy of the forest (fwith the latest code:
(cd nashorn~jdk8 ; hg fpull)
(cd nashorn~jdk9 ; hg fpull)
Or just the nashorn subdirectory with
(cd nashorn~jdk8/nashorn ; hg pull -u)
(cd nashorn~jdk9/nashorn ; hg pull -u)
To learn about Mercurial in detail, please visit http://hgbook.red-bean.com.
- How to build?
To build Nashorn, you need to install JDK 8. You may use the Nashorn
To build Nashorn, you need to install JDK 9. You may use the Nashorn
forest build (recommended) or down load from java.net. You will need to
set JAVA_HOME environmental variable to point to your JDK installation
directory.
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant clean; ant
- How to run?
Use the jjs script (see RELESE_README):
cd nashorn~jdk8/nashorn
cd nashorn~jdk9/nashorn
sh bin/jjs <your .js file>
Nashorn supports javax.script API. It is possible to drop nashorn.jar in
@ -64,7 +64,7 @@ Look for samples under the directory test/src/jdk/nashorn/api/scripting/.
Comprehensive development documentation is found in the Nashorn JavaDoc. You can
build it using:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant javadoc
after which you can view the generated documentation at dist/javadoc/index.html.
@ -90,7 +90,7 @@ Alternatively, you can check it out elsewhere and make
test/script/external/test262 a symbolic link to that directory. After
you've done this, you can run the ECMA-262 tests using:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant test262
Ant target to get/update external test suites:
@ -101,7 +101,7 @@ Ant target to get/update external test suites:
These tests take time, so we have a parallelized runner for them that
takes advantage of all processor cores on the computer:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant test262parallel
- How to write your own test?

@ -1,20 +0,0 @@
The Nashorn repo is in the process of being migrated to OpenJDK and as such is
incomplete in several areas.
- The build system is not fully integrated. When complete, Nashorn will be
installed in its proper location in the JRE.
- Once integrated, the correct version of the JDK will be wrapped around
Nashorn. In the meantime, ensure you use JDK8 b68 or later.
- The jjs tool has not been implemented in binary form yet. Use "sh bin/jjs"
(or bin/jjs.bat on windows) in the interm.
- The Dynalink component is not fully integrated into Nashorn as yet, but will
be when details are finalized.
- And, finally Nashorn is still in development. To stay up to date, subscribe
to nashorn-dev@openjdk.java.net at
http://mail.openjdk.java.net/mailman/listinfo/nashorn-dev.

@ -267,7 +267,7 @@
<!-- generate javadoc for Nashorn classes -->
<target name="javadoc" depends="jar">
<javadoc destdir="${dist.javadoc.dir}" use="yes" overview="${nashorn.module.src.dir}/overview.html"
<javadoc destdir="${dist.javadoc.dir}" use="yes"
windowtitle="${nashorn.product.name} ${nashorn.version}"
additionalparam="-quiet" failonerror="true" useexternalfile="true">
<arg value="--module-source-path"/>
@ -285,7 +285,7 @@
<!-- generate javadoc only for nashorn extension api classes -->
<target name="nashornapi" depends="jar">
<mkdir dir="${dist.nashornapi.javadoc.dir}"/>
<javadoc destdir="${dist.nashornapi.javadoc.dir}" use="yes" overview="${nashorn.module.src.dir}/overview.html"
<javadoc destdir="${dist.nashornapi.javadoc.dir}" use="yes"
extdirs="${nashorn.ext.path}" windowtitle="${nashorn.product.name} ${nashorn.version}"
additionalparam="-quiet" failonerror="true" useexternalfile="true">
<arg value="--module-source-path"/>

@ -82,197 +82,6 @@
*/
/**
* <p>
* Dynalink is a library for dynamic linking of high-level operations on objects.
* These operations include "read a property",
* "write a property", "invoke a function" and so on. Dynalink is primarily
* useful for implementing programming languages where at least some expressions
* have dynamic types (that is, types that can not be decided statically), and
* the operations on dynamic types are expressed as
* {@link java.lang.invoke.CallSite call sites}. These call sites will be
* linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}
* at run time based on actual types of the values the expressions evaluated to.
* These can change between invocations, necessitating relinking the call site
* multiple times to accommodate new types; Dynalink handles all that and more.
* <p>
* Dynalink supports implementation of programming languages with object models
* that differ (even radically) from the JVM's class-based model and have their
* custom type conversions.
* <p>
* Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
* package.
* <p>
*
* While {@link java.lang.invoke} provides a low level API for dynamic linking
* of {@code invokedynamic} call sites, it does not provide a way to express
* higher level operations on objects, nor methods that implement them. These
* operations are the usual ones in object-oriented environments: property
* access, access of elements of collections, invocation of methods and
* constructors (potentially with multiple dispatch, e.g. link- and run-time
* equivalents of Java overloaded method resolution). These are all functions
* that are normally desired in a language on the JVM. If a language is
* statically typed and its type system matches that of the JVM, it can
* accomplish this with use of the usual invocation, field access, etc.
* instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the
* language is dynamic (hence, types of some expressions are not known until
* evaluated at run time), or its object model or type system don't match
* closely that of the JVM, then it should use {@code invokedynamic} call sites
* instead and let Dynalink manage them.
* <h2>Example</h2>
* Dynalink is probably best explained by an example showing its use. Let's
* suppose you have a program in a language where you don't have to declare the
* type of an object and you want to access a property on it:
* <pre>
* var color = obj.color;
* </pre>
* If you generated a Java class to represent the above one-line program, its
* bytecode would look something like this:
* <pre>
* aload 2 // load "obj" on stack
* invokedynamic "GET:PROPERTY:color"(Object)Object // invoke property getter on object of unknown type
* astore 3 // store the return value into local variable "color"
* </pre>
* In order to link the {@code invokedynamic} instruction, we need a bootstrap
* method. A minimalist bootstrap method with Dynalink could look like this:
* <pre>
* import java.lang.invoke.*;
* import jdk.dynalink.*;
* import jdk.dynalink.support.*;
*
* class MyLanguageRuntime {
* private static final DynamicLinker dynamicLinker = new DynamicLinkerFactory().createLinker();
*
* public static CallSite bootstrap(MethodHandles.Lookup lookup, String name, MethodType type) {
* return dynamicLinker.link(
* new SimpleRelinkableCallSite(
* new CallSiteDescriptor(lookup, parseOperation(name), type)));
* }
*
* private static Operation parseOperation(String name) {
* ...
* }
* }
* </pre>
* There are several objects of significance in the above code snippet:
* <ul>
* <li>{@link jdk.dynalink.DynamicLinker} is the main object in Dynalink, it
* coordinates the linking of call sites to method handles that implement the
* operations named in them. It is configured and created using a
* {@link jdk.dynalink.DynamicLinkerFactory}.</li>
* <li>When the bootstrap method is invoked, it needs to create a
* {@link java.lang.invoke.CallSite} object. In Dynalink, these call sites need
* to additionally implement the {@link jdk.dynalink.RelinkableCallSite}
* interface. "Relinkable" here alludes to the fact that if the call site
* encounters objects of different types at run time, its target will be changed
* to a method handle that can perform the operation on the newly encountered
* type. {@link jdk.dynalink.support.SimpleRelinkableCallSite} and
* {@link jdk.dynalink.support.ChainedCallSite} (not used in the above example)
* are two implementations already provided by the library.</li>
* <li>Dynalink uses {@link jdk.dynalink.CallSiteDescriptor} objects to
* preserve the parameters to the bootstrap method: the lookup and the method type,
* as it will need them whenever it needs to relink a call site.</li>
* <li>Dynalink uses {@link jdk.dynalink.Operation} objects to express
* dynamic operations. It does not prescribe how would you encode the operations
* in your call site, though. That is why in the above example the
* {@code parseOperation} function is left empty, and you would be expected to
* provide the code to parse the string {@code "GET:PROPERTY:color"}
* in the call site's name into a named property getter operation object as
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}.
* </ul>
* <p>What can you already do with the above setup? {@code DynamicLinkerFactory}
* by default creates a {@code DynamicLinker} that can link Java objects with the
* usual Java semantics. If you have these three simple classes:
* <pre>
* public class A {
* public String color;
* public A(String color) { this.color = color; }
* }
*
* public class B {
* private String color;
* public B(String color) { this.color = color; }
* public String getColor() { return color; }
* }
*
* public class C {
* private int color;
* public C(int color) { this.color = color; }
* public int getColor() { return color; }
* }
* </pre>
* and you somehow create their instances and pass them to your call site in your
* programming language:
* <pre>
* for each(var obj in [new A("red"), new B("green"), new C(0x0000ff)]) {
* print(obj.color);
* }
* </pre>
* then on first invocation, Dynalink will link the {@code .color} getter
* operation to a field getter for {@code A.color}, on second invocation it will
* relink it to {@code B.getColor()} returning a {@code String}, and finally on
* third invocation it will relink it to {@code C.getColor()} returning an {@code int}.
* The {@code SimpleRelinkableCallSite} we used above only remembers the linkage
* for the last encountered type (it implements what is known as a <i>monomorphic
* inline cache</i>). Another already provided implementation,
* {@link jdk.dynalink.support.ChainedCallSite} will remember linkages for
* several different types (it is a <i>polymorphic inline cache</i>) and is
* probably a better choice in serious applications.
* <h2>Dynalink and bytecode creation</h2>
* {@code CallSite} objects are usually created as part of bootstrapping
* {@code invokedynamic} instructions in bytecode. Hence, Dynalink is typically
* used as part of language runtimes that compile programs into Java
* {@code .class} bytecode format. Dynalink does not address the aspects of
* either creating bytecode classes or loading them into the JVM. That said,
* Dynalink can also be used without bytecode compilation (e.g. in language
* interpreters) by creating {@code CallSite} objects explicitly and associating
* them with representations of dynamic operations in the interpreted program
* (e.g. a typical representation would be some node objects in a syntax tree).
* <h2>Available operations</h2>
* Dynalink defines several standard operations in its
* {@link jdk.dynalink.StandardOperation} class. The linker for Java
* objects can link all of these operations, and you are encouraged to at
* minimum support and use these operations in your language too. The
* standard operations {@code GET} and {@code SET} need to be combined with
* at least one {@link jdk.dynalink.Namespace} to be useful, e.g. to express a
* property getter, you'd use {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY)}.
* Dynalink defines three standard namespaces in the {@link jdk.dynalink.StandardNamespace} class.
* To associate a fixed name with an operation, you can use
* {@link jdk.dynalink.NamedOperation} as in the previous example:
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}
* expresses a getter for the property named "color".
* <h2>Operations on multiple namespaces</h2>
* Some languages might not have separate namespaces on objects for
* properties, elements, and methods, and a source language construct might
* address several of them at once. Dynalink supports specifying multiple
* {@link jdk.dynalink.Namespace} objects with {@link jdk.dynalink.NamespaceOperation}.
* <h2>Language-specific linkers</h2>
* Languages that define their own object model different than the JVM
* class-based model and/or use their own type conversions will need to create
* their own language-specific linkers. See the {@link jdk.dynalink.linker}
* package and specifically the {@link jdk.dynalink.linker.GuardingDynamicLinker}
* interface to get started.
* <h2>Dynalink and Java objects</h2>
* The {@code DynamicLinker} objects created by {@code DynamicLinkerFactory} by
* default contain an internal instance of
* {@code BeansLinker}, which is a language-specific linker
* that implements the usual Java semantics for all of the above operations and
* can link any Java object that no other language-specific linker has managed
* to link. This way, all language runtimes have built-in interoperability with
* ordinary Java objects. See {@link jdk.dynalink.beans.BeansLinker} for details
* on how it links the various operations.
* <h2>Cross-language interoperability</h2>
* A {@code DynamicLinkerFactory} can be configured with a
* {@link jdk.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class
* loader}. It will try to instantiate all
* {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to
* that class loader and compose the linkers they provide into the
* {@code DynamicLinker} it creates. This allows for interoperability between
* languages: if you have two language runtimes A and B deployed in your JVM and
* they export their linkers through the above mechanism, language runtime A
* will have a language-specific linker instance from B and vice versa inside
* their {@code DynamicLinker} objects. This means that if an object from
* language runtime B gets passed to code from language runtime A, the linker
* from B will get a chance to link the call site in A when it encounters the
* object from B.
* Contains interfaces and classes that are used to link an {@code invokedynamic} call site.
*/
package jdk.dynalink;

@ -24,7 +24,198 @@
*/
/**
* Dynalink
* <p>
* Dynalink is a library for dynamic linking of high-level operations on objects.
* These operations include "read a property",
* "write a property", "invoke a function" and so on. Dynalink is primarily
* useful for implementing programming languages where at least some expressions
* have dynamic types (that is, types that can not be decided statically), and
* the operations on dynamic types are expressed as
* {@link java.lang.invoke.CallSite call sites}. These call sites will be
* linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}
* at run time based on actual types of the values the expressions evaluated to.
* These can change between invocations, necessitating relinking the call site
* multiple times to accommodate new types; Dynalink handles all that and more.
* <p>
* Dynalink supports implementation of programming languages with object models
* that differ (even radically) from the JVM's class-based model and have their
* custom type conversions.
* <p>
* Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
* package.
* <p>
*
* While {@link java.lang.invoke} provides a low level API for dynamic linking
* of {@code invokedynamic} call sites, it does not provide a way to express
* higher level operations on objects, nor methods that implement them. These
* operations are the usual ones in object-oriented environments: property
* access, access of elements of collections, invocation of methods and
* constructors (potentially with multiple dispatch, e.g. link- and run-time
* equivalents of Java overloaded method resolution). These are all functions
* that are normally desired in a language on the JVM. If a language is
* statically typed and its type system matches that of the JVM, it can
* accomplish this with use of the usual invocation, field access, etc.
* instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the
* language is dynamic (hence, types of some expressions are not known until
* evaluated at run time), or its object model or type system don't match
* closely that of the JVM, then it should use {@code invokedynamic} call sites
* instead and let Dynalink manage them.
* <h2>Example</h2>
* Dynalink is probably best explained by an example showing its use. Let's
* suppose you have a program in a language where you don't have to declare the
* type of an object and you want to access a property on it:
* <pre>
* var color = obj.color;
* </pre>
* If you generated a Java class to represent the above one-line program, its
* bytecode would look something like this:
* <pre>
* aload 2 // load "obj" on stack
* invokedynamic "GET:PROPERTY:color"(Object)Object // invoke property getter on object of unknown type
* astore 3 // store the return value into local variable "color"
* </pre>
* In order to link the {@code invokedynamic} instruction, we need a bootstrap
* method. A minimalist bootstrap method with Dynalink could look like this:
* <pre>
* import java.lang.invoke.*;
* import jdk.dynalink.*;
* import jdk.dynalink.support.*;
*
* class MyLanguageRuntime {
* private static final DynamicLinker dynamicLinker = new DynamicLinkerFactory().createLinker();
*
* public static CallSite bootstrap(MethodHandles.Lookup lookup, String name, MethodType type) {
* return dynamicLinker.link(
* new SimpleRelinkableCallSite(
* new CallSiteDescriptor(lookup, parseOperation(name), type)));
* }
*
* private static Operation parseOperation(String name) {
* ...
* }
* }
* </pre>
* There are several objects of significance in the above code snippet:
* <ul>
* <li>{@link jdk.dynalink.DynamicLinker} is the main object in Dynalink, it
* coordinates the linking of call sites to method handles that implement the
* operations named in them. It is configured and created using a
* {@link jdk.dynalink.DynamicLinkerFactory}.</li>
* <li>When the bootstrap method is invoked, it needs to create a
* {@link java.lang.invoke.CallSite} object. In Dynalink, these call sites need
* to additionally implement the {@link jdk.dynalink.RelinkableCallSite}
* interface. "Relinkable" here alludes to the fact that if the call site
* encounters objects of different types at run time, its target will be changed
* to a method handle that can perform the operation on the newly encountered
* type. {@link jdk.dynalink.support.SimpleRelinkableCallSite} and
* {@link jdk.dynalink.support.ChainedCallSite} (not used in the above example)
* are two implementations already provided by the library.</li>
* <li>Dynalink uses {@link jdk.dynalink.CallSiteDescriptor} objects to
* preserve the parameters to the bootstrap method: the lookup and the method type,
* as it will need them whenever it needs to relink a call site.</li>
* <li>Dynalink uses {@link jdk.dynalink.Operation} objects to express
* dynamic operations. It does not prescribe how would you encode the operations
* in your call site, though. That is why in the above example the
* {@code parseOperation} function is left empty, and you would be expected to
* provide the code to parse the string {@code "GET:PROPERTY:color"}
* in the call site's name into a named property getter operation object as
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}.
* </ul>
* <p>What can you already do with the above setup? {@code DynamicLinkerFactory}
* by default creates a {@code DynamicLinker} that can link Java objects with the
* usual Java semantics. If you have these three simple classes:
* <pre>
* public class A {
* public String color;
* public A(String color) { this.color = color; }
* }
*
* public class B {
* private String color;
* public B(String color) { this.color = color; }
* public String getColor() { return color; }
* }
*
* public class C {
* private int color;
* public C(int color) { this.color = color; }
* public int getColor() { return color; }
* }
* </pre>
* and you somehow create their instances and pass them to your call site in your
* programming language:
* <pre>
* for each(var obj in [new A("red"), new B("green"), new C(0x0000ff)]) {
* print(obj.color);
* }
* </pre>
* then on first invocation, Dynalink will link the {@code .color} getter
* operation to a field getter for {@code A.color}, on second invocation it will
* relink it to {@code B.getColor()} returning a {@code String}, and finally on
* third invocation it will relink it to {@code C.getColor()} returning an {@code int}.
* The {@code SimpleRelinkableCallSite} we used above only remembers the linkage
* for the last encountered type (it implements what is known as a <i>monomorphic
* inline cache</i>). Another already provided implementation,
* {@link jdk.dynalink.support.ChainedCallSite} will remember linkages for
* several different types (it is a <i>polymorphic inline cache</i>) and is
* probably a better choice in serious applications.
* <h2>Dynalink and bytecode creation</h2>
* {@code CallSite} objects are usually created as part of bootstrapping
* {@code invokedynamic} instructions in bytecode. Hence, Dynalink is typically
* used as part of language runtimes that compile programs into Java
* {@code .class} bytecode format. Dynalink does not address the aspects of
* either creating bytecode classes or loading them into the JVM. That said,
* Dynalink can also be used without bytecode compilation (e.g. in language
* interpreters) by creating {@code CallSite} objects explicitly and associating
* them with representations of dynamic operations in the interpreted program
* (e.g. a typical representation would be some node objects in a syntax tree).
* <h2>Available operations</h2>
* Dynalink defines several standard operations in its
* {@link jdk.dynalink.StandardOperation} class. The linker for Java
* objects can link all of these operations, and you are encouraged to at
* minimum support and use these operations in your language too. The
* standard operations {@code GET} and {@code SET} need to be combined with
* at least one {@link jdk.dynalink.Namespace} to be useful, e.g. to express a
* property getter, you'd use {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY)}.
* Dynalink defines three standard namespaces in the {@link jdk.dynalink.StandardNamespace} class.
* To associate a fixed name with an operation, you can use
* {@link jdk.dynalink.NamedOperation} as in the previous example:
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}
* expresses a getter for the property named "color".
* <h2>Operations on multiple namespaces</h2>
* Some languages might not have separate namespaces on objects for
* properties, elements, and methods, and a source language construct might
* address several of them at once. Dynalink supports specifying multiple
* {@link jdk.dynalink.Namespace} objects with {@link jdk.dynalink.NamespaceOperation}.
* <h2>Language-specific linkers</h2>
* Languages that define their own object model different than the JVM
* class-based model and/or use their own type conversions will need to create
* their own language-specific linkers. See the {@link jdk.dynalink.linker}
* package and specifically the {@link jdk.dynalink.linker.GuardingDynamicLinker}
* interface to get started.
* <h2>Dynalink and Java objects</h2>
* The {@code DynamicLinker} objects created by {@code DynamicLinkerFactory} by
* default contain an internal instance of
* {@code BeansLinker}, which is a language-specific linker
* that implements the usual Java semantics for all of the above operations and
* can link any Java object that no other language-specific linker has managed
* to link. This way, all language runtimes have built-in interoperability with
* ordinary Java objects. See {@link jdk.dynalink.beans.BeansLinker} for details
* on how it links the various operations.
* <h2>Cross-language interoperability</h2>
* A {@code DynamicLinkerFactory} can be configured with a
* {@link jdk.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class
* loader}. It will try to instantiate all
* {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to
* that class loader and compose the linkers they provide into the
* {@code DynamicLinker} it creates. This allows for interoperability between
* languages: if you have two language runtimes A and B deployed in your JVM and
* they export their linkers through the above mechanism, language runtime A
* will have a language-specific linker instance from B and vice versa inside
* their {@code DynamicLinker} objects. This means that if an object from
* language runtime B gets passed to code from language runtime A, the linker
* from B will get a chance to link the call site in A when it encounters the
* object from B.
*/
module jdk.dynalink {
requires java.logging;

@ -24,7 +24,71 @@
*/
/**
* Nashorn
<p>
Nashorn is a runtime environment for programs written in ECMAScript 5.1.
</p>
<h1>Usage</h1>
The recommended way to use Nashorn is through the <a href="http://jcp.org/en/jsr/detail?id=223" target="_top">JSR-223
"Scripting for the Java Platform"</a> APIs found in the {@link javax.script} package. Usually, you'll obtain a
{@link javax.script.ScriptEngine} instance for Nashorn using:
<pre>
import javax.script.*;
...
ScriptEngine nashornEngine = new ScriptEngineManager().getEngineByName("nashorn");
</pre>
and then use it just as you would any other JSR-223 script engine. See
<a href="jdk/nashorn/api/scripting/package-summary.html">{@code jdk.nashorn.api.scripting}</a> package
for details.
<h1>Compatibility</h1>
Nashorn is 100% compliant with the <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm"
target="_top">ECMA-262 Standard, Edition 5.1</a>. It requires a Java Virtual Machine that implements the
<a href="http://jcp.org/en/jsr/detail?id=292" target="_top">JSR-292 "Supporting Dynamically Typed Languages on the Java
Platform"</a> specification (often referred to as "invokedynamic"), as well as the already mentioned JSR-223.
<h1>Interoperability with the Java platform</h1>
In addition to being a 100% ECMAScript 5.1 runtime, Nashorn provides features for interoperability of the ECMAScript
programs with the Java platform. In general, any Java object put into the script engine's context will be visible from
the script. In terms of the standard, such Java objects are not considered "native objects", but rather "host objects",
as defined in section 4.3.8. This distinction allows certain semantical differences in handling them compared to native
objects. For most purposes, Java objects behave just as native objects do: you can invoke their methods, get and set
their properties. In most cases, though, you can't add arbitrary properties to them, nor can you remove existing
properties.
<h2>Java collection handling</h2>
Native Java arrays and {@link java.util.List}s support indexed access to their elements through the property accessors,
and {@link java.util.Map}s support both property and element access through both dot and square-bracket property
accessors, with the difference being that dot operator gives precedence to object properties (its fields and properties
defined as {@code getXxx} and {@code setXxx} methods) while the square bracket operator gives precedence to map
elements. Native Java arrays expose the {@code length} property.
<h2>ECMAScript primitive types</h2>
ECMAScript primitive types for number, string, and boolean are represented with {@link java.lang.Number},
{@link java.lang.CharSequence}, and {@link java.lang.Boolean} objects. While the most often used number type is
{@link java.lang.Double} and the most often used string type is {@link java.lang.String}, don't rely on it as various
internal optimizations cause other subclasses of {@code Number} and internal implementations of {@code CharSequence} to
be used.
<h2>Type conversions</h2>
When a method on a Java object is invoked, the arguments are converted to the formal parameter types of the Java method
using all allowed ECMAScript conversions. This can be surprising, as in general, conversions from string to number will
succeed according to Standard's section 9.3 "ToNumber" and so on; string to boolean, number to boolean, Object to
number, Object to string all work. Note that if the Java method's declared parameter type is {@code java.lang.Object},
Nashorn objects are passed without any conversion whatsoever; specifically if the JavaScript value being passed is of
primitive string type, you can only rely on it being a {@code java.lang.CharSequence}, and if the value is a number, you
can only rely on it being a {@code java.lang.Number}. If the Java method declared parameter type is more specific (e.g.
{@code java.lang.String} or {@code java.lang.Double}), then Nashorn will of course ensure the required type is passed.
<h2>SAM types</h2>
As a special extension when invoking Java methods, ECMAScript function objects can be passed in place of an argument
whose Java type is so-called "single abstract method" or "SAM" type. While this name usually covers single-method
interfaces, Nashorn is a bit more versatile, and it recognizes a type as a SAM type if all its abstract methods are
overloads of the same name, and it is either an interface, or it is an abstract class with
a no-arg constructor. The type itself must be public, while the constructor and the methods can be either public or
protected. If there are multiple abstract overloads of the same name, the single function will serve as the shared
implementation for all of them, <em>and additionally it will also override any non-abstract methods of the same name</em>.
This is done to be consistent with the fact that ECMAScript does not have the concept of overloaded methods.
<h2>The {@code Java} object</h2>
Nashorn exposes a non-standard global object named {@code Java} that is the primary API entry point into Java
platform-specific functionality. You can use it to create instances of Java classes, convert from Java arrays to native
arrays and back, and so on.
<h2>Other non-standard built-in objects</h2>
In addition to {@code Java}, Nashorn also exposes some other non-standard built-in objects:
{@code JSAdapter}, {@code JavaImporter}, {@code Packages}
*/
module jdk.scripting.nashorn {
requires java.logging;
@ -47,4 +111,3 @@ module jdk.scripting.nashorn {
provides jdk.dynalink.linker.GuardingDynamicLinkerExporter
with jdk.nashorn.api.linker.NashornLinkerExporter;
}

@ -1,113 +0,0 @@
<!--
Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<body>
<p>
Nashorn is a runtime environment for programs written in ECMAScript 5.1.
</p>
<h1>Usage</h1>
<p>
The recommended way to use Nashorn is through the <a href="http://jcp.org/en/jsr/detail?id=223" target="_top">JSR-223
"Scripting for the Java Platform"</a> APIs found in the {@link javax.script} package. Usually, you'll obtain a
{@link javax.script.ScriptEngine} instance for Nashorn using:
<pre>
import javax.script.*;
...
ScriptEngine nashornEngine = new ScriptEngineManager().getEngineByName("nashorn");
</pre>
and then use it just as you would any other JSR-223 script engine. See
<a href="jdk/nashorn/api/scripting/package-summary.html">{@code jdk.nashorn.api.scripting}</a> package
for details.
<p>
<h1>Compatibility</h1>
Nashorn is 100% compliant with the <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm"
target="_top">ECMA-262 Standard, Edition 5.1</a>. It requires a Java Virtual Machine that implements the
<a href="http://jcp.org/en/jsr/detail?id=292" target="_top">JSR-292 "Supporting Dynamically Typed Languages on the Java
Platform"</a> specification (often referred to as "invokedynamic"), as well as the already mentioned JSR-223.
<h1>Interoperability with the Java platform</h1>
<p>
In addition to being a 100% ECMAScript 5.1 runtime, Nashorn provides features for interoperability of the ECMAScript
programs with the Java platform. In general, any Java object put into the script engine's context will be visible from
the script. In terms of the standard, such Java objects are not considered "native objects", but rather "host objects",
as defined in section 4.3.8. This distinction allows certain semantical differences in handling them compared to native
objects. For most purposes, Java objects behave just as native objects do: you can invoke their methods, get and set
their properties. In most cases, though, you can't add arbitrary properties to them, nor can you remove existing
properties.
<p>
<h2>Java collection handling</h2>
<p>
Native Java arrays and {@link java.util.List}s support indexed access to their elements through the property accessors,
and {@link java.util.Map}s support both property and element access through both dot and square-bracket property
accessors, with the difference being that dot operator gives precedence to object properties (its fields and properties
defined as {@code getXxx} and {@code setXxx} methods) while the square bracket operator gives precedence to map
elements. Native Java arrays expose the {@code length} property.
<p>
<h2>ECMAScript primitive types</h2>
<p>
ECMAScript primitive types for number, string, and boolean are represented with {@link java.lang.Number},
{@link java.lang.CharSequence}, and {@link java.lang.Boolean} objects. While the most often used number type is
{@link java.lang.Double} and the most often used string type is {@link java.lang.String}, don't rely on it as various
internal optimizations cause other subclasses of {@code Number} and internal implementations of {@code CharSequence} to
be used.
<p>
<h2>Type conversions</h2>
<p>
When a method on a Java object is invoked, the arguments are converted to the formal parameter types of the Java method
using all allowed ECMAScript conversions. This can be surprising, as in general, conversions from string to number will
succeed according to Standard's section 9.3 "ToNumber" and so on; string to boolean, number to boolean, Object to
number, Object to string all work. Note that if the Java method's declared parameter type is {@code java.lang.Object},
Nashorn objects are passed without any conversion whatsoever; specifically if the JavaScript value being passed is of
primitive string type, you can only rely on it being a {@code java.lang.CharSequence}, and if the value is a number, you
can only rely on it being a {@code java.lang.Number}. If the Java method declared parameter type is more specific (e.g.
{@code java.lang.String} or {@code java.lang.Double}), then Nashorn will of course ensure the required type is passed.
<p>
<h2>SAM types</h2>
<p>
As a special extension when invoking Java methods, ECMAScript function objects can be passed in place of an argument
whose Java type is so-called "single abstract method" or "SAM" type. While this name usually covers single-method
interfaces, Nashorn is a bit more versatile, and it recognizes a type as a SAM type if all its abstract methods are
overloads of the same name, and it is either an interface, or it is an abstract class with
a no-arg constructor. The type itself must be public, while the constructor and the methods can be either public or
protected. If there are multiple abstract overloads of the same name, the single function will serve as the shared
implementation for all of them, <em>and additionally it will also override any non-abstract methods of the same name</em>.
This is done to be consistent with the fact that ECMAScript does not have the concept of overloaded methods.
<p>
<h2>The {@code Java} object</h2>
Nashorn exposes a non-standard global object named {@code Java} that is the primary API entry point into Java
platform-specific functionality. You can use it to create instances of Java classes, convert from Java arrays to native
arrays and back, and so on. The methods on the objects are directly implemented by public static methods on the class
<a href="jdk/nashorn/internal/objects/NativeJava.html">{@code NativeJava}</a>, see that class for details on what
functionality is available.
<h2>Representations of Java types</h2>
The method <a href="jdk/nashorn/internal/objects/NativeJava.html#type(java.lang.Object,%20java.lang.Object)">
{@code Java.type(typeName)}</a> takes a name of a type, and returns an object representing a Java type. You can
use that object to both create new instances of Java classes, as well as to access static fields and methods on them.
The type object is distinct from the {@code java.lang.Class} object, which represents the reflective run-time type
identity and doesn't carry i.e. static members. Again, see the link for {@code NativeJava} above for details.
<h2>Other non-standard built-in objects</h2>
In addition to {@code Java}, Nashorn also exposes some other non-standard built-in objects:
<a href="jdk/nashorn/internal/objects/NativeJSAdapter.html">{@code JSAdapter}</a>,
<a href="jdk/nashorn/internal/objects/NativeJavaImporter.html">{@code JavaImporter}</a>,
<a href="jdk/nashorn/internal/runtime/NativeJavaPackage.html">{@code Packages}.</a>
</body>