1 /* 2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 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 * <h2>Usage</h2> 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 * {@link jdk.nashorn.api.scripting} package for details. 48 * <h2>Compatibility</h2> 49 * Nashorn is 100% compliant with the 50 * <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm" 51 * target="_top">ECMA-262 Standard, Edition 5.1</a>. 52 * It requires a Java Virtual Machine that implements the 53 * <a href="http://jcp.org/en/jsr/detail?id=292" target="_top"> 54 * JSR-292 "Supporting Dynamically Typed Languages on the Java Platform"</a> 55 * specification (often referred to as "invokedynamic"), as well as 56 * the already mentioned JSR-223. 57 * 58 * <h2>Interoperability with the Java platform</h2> 59 * 60 * In addition to being a 100% ECMAScript 5.1 runtime, Nashorn provides features 61 * for interoperability of the ECMAScript programs with the Java platform. 62 * In general, any Java object put into the script engine's context will be 63 * visible from the script. In terms of the standard, such Java objects are not 64 * considered "native objects", but rather "host objects", as defined in 65 * section 4.3.8. This distinction allows certain semantical differences 66 * in handling them compared to native objects. For most purposes, Java objects 67 * behave just as native objects do: you can invoke their methods, get and set 68 * their properties. In most cases, though, you can't add arbitrary properties 69 * to them, nor can you remove existing properties. 70 * 71 * <h3>Java collection handling</h3> 72 * 73 * Native Java arrays and {@link java.util.List}s support indexed access to 74 * their elements through the property accessors, and {@link java.util.Map}s 75 * support both property and element access through both dot and square-bracket 76 * property accessors, with the difference being that dot operator gives 77 * precedence to object properties (its fields and properties defined as 78 * {@code getXxx} and {@code setXxx} methods) while the square bracket 79 * operator gives precedence to map elements. Native Java arrays expose 80 * the {@code length} property. 81 * 82 * <h3>ECMAScript primitive types</h3> 83 * 84 * ECMAScript primitive types for number, string, and boolean are represented 85 * with {@link java.lang.Number}, {@link java.lang.CharSequence}, and 86 * {@link java.lang.Boolean} objects. While the most often used number type 87 * is {@link java.lang.Double} and the most often used string type is 88 * {@link java.lang.String}, don't rely on it as various internal optimizations 89 * cause other subclasses of {@code Number} and internal implementations of 90 * {@code CharSequence} to be used. 91 * 92 * <h3>Type conversions</h3> 93 * 94 * When a method on a Java object is invoked, the arguments are converted to 95 * the formal parameter types of the Java method using all allowed ECMAScript 96 * conversions. This can be surprising, as in general, conversions from string 97 * to number will succeed according to Standard's section 9.3 "ToNumber" 98 * and so on; string to boolean, number to boolean, Object to number, 99 * Object to string all work. Note that if the Java method's declared parameter 100 * type is {@code java.lang.Object}, Nashorn objects are passed without any 101 * conversion whatsoever; specifically if the JavaScript value being passed 102 * is of primitive string type, you can only rely on it being a 103 * {@code java.lang.CharSequence}, and if the value is a number, you can only 104 * rely on it being a {@code java.lang.Number}. If the Java method declared 105 * parameter type is more specific (e.g. {@code java.lang.String} or 106 * {@code java.lang.Double}), then Nashorn will of course ensure 107 * the required type is passed. 108 * 109 * <h3>SAM types</h3> 110 * 111 * As a special extension when invoking Java methods, ECMAScript function 112 * objects can be passed in place of an argument whose Java type is so-called 113 * "single abstract method" or "SAM" type. While this name usually covers 114 * single-method interfaces, Nashorn is a bit more versatile, and it 115 * recognizes a type as a SAM type if all its abstract methods are 116 * overloads of the same name, and it is either an interface, or it is an 117 * abstract class with a no-arg constructor. The type itself must be public, 118 * while the constructor and the methods can be either public or protected. 119 * If there are multiple abstract overloads of the same name, the single 120 * function will serve as the shared implementation for all of them, 121 * <em>and additionally it will also override any non-abstract methods of 122 * the same name</em>. This is done to be consistent with the fact that 123 * ECMAScript does not have the concept of overloaded methods. 124 * 125 * <h3>The {@code Java} object</h3> 126 * 127 * Nashorn exposes a non-standard global object named {@code Java} that is 128 * the primary API entry point into Java platform-specific functionality. 129 * You can use it to create instances of Java classes, convert from Java arrays 130 * to native arrays and back, and so on. 131 * 132 * <h3>Other non-standard built-in objects</h3> 133 * 134 * In addition to {@code Java}, Nashorn also exposes some other 135 * non-standard built-in objects: 136 * {@code JSAdapter}, {@code JavaImporter}, {@code Packages} 137 * 138 * @deprecated Nashorn JavaScript script engine and APIs, and the jjs tool 139 * are deprecated with the intent to remove them in a future release. 140 * 141 * @provides javax.script.ScriptEngineFactory 142 * @moduleGraph 143 * @since 9 144 */ 145 @Deprecated(since="11", forRemoval=true) 146 module jdk.scripting.nashorn { 147 requires java.logging; 148 requires jdk.dynalink; 149 150 requires transitive java.scripting; 151 152 exports jdk.nashorn.api.scripting; 153 exports jdk.nashorn.api.tree; 154 155 exports jdk.nashorn.internal.runtime to 156 jdk.scripting.nashorn.shell; 157 exports jdk.nashorn.internal.objects to 158 jdk.scripting.nashorn.shell; 159 exports jdk.nashorn.tools to 160 jdk.scripting.nashorn.shell; 161 162 provides javax.script.ScriptEngineFactory with 163 jdk.nashorn.api.scripting.NashornScriptEngineFactory; 164 165 provides jdk.dynalink.linker.GuardingDynamicLinkerExporter with 166 jdk.nashorn.api.linker.NashornLinkerExporter; 167 }