7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 <p> 28 Nashorn is a runtime environment for programs written in ECMAScript 5.1. 29 </p> 30 <h1>Usage</h1> 31 The recommended way to use Nashorn is through the <a href="http://jcp.org/en/jsr/detail?id=223" target="_top">JSR-223 32 "Scripting for the Java Platform"</a> APIs found in the {@link javax.script} package. Usually, you'll obtain a 33 {@link javax.script.ScriptEngine} instance for Nashorn using: 34 <pre> 35 import javax.script.*; 36 ... 37 ScriptEngine nashornEngine = new ScriptEngineManager().getEngineByName("nashorn"); 38 </pre> 39 and then use it just as you would any other JSR-223 script engine. See 40 <a href="jdk/nashorn/api/scripting/package-summary.html">{@code jdk.nashorn.api.scripting}</a> package 41 for details. 42 <h1>Compatibility</h1> 43 Nashorn is 100% compliant with the <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm" 44 target="_top">ECMA-262 Standard, Edition 5.1</a>. It requires a Java Virtual Machine that implements the 45 <a href="http://jcp.org/en/jsr/detail?id=292" target="_top">JSR-292 "Supporting Dynamically Typed Languages on the Java 46 Platform"</a> specification (often referred to as "invokedynamic"), as well as the already mentioned JSR-223. 47 <h1>Interoperability with the Java platform</h1> 48 In addition to being a 100% ECMAScript 5.1 runtime, Nashorn provides features for interoperability of the ECMAScript 49 programs with the Java platform. In general, any Java object put into the script engine's context will be visible from 50 the script. In terms of the standard, such Java objects are not considered "native objects", but rather "host objects", 51 as defined in section 4.3.8. This distinction allows certain semantical differences in handling them compared to native 52 objects. For most purposes, Java objects behave just as native objects do: you can invoke their methods, get and set 53 their properties. In most cases, though, you can't add arbitrary properties to them, nor can you remove existing 54 properties. 55 <h2>Java collection handling</h2> 56 Native Java arrays and {@link java.util.List}s support indexed access to their elements through the property accessors, 57 and {@link java.util.Map}s support both property and element access through both dot and square-bracket property 58 accessors, with the difference being that dot operator gives precedence to object properties (its fields and properties 59 defined as {@code getXxx} and {@code setXxx} methods) while the square bracket operator gives precedence to map 60 elements. Native Java arrays expose the {@code length} property. 61 <h2>ECMAScript primitive types</h2> 62 ECMAScript primitive types for number, string, and boolean are represented with {@link java.lang.Number}, 63 {@link java.lang.CharSequence}, and {@link java.lang.Boolean} objects. While the most often used number type is 64 {@link java.lang.Double} and the most often used string type is {@link java.lang.String}, don't rely on it as various 65 internal optimizations cause other subclasses of {@code Number} and internal implementations of {@code CharSequence} to 66 be used. 67 <h2>Type conversions</h2> 68 When a method on a Java object is invoked, the arguments are converted to the formal parameter types of the Java method 69 using all allowed ECMAScript conversions. This can be surprising, as in general, conversions from string to number will 70 succeed according to Standard's section 9.3 "ToNumber" and so on; string to boolean, number to boolean, Object to 71 number, Object to string all work. Note that if the Java method's declared parameter type is {@code java.lang.Object}, 72 Nashorn objects are passed without any conversion whatsoever; specifically if the JavaScript value being passed is of 73 primitive string type, you can only rely on it being a {@code java.lang.CharSequence}, and if the value is a number, you 74 can only rely on it being a {@code java.lang.Number}. If the Java method declared parameter type is more specific (e.g. 75 {@code java.lang.String} or {@code java.lang.Double}), then Nashorn will of course ensure the required type is passed. 76 <h2>SAM types</h2> 77 As a special extension when invoking Java methods, ECMAScript function objects can be passed in place of an argument 78 whose Java type is so-called "single abstract method" or "SAM" type. While this name usually covers single-method 79 interfaces, Nashorn is a bit more versatile, and it recognizes a type as a SAM type if all its abstract methods are 80 overloads of the same name, and it is either an interface, or it is an abstract class with 81 a no-arg constructor. The type itself must be public, while the constructor and the methods can be either public or 82 protected. If there are multiple abstract overloads of the same name, the single function will serve as the shared 83 implementation for all of them, <em>and additionally it will also override any non-abstract methods of the same name</em>. 84 This is done to be consistent with the fact that ECMAScript does not have the concept of overloaded methods. 85 <h2>The {@code Java} object</h2> 86 Nashorn exposes a non-standard global object named {@code Java} that is the primary API entry point into Java 87 platform-specific functionality. You can use it to create instances of Java classes, convert from Java arrays to native 88 arrays and back, and so on. 89 <h2>Other non-standard built-in objects</h2> 90 In addition to {@code Java}, Nashorn also exposes some other non-standard built-in objects: 91 {@code JSAdapter}, {@code JavaImporter}, {@code Packages} 92 93 @moduleGraph 94 @since 9 95 */ 96 module jdk.scripting.nashorn { 97 requires java.logging; 98 requires transitive java.scripting; 99 requires jdk.dynalink; 100 101 exports jdk.nashorn.api.scripting; 102 exports jdk.nashorn.api.tree; 103 104 exports jdk.nashorn.internal.runtime to 105 jdk.scripting.nashorn.shell; 106 exports jdk.nashorn.internal.objects to 107 jdk.scripting.nashorn.shell; 108 exports jdk.nashorn.tools to 109 jdk.scripting.nashorn.shell; 110 111 provides javax.script.ScriptEngineFactory 112 with jdk.nashorn.api.scripting.NashornScriptEngineFactory; 113 114 provides jdk.dynalink.linker.GuardingDynamicLinkerExporter | 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * Provides the implementation of Nashorn script engine and 28 * the runtime environment for programs written in ECMAScript 5.1. 29 * <p> 30 * Nashorn is a runtime environment for programs written in ECMAScript 5.1. 31 * </p> 32 * 33 * <h1>Usage</h1> 34 * 35 * The recommended way to use Nashorn is through the 36 * <a href="http://jcp.org/en/jsr/detail?id=223" target="_top">JSR-223 37 * "Scripting for the Java Platform"</a> APIs found in the 38 * {@link javax.script} package. Usually, you'll obtain a 39 * {@link javax.script.ScriptEngine} instance for Nashorn using: 40 * <pre> 41 import javax.script.*; 42 ... 43 ScriptEngine nashornEngine = new ScriptEngineManager().getEngineByName("nashorn"); 44 </pre> 45 * 46 * and then use it just as you would any other JSR-223 script engine. See 47 * <a href="jdk/nashorn/api/scripting/package-summary.html"> 48 * {@code jdk.nashorn.api.scripting}</a> package for details. 49 * <h1>Compatibility</h1> 50 * Nashorn is 100% compliant with the 51 * <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm" 52 * target="_top">ECMA-262 Standard, Edition 5.1</a>. 53 * It requires a Java Virtual Machine that implements the 54 * <a href="http://jcp.org/en/jsr/detail?id=292" target="_top"> 55 * JSR-292 "Supporting Dynamically Typed Languages on the Java Platform"</a> 56 * specification (often referred to as "invokedynamic"), as well as 57 * the already mentioned JSR-223. 58 * 59 * <h1>Interoperability with the Java platform</h1> 60 * 61 * In addition to being a 100% ECMAScript 5.1 runtime, Nashorn provides features 62 * for interoperability of the ECMAScript programs with the Java platform. 63 * In general, any Java object put into the script engine's context will be 64 * visible from the script. In terms of the standard, such Java objects are not 65 * considered "native objects", but rather "host objects", as defined in 66 * section 4.3.8. This distinction allows certain semantical differences 67 * in handling them compared to native objects. For most purposes, Java objects 68 * behave just as native objects do: you can invoke their methods, get and set 69 * their properties. In most cases, though, you can't add arbitrary properties 70 * to them, nor can you remove existing properties. 71 * 72 * <h2>Java collection handling</h2> 73 * 74 * Native Java arrays and {@link java.util.List}s support indexed access to 75 * their elements through the property accessors, and {@link java.util.Map}s 76 * support both property and element access through both dot and square-bracket 77 * property accessors, with the difference being that dot operator gives 78 * precedence to object properties (its fields and properties defined as 79 * {@code getXxx} and {@code setXxx} methods) while the square bracket 80 * operator gives precedence to map elements. Native Java arrays expose 81 * the {@code length} property. 82 * 83 * <h2>ECMAScript primitive types</h2> 84 * 85 * ECMAScript primitive types for number, string, and boolean are represented 86 * with {@link java.lang.Number}, {@link java.lang.CharSequence}, and 87 * {@link java.lang.Boolean} objects. While the most often used number type 88 * is {@link java.lang.Double} and the most often used string type is 89 * {@link java.lang.String}, don't rely on it as various internal optimizations 90 * cause other subclasses of {@code Number} and internal implementations of 91 * {@code CharSequence} to be used. 92 * 93 * <h2>Type conversions</h2> 94 * 95 * When a method on a Java object is invoked, the arguments are converted to 96 * the formal parameter types of the Java method using all allowed ECMAScript 97 * conversions. This can be surprising, as in general, conversions from string 98 * to number will succeed according to Standard's section 9.3 "ToNumber" 99 * and so on; string to boolean, number to boolean, Object to number, 100 * Object to string all work. Note that if the Java method's declared parameter 101 * type is {@code java.lang.Object}, Nashorn objects are passed without any 102 * conversion whatsoever; specifically if the JavaScript value being passed 103 * is of primitive string type, you can only rely on it being a 104 * {@code java.lang.CharSequence}, and if the value is a number, you can only 105 * rely on it being a {@code java.lang.Number}. If the Java method declared 106 * parameter type is more specific (e.g. {@code java.lang.String} or 107 * {@code java.lang.Double}), then Nashorn will of course ensure 108 * the required type is passed. 109 * 110 * <h2>SAM types</h2> 111 * 112 * As a special extension when invoking Java methods, ECMAScript function 113 * objects can be passed in place of an argument whose Java type is so-called 114 * "single abstract method" or "SAM" type. While this name usually covers 115 * single-method interfaces, Nashorn is a bit more versatile, and it 116 * recognizes a type as a SAM type if all its abstract methods are 117 * overloads of the same name, and it is either an interface, or it is an 118 * abstract class with a no-arg constructor. The type itself must be public, 119 * while the constructor and the methods can be either public or protected. 120 * If there are multiple abstract overloads of the same name, the single 121 * function will serve as the shared implementation for all of them, 122 * <em>and additionally it will also override any non-abstract methods of 123 * the same name</em>. This is done to be consistent with the fact that 124 * ECMAScript does not have the concept of overloaded methods. 125 * 126 * <h2>The {@code Java} object</h2> 127 * 128 * Nashorn exposes a non-standard global object named {@code Java} that is 129 * the primary API entry point into Java platform-specific functionality. 130 * You can use it to create instances of Java classes, convert from Java arrays 131 * to native arrays and back, and so on. 132 * 133 * <h2>Other non-standard built-in objects</h2> 134 * 135 * In addition to {@code Java}, Nashorn also exposes some other 136 * non-standard built-in objects: 137 * {@code JSAdapter}, {@code JavaImporter}, {@code Packages} 138 * 139 * @provides javax.script.ScriptEngineFactory 140 * @moduleGraph 141 * @since 9 142 */ 143 module jdk.scripting.nashorn { 144 requires java.logging; 145 requires transitive java.scripting; 146 requires jdk.dynalink; 147 148 exports jdk.nashorn.api.scripting; 149 exports jdk.nashorn.api.tree; 150 151 exports jdk.nashorn.internal.runtime to 152 jdk.scripting.nashorn.shell; 153 exports jdk.nashorn.internal.objects to 154 jdk.scripting.nashorn.shell; 155 exports jdk.nashorn.tools to 156 jdk.scripting.nashorn.shell; 157 158 provides javax.script.ScriptEngineFactory 159 with jdk.nashorn.api.scripting.NashornScriptEngineFactory; 160 161 provides jdk.dynalink.linker.GuardingDynamicLinkerExporter |