       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>
      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  * <h1>Compatibility</h1>
      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  * <h1>Interoperability with the Java platform</h1>
      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  * <h2>Java collection handling</h2>
      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  * <h2>ECMAScript primitive types</h2>
      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  * <h2>Type conversions</h2>
      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  * <h2>SAM types</h2>
     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  * <h2>The {@code Java} object</h2>
     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  * <h2>Other non-standard built-in objects</h2>
     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  * @provides javax.script.ScriptEngineFactory
     139  * @moduleGraph
     140  * @since 9
     141  */

     142 module jdk.scripting.nashorn {
     143     requires java.logging;
     144     requires jdk.dynalink;
     145
     146     requires transitive java.scripting;
     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 with
     159         jdk.nashorn.api.scripting.NashornScriptEngineFactory;
     160
     161     provides jdk.dynalink.linker.GuardingDynamicLinkerExporter with
     162         jdk.nashorn.api.linker.NashornLinkerExporter;
     163 }
    --- EOF ---