module-info.java revision 1917:734b3209b6ed
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 * <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> 41import javax.script.*; 42... 43ScriptEngine 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 */ 143module jdk.scripting.nashorn { 144 requires java.logging; 145 requires jdk.dynalink; 146 147 requires transitive java.scripting; 148 149 exports jdk.nashorn.api.scripting; 150 exports jdk.nashorn.api.tree; 151 152 exports jdk.nashorn.internal.runtime to 153 jdk.scripting.nashorn.shell; 154 exports jdk.nashorn.internal.objects to 155 jdk.scripting.nashorn.shell; 156 exports jdk.nashorn.tools to 157 jdk.scripting.nashorn.shell; 158 159 provides javax.script.ScriptEngineFactory with 160 jdk.nashorn.api.scripting.NashornScriptEngineFactory; 161 162 provides jdk.dynalink.linker.GuardingDynamicLinkerExporter with 163 jdk.nashorn.api.linker.NashornLinkerExporter; 164} 165