1 /*
2 * Copyright (c) 2017, 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 java.lang.invoke;
27
28 import java.lang.invoke.MethodHandles.Lookup;
29
30 /**
31 * An interface providing full static information about a particular
32 * call to a
33 * <a href="package-summary.html#bsm">bootstrap method</a> of an
34 * dynamic call site or dynamic constant.
35 * This information includes the method itself, the associated
36 * name and type, and any associated static arguments.
37 * <p>
38 * If a bootstrap method declares exactly two arguments, and is
39 * not of variable arity, then it is fed only two arguments by
40 * the JVM, the {@linkplain Lookup lookup object} and an instance
41 * of {@code BootstrapCallInfo} which supplies the rest of the
42 * information about the call.
43 * <p>
44 * The API for accessing the static arguments allows the bootstrap
45 * method to reorder the resolution (in the constant pool) of the
46 * static arguments, and to catch errors resulting from the resolution.
47 * This mode of evaluation <em>pulls</em> bootstrap parameters from
48 * the JVM under control of the bootstrap method, as opposed to
49 * the JVM <em>pushing</em> parameters to a bootstrap method
50 * by resolving them all before the bootstrap method is called.
51 * @apiNote
52 * <p>
53 * The {@linkplain Lookup lookup object} is <em>not</em> included in this
54 * bundle of information, so as not to obscure the access control
55 * logic of the program.
56 * In cases where there are many thousands of parameters, it may
57 * be preferable to pull their resolved values, either singly or in
58 * batches, rather than wait until all of them have been resolved
59 * before a constant or call site can be used.
60 * <p>
61 * A push mode bootstrap method can be adapted to a pull mode
62 * bootstrap method, and vice versa. For example, this generic
63 * adapter pops a push-mode bootstrap method from the beginning
64 * of the static argument list, eagerly resolves all the remaining
65 * static arguments, and invokes the popped method in push mode.
66 * The callee has no way of telling that it was not called directly
67 * from the JVM.
68 * <blockquote><pre>{@code
69 static Object genericBSM(Lookup lookup, BootstrapCallInfo<Object> bsci)
70 throws Throwable {
71 ArrayList<Object> args = new ArrayList<>();
72 args.add(lookup);
73 args.add(bsci.invocationName());
74 args.add(bsci.invocationType());
75 MethodHandle bsm = (MethodHandle) bsci.get(0);
76 List<Object> restOfArgs = bsci.asList().subList(1, bsci.size();
77 // the next line eagerly resolves all remaining static arguments:
78 args.addAll(restOfArgs);
79 return bsm.invokeWithArguments(args);
80 }
81 * }</pre></blockquote>
82 *
83 * <p>
84 * In the other direction, here is a combinator which pops
85 * a pull-mode bootstrap method from the beginning of a list of
86 * static argument values (already resolved), reformats all of
87 * the arguments into a pair of a lookup and a {@code BootstrapCallInfo},
88 * and invokes the popped method. Again the callee has no way of
89 * telling it was not called directly by the JVM, except that
90 * all of the constant values will appear as resolved.
91 * Put another way, if any constant fails to resolve, the
92 * callee will not be able to catch the resulting error,
93 * since the error will be thrown by the JVM before the
94 * bootstrap method is entered.
95 * <blockquote><pre>{@code
96 static Object genericBSM(Lookup lookup, String name, Object type,
97 MethodHandle bsm, Object... args)
98 throws Throwable {
99 ConstantGroup cons = ConstantGroup.makeConstantGroup(Arrays.asList(args));
100 BootstrapCallInfo<Object> bsci = makeBootstrapCallInfo(bsm, name, type, cons);
101 return bsm.invoke(lookup, bsci);
102 }
103 * }</pre></blockquote>
104 *
105 * @since 1.10
106 */
107 // public
108 interface BootstrapCallInfo<T> extends ConstantGroup {
109 /** Returns the bootstrap method for this call.
110 * @return the bootstrap method
111 */
112 MethodHandle bootstrapMethod();
113
114 /** Returns the method name or constant name for this call.
115 * @return the method name or constant name
116 */
117 String invocationName();
118
119 /** Returns the method type or constant type for this call.
120 * @return the method type or constant type
121 */
122 T invocationType();
123
124 /**
125 * Make a new bootstrap call descriptor with the given components.
126 * @param bsm bootstrap method
127 * @param name invocation name
128 * @param type invocation type
129 * @param constants the additional static arguments for the bootstrap method
130 * @param <T> the type of the invocation type, either {@link MethodHandle} or {@link Class}
131 * @return a new bootstrap call descriptor with the given components
132 */
133 static <T> BootstrapCallInfo<T> makeBootstrapCallInfo(MethodHandle bsm,
134 String name,
135 T type,
136 ConstantGroup constants) {
137 AbstractConstantGroup.BSCIWithCache<T> bsci = new AbstractConstantGroup.BSCIWithCache<>(bsm, name, type, constants.size());
138 final Object NP = AbstractConstantGroup.BSCIWithCache.NOT_PRESENT;
139 bsci.initializeCache(constants.asList(NP), NP);
140 return bsci;
141 }
142 }