1 /*
2 * Copyright (c) 2010, 2013, 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 package jdk.nashorn.internal.runtime.linker;
27
28 import static jdk.nashorn.internal.codegen.CompilerConstants.staticCallNoLookup;
29
30 import java.lang.invoke.CallSite;
31 import java.lang.invoke.MethodHandle;
32 import java.lang.invoke.MethodHandles;
33 import java.lang.invoke.MethodHandles.Lookup;
34 import java.lang.invoke.MethodType;
35 import jdk.internal.dynalink.CallSiteDescriptor;
36 import jdk.internal.dynalink.DynamicLinker;
37 import jdk.internal.dynalink.DynamicLinkerFactory;
38 import jdk.internal.dynalink.beans.BeansLinker;
39 import jdk.internal.dynalink.beans.StaticClass;
40 import jdk.internal.dynalink.linker.GuardedInvocation;
41 import jdk.internal.dynalink.linker.LinkerServices;
42 import jdk.nashorn.api.scripting.JSObject;
43 import jdk.nashorn.internal.codegen.CompilerConstants.Call;
44 import jdk.nashorn.internal.codegen.RuntimeCallSite;
45 import jdk.nashorn.internal.runtime.JSType;
46 import jdk.nashorn.internal.runtime.ScriptFunction;
47 import jdk.nashorn.internal.runtime.ScriptRuntime;
48 import jdk.nashorn.internal.runtime.options.Options;
49
50 /**
51 * This class houses bootstrap method for invokedynamic instructions generated by compiler.
52 */
53 public final class Bootstrap {
54 /** Reference to the seed boostrap function */
55 public static final Call BOOTSTRAP = staticCallNoLookup(Bootstrap.class, "bootstrap", CallSite.class, Lookup.class, String.class, MethodType.class, int.class);
56
57 // do not create me!!
58 private Bootstrap() {
59 }
60
61 private static final DynamicLinker dynamicLinker;
62 static {
63 final DynamicLinkerFactory factory = new DynamicLinkerFactory();
64 factory.setPrioritizedLinkers(new NashornLinker(), new NashornPrimitiveLinker(), new NashornStaticClassLinker(),
65 new BoundDynamicMethodLinker(), new JavaSuperAdapterLinker(), new JSObjectLinker(), new ReflectionCheckLinker());
66 factory.setFallbackLinkers(new NashornBeansLinker(), new NashornBottomLinker());
67 factory.setSyncOnRelink(true);
68 final int relinkThreshold = Options.getIntProperty("nashorn.unstable.relink.threshold", -1);
69 if (relinkThreshold > -1) {
70 factory.setUnstableRelinkThreshold(relinkThreshold);
71 }
72
73 // Linkers for any additional language runtimes deployed alongside Nashorn will be picked up by the factory.
74 factory.setClassLoader(Bootstrap.class.getClassLoader());
75
76 dynamicLinker = factory.createLinker();
77 }
78
79 /**
80 * Returns if the given object is a "callable"
81 * @param obj object to be checked for callability
82 * @return true if the obj is callable
83 */
84 public static boolean isCallable(final Object obj) {
85 if (obj == ScriptRuntime.UNDEFINED || obj == null) {
86 return false;
87 }
88
89 return obj instanceof ScriptFunction ||
90 ((obj instanceof JSObject) && ((JSObject)obj).isFunction()) ||
91 isDynamicMethod(obj) ||
92 isFunctionalInterfaceObject(obj) ||
93 obj instanceof StaticClass;
94 }
95
96 /**
97 * Returns if the given object is a dynalink Dynamic method
98 * @param obj object to be checked
99 * @return true if the obj is a dynamic method
100 */
101 public static boolean isDynamicMethod(final Object obj) {
102 return obj instanceof BoundDynamicMethod || BeansLinker.isDynamicMethod(obj);
103 }
104
105 /**
106 * Returns if the given object is an instance of an interface annotated with
107 * java.lang.FunctionalInterface
108 * @param obj object to be checked
109 * @return true if the obj is an instance of @FunctionalInterface interface
110 */
111 public static boolean isFunctionalInterfaceObject(final Object obj) {
112 return !JSType.isPrimitive(obj) && (NashornBottomLinker.getFunctionalInterfaceMethod(obj.getClass()) != null);
113 }
114
115 /**
116 * Create a call site and link it for Nashorn. This version of the method conforms to the invokedynamic bootstrap
117 * method expected signature and is referenced from Nashorn generated bytecode as the bootstrap method for all
118 * invokedynamic instructions.
119 * @param lookup MethodHandle lookup. Ignored as Nashorn only uses public lookup.
120 * @param opDesc Dynalink dynamic operation descriptor.
121 * @param type Method type.
122 * @param flags flags for call type, trace/profile etc.
123 * @return CallSite with MethodHandle to appropriate method or null if not found.
124 */
125 public static CallSite bootstrap(final Lookup lookup, final String opDesc, final MethodType type, final int flags) {
126 return dynamicLinker.link(LinkerCallSite.newLinkerCallSite(lookup, opDesc, type, flags));
127 }
128
129 /**
130 * Bootstrapper for a specialized Runtime call
131 *
132 * @param lookup lookup
133 * @param initialName initial name for callsite
134 * @param type method type for call site
135 *
136 * @return callsite for a runtime node
137 */
138 public static CallSite runtimeBootstrap(final MethodHandles.Lookup lookup, final String initialName, final MethodType type) {
139 return new RuntimeCallSite(type, initialName);
140 }
141
142 /**
143 * Returns a dynamic invoker for a specified dynamic operation using the public lookup. You can use this method to
144 * create a method handle that when invoked acts completely as if it were a Nashorn-linked call site. An overview of
145 * available dynamic operations can be found in the
146 * <a href="https://github.com/szegedi/dynalink/wiki/User-Guide-0.6">Dynalink User Guide</a>, but we'll show few
147 * examples here:
148 * <ul>
149 * <li>Get a named property with fixed name:
150 * <pre>
151 * MethodHandle getColor = Boostrap.createDynamicInvoker("dyn:getProp:color", Object.class, Object.class);
152 * Object obj = ...; // somehow obtain the object
153 * Object color = getColor.invokeExact(obj);
154 * </pre>
155 * </li>
156 * <li>Get a named property with variable name:
157 * <pre>
158 * MethodHandle getProperty = Boostrap.createDynamicInvoker("dyn:getElem", Object.class, Object.class, String.class);
159 * Object obj = ...; // somehow obtain the object
160 * Object color = getProperty.invokeExact(obj, "color");
161 * Object shape = getProperty.invokeExact(obj, "shape");
162 * MethodHandle getNumProperty = Boostrap.createDynamicInvoker("dyn:getElem", Object.class, Object.class, int.class);
163 * Object elem42 = getNumProperty.invokeExact(obj, 42);
164 * </pre>
165 * </li>
166 * <li>Set a named property with fixed name:
167 * <pre>
168 * MethodHandle setColor = Boostrap.createDynamicInvoker("dyn:setProp:color", void.class, Object.class, Object.class);
169 * Object obj = ...; // somehow obtain the object
170 * setColor.invokeExact(obj, Color.BLUE);
171 * </pre>
172 * </li>
173 * <li>Set a property with variable name:
174 * <pre>
175 * MethodHandle setProperty = Boostrap.createDynamicInvoker("dyn:setElem", void.class, Object.class, String.class, Object.class);
176 * Object obj = ...; // somehow obtain the object
177 * setProperty.invokeExact(obj, "color", Color.BLUE);
178 * setProperty.invokeExact(obj, "shape", Shape.CIRCLE);
179 * </pre>
180 * </li>
181 * <li>Call a function on an object; two-step variant. This is the actual variant used by Nashorn-generated code:
182 * <pre>
183 * MethodHandle findFooFunction = Boostrap.createDynamicInvoker("dyn:getMethod:foo", Object.class, Object.class);
184 * Object obj = ...; // somehow obtain the object
185 * Object foo_fn = findFooFunction.invokeExact(obj);
186 * MethodHandle callFunctionWithTwoArgs = Boostrap.createDynamicInvoker("dyn:call", Object.class, Object.class, Object.class, Object.class, Object.class);
187 * // Note: "call" operation takes a function, then a "this" value, then the arguments:
188 * Object foo_retval = callFunctionWithTwoArgs.invokeExact(foo_fn, obj, arg1, arg2);
189 * </pre>
190 * </li>
191 * <li>Call a function on an object; single-step variant. Although Nashorn doesn't use this variant and never
192 * emits any INVOKEDYNAMIC instructions with {@code dyn:getMethod}, it still supports this standard Dynalink
193 * operation:
194 * <pre>
195 * MethodHandle callFunctionFooWithTwoArgs = Boostrap.createDynamicInvoker("dyn:callMethod:foo", Object.class, Object.class, Object.class, Object.class);
196 * Object obj = ...; // somehow obtain the object
197 * Object foo_retval = callFunctionFooWithTwoArgs.invokeExact(obj, arg1, arg2);
198 * </pre>
199 * </li>
200 * </ul>
201 * Few additional remarks:
202 * <ul>
203 * <li>Just as Nashorn works with any Java object, the invokers returned from this method can also be applied to
204 * arbitrary Java objects in addition to Nashorn JavaScript objects.</li>
205 * <li>For invoking a named function on an object, you can also use the {@link InvokeByName} convenience class.</li>
206 * <li>For Nashorn objects {@code getElem}, {@code getProp}, and {@code getMethod} are handled almost identically,
207 * since JavaScript doesn't distinguish between different kinds of properties on an object. Either can be used with
208 * fixed property name or a variable property name. The only significant difference is handling of missing
209 * properties: {@code getMethod} for a missing member will link to a potential invocation of
210 * {@code __noSuchMethod__} on the object, {@code getProp} for a missing member will link to a potential invocation
211 * of {@code __noSuchProperty__}, while {@code getElem} for a missing member will link to an empty getter.</li>
212 * <li>In similar vein, {@code setElem} and {@code setProp} are handled identically on Nashorn objects.</li>
213 * <li>There's no rule that the variable property identifier has to be a {@code String} for {@code getProp/setProp}
214 * and {@code int} for {@code getElem/setElem}. You can declare their type to be {@code int}, {@code double},
215 * {@code Object}, and so on regardless of the kind of the operation.</li>
216 * <li>You can be as specific in parameter types as you want. E.g. if you know that the receiver of the operation
217 * will always be {@code ScriptObject}, you can pass {@code ScriptObject.class} as its parameter type. If you happen
218 * to link to a method that expects different types, (you can use these invokers on POJOs too, after all, and end up
219 * linking with their methods that have strongly-typed signatures), all necessary conversions allowed by either Java
220 * or JavaScript will be applied: if invoked methods specify either primitive or wrapped Java numeric types, or
221 * {@code String} or {@code boolean/Boolean}, then the parameters might be subjected to standard ECMAScript
222 * {@code ToNumber}, {@code ToString}, and {@code ToBoolean} conversion, respectively. Less obviously, if the
223 * expected parameter type is a SAM type, and you pass a JavaScript function, a proxy object implementing the SAM
224 * type and delegating to the function will be passed. Linkage can often be optimized when linkers have more
225 * specific type information than "everything can be an object".</li>
226 * <li>You can also be as specific in return types as you want. For return types any necessary type conversion
227 * available in either Java or JavaScript will be automatically applied, similar to the process described for
228 * parameters, only in reverse direction: if you specify any either primitive or wrapped Java numeric type, or
229 * {@code String} or {@code boolean/Boolean}, then the return values will be subjected to standard ECMAScript
230 * {@code ToNumber}, {@code ToString}, and {@code ToBoolean} conversion, respectively. Less obviously, if the return
231 * type is a SAM type, and the return value is a JavaScript function, a proxy object implementing the SAM type and
232 * delegating to the function will be returned.</li>
233 * </ul>
234 * @param opDesc Dynalink dynamic operation descriptor.
235 * @param rtype the return type for the operation
236 * @param ptypes the parameter types for the operation
237 * @return MethodHandle for invoking the operation.
238 */
239 public static MethodHandle createDynamicInvoker(final String opDesc, final Class<?> rtype, final Class<?>... ptypes) {
240 return createDynamicInvoker(opDesc, MethodType.methodType(rtype, ptypes));
241 }
242
243 /**
244 * Returns a dynamic invoker for a specified dynamic operation using the public lookup. Similar to
245 * {@link #createDynamicInvoker(String, Class, Class...)} but with return and parameter types composed into a
246 * method type in the signature. See the discussion of that method for details.
247 * @param opDesc Dynalink dynamic operation descriptor.
248 * @param type the method type for the operation
249 * @return MethodHandle for invoking the operation.
250 */
251 public static MethodHandle createDynamicInvoker(final String opDesc, final MethodType type) {
252 return bootstrap(MethodHandles.publicLookup(), opDesc, type, 0).dynamicInvoker();
253 }
254
255 /**
256 * Binds a bean dynamic method (returned by invoking {@code dyn:getMethod} on an object linked with
257 * {@code BeansLinker} to a receiver.
258 * @param dynamicMethod the dynamic method to bind
259 * @param boundThis the bound "this" value.
260 * @return a bound dynamic method.
261 */
262 public static Object bindDynamicMethod(Object dynamicMethod, Object boundThis) {
263 return new BoundDynamicMethod(dynamicMethod, boundThis);
264 }
265
266 /**
267 * Creates a super-adapter for an adapter, that is, an adapter to the adapter that allows invocation of superclass
268 * methods on it.
269 * @param adapter the original adapter
270 * @return a new adapter that can be used to invoke super methods on the original adapter.
271 */
272 public static Object createSuperAdapter(final Object adapter) {
273 return new JavaSuperAdapter(adapter);
274 }
275
276 /**
277 * If the given class is a reflection-specific class (anything in {@code java.lang.reflect} and
278 * {@code java.lang.invoke} package, as well a {@link Class} and any subclass of {@link ClassLoader}) and there is
279 * a security manager in the system, then it checks the {@code nashorn.JavaReflection} {@code RuntimePermission}.
280 * @param clazz the class being tested
281 * @param isStatic is access checked for static members (or instance members)
282 */
283 public static void checkReflectionAccess(Class<?> clazz, boolean isStatic) {
284 ReflectionCheckLinker.checkReflectionAccess(clazz, isStatic);
285 }
286
287 /**
288 * Returns the Nashorn's internally used dynamic linker's services object. Note that in code that is processing a
289 * linking request, you will normally use the {@code LinkerServices} object passed by whatever top-level linker
290 * invoked the linking (if the call site is in Nashorn-generated code, you'll get this object anyway). You should
291 * only resort to retrieving a linker services object using this method when you need some linker services (e.g.
292 * type converter method handles) outside of a code path that is linking a call site.
293 * @return Nashorn's internal dynamic linker's services object.
294 */
295 public static LinkerServices getLinkerServices() {
296 return dynamicLinker.getLinkerServices();
297 }
298
299 /**
300 * Takes a guarded invocation, and ensures its method and guard conform to the type of the call descriptor, using
301 * all type conversions allowed by the linker's services. This method is used by Nashorn's linkers as a last step
302 * before returning guarded invocations to the callers. Most of the code used to produce the guarded invocations
303 * does not make an effort to coordinate types of the methods, and so a final type adjustment before a guarded
304 * invocation is returned is the responsibility of the linkers themselves.
305 * @param inv the guarded invocation that needs to be type-converted. Can be null.
306 * @param linkerServices the linker services object providing the type conversions.
307 * @param desc the call site descriptor to whose method type the invocation needs to conform.
308 * @return the type-converted guarded invocation. If input is null, null is returned. If the input invocation
309 * already conforms to the requested type, it is returned unchanged.
310 */
311 static GuardedInvocation asType(final GuardedInvocation inv, final LinkerServices linkerServices, final CallSiteDescriptor desc) {
312 return inv == null ? null : inv.asType(linkerServices, desc.getMethodType());
313 }
314 }