internal/objects/NativeJava.java

8  * particular file as subject to the "Classpath" exception as provided
18  * 2 along with this work; if not, write to the Free Software Foundation,
61  * This class is the implementation for the {@code Java} global object exposed to programs running under Nashorn. This
62  * object acts as the API entry point to Java platform specific functionality, dealing with creating new instances of
163      * used to represent Java types in Nashorn is not {@link java.lang.Class} but rather {@link StaticClass}. They are
164      * the objects that you can use with the {@code new} operator to create new instances of the class as well as to
166      * treated specially. Instead of them, {@link StaticClass} instances - which we sometimes refer to as "Java type
169      * different expression (e.g. {@code java.io.File}) as an argument in "new" and to address statics, and it is
181      * Note that the name of the type is always a string for a fully qualified name. You can use any of these types to
201      * both work. Note however that using the dollar sign is faster, as Java.type first tries to resolve the class name
203      * dot, Java.type will internally get a ClassNotFoundException and subsequently retry by changing the last dot to
207      * alternative way to access the inner class is as a property of the outer class:
213      * You can access both static and non-static inner classes. If you want to create an instance of a non-static
214      * inner class, remember to pass an instance of its outer class as the first argument to the constructor.
218      * applicable to any of its public or protected constructors, but inserting a JavaScript object with functions
227      * Nashorn supports a syntactic extension where a "new" expression followed by an argument is identical to
228      * invoking the constructor and passing the argument to it, so you can write the above example also as:
238      * which is very similar to Java anonymous inner class definition. On the other hand, if the type is an abstract
239      * type with a single abstract method (commonly referred to as a "SAM type") or all abstract methods it has share
241      * become even more simplified to:
247      * Note that in every one of these cases if you are trying to instantiate an abstract class that has constructors
260      * {@code TimerTask} subclass and uses the passed function to implement its only abstract method, {@code run()}. In
265      * You can also subclass non-abstract classes; for that you will need to use the {@link #extend(Object, Object...)}
276      * Actually, you can even assign static methods to variables, so the above example can be rewritten as:
283      * If you need to access the actual {@code java.lang.Class} object for the type, you can use the {@code class}
292      * {@code java.lang.Class} object to retrieve its type-representing object:
298      * The standard ECMAScript {@code instanceof} operator is extended to recognize Java objects and their type objects:
307      * types to obtain representations of them, and you can use trailing square brackets to represent Java array types.
352      * var javaIntArray = Java.to(anArray, "int[]")
354      * print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion
355      * print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion
360      * object to create. Can not be null. If undefined, a "default" conversion is presumed (allowing the argument to be
362      * @return a Java object whose value corresponds to the original script object's value. Specifically, for array
363      * target types, returns a Java array of the same type with contents converted to the array's component type.
370     public static Object to(final Object self, final Object obj, final Object objType) throws ClassNotFoundException {
407         throw typeError("unsupported.java.to.type", targetClass.getName());
413      * need to have an actual JavaScript native array (e.g. to work with the array comprehensions functions), you will
414      * want to use this method. Example:
454         throw typeError("cant.convert.to.javascript.array", objArray.getClass().getName());
547             // The logic below compensates for a frequent user error - when people use dot notation to separate inner
575      * that acts as a script-to-Java adapter for it. See {@link #type(Object, Object)} for a discussion of type objects,
576      * and see {@link JavaAdapterFactory} for details on script-to-Java adapters. Note that you can also implement
578      * class. However, to extend a non-abstract class, you will have to use this method. Example:
598      * the same extender type. It's a generic adapter that delegates to whatever JavaScript functions its implementation
601      * must be prepared to deal with all overloads.</li>
604      * <li>It is also possible to specify an ordinary JavaScript object as the last argument to {@code extend}. In that
607      * argument to their constructor. Example:
620      * As you can see, you don't have to pass any object when you create a new instance of {@code R1} as its
621      * {@code run()} function was defined already when extending the class. If you also want to add instance-level
622      * overrides on these objects, you will have to repeatedly use {@code extend()} to subclass the class-level adapter.
631      * Note that you must use {@code Java.extend} to explicitly create an instance-override adapter class from a
638      * constructor. If more than one type is specified, at most one can be a class and the rest have to be interfaces.
643      * functionally identical; we deliberately don't want to incur the additional processing cost of canonicalizing type
648      * you can still pass a script object (or if it's a SAM type, a function) to the constructor to provide further
694      * When given an object created using {@code Java.extend()} or equivalent mechanism (that is, any JavaScript-to-Java
695      * adapter), returns an object that can be used to invoke superclass methods on that object. E.g.:
722      * @param obj the object to be exposed in a Java JSON library compatible manner.