1 /* |
1 /* |
2 * Copyright (c) 2008, 2017, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 2008, 2018, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
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 |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
120 * derived from the invocation's type descriptor and passed to |
120 * derived from the invocation's type descriptor and passed to |
121 * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. |
121 * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. |
122 * On success the call site then becomes permanently linked to the {@code invokedynamic} |
122 * On success the call site then becomes permanently linked to the {@code invokedynamic} |
123 * instruction. |
123 * instruction. |
124 * <p> |
124 * <p> |
125 * For a dynamically-computed constant, the result of the bootstrap method is cached |
125 * For a dynamically-computed constant, the first parameter of the bootstrap |
126 * as the resolved constant value. |
126 * method must be assignable to {@code MethodHandles.Lookup}. If this condition |
|
127 * is not met, a {@code BootstrapMethodError} is thrown. |
|
128 * On success the result of the bootstrap method is cached as the resolved |
|
129 * constant value. |
127 * <p> |
130 * <p> |
128 * If an exception, {@code E} say, occurs during execution of the bootstrap method, then |
131 * If an exception, {@code E} say, occurs during execution of the bootstrap method, then |
129 * resolution fails and terminates abnormally. {@code E} is rethrown if the type of |
132 * resolution fails and terminates abnormally. {@code E} is rethrown if the type of |
130 * {@code E} is {@code Error} or a subclass, otherwise a |
133 * {@code E} is {@code Error} or a subclass, otherwise a |
131 * {@code BootstrapMethodError} that wraps {@code E} is thrown. |
134 * {@code BootstrapMethodError} that wraps {@code E} is thrown. |
169 * There is no way to undo the effect of a completed bootstrap method call. |
172 * There is no way to undo the effect of a completed bootstrap method call. |
170 * |
173 * |
171 * <h2>Types of bootstrap methods</h2> |
174 * <h2>Types of bootstrap methods</h2> |
172 * For a dynamically-computed call site, the bootstrap method is invoked with parameter |
175 * For a dynamically-computed call site, the bootstrap method is invoked with parameter |
173 * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types |
176 * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types |
174 * of any static arguments; the return type is {@code CallSite}. For a |
177 * of any static arguments; the return type is {@code CallSite}. |
175 * dynamically-computed constant, the bootstrap method is invoked with parameter types |
178 * <p> |
|
179 * For a dynamically-computed constant, the bootstrap method is invoked with parameter types |
176 * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any |
180 * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any |
177 * static arguments; the return type is the type represented by the {@code Class}. |
181 * static arguments; the return type is the type represented by the {@code Class}. |
178 * |
182 * <p> |
179 * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for |
183 * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for |
180 * adaptations between the invoked method type and the method handle's method type, |
184 * adaptations between the invoked method type and the bootstrap method handle's method type, |
181 * there is flexibility in the declaration of the bootstrap method. |
185 * there is flexibility in the declaration of the bootstrap method. |
182 * For example, the first argument could be {@code Object} |
186 * For a dynamically-computed constant the first parameter type of the bootstrap method handle |
183 * instead of {@code MethodHandles.Lookup}, and the return type |
187 * must be assignable to {@code MethodHandles.Lookup}, other than that constraint the same degree |
|
188 * of flexibility applies to bootstrap methods of dynamically-computed call sites and |
|
189 * dynamically-computed constants. |
|
190 * Note: this constraint allows for the future possibility where the bootstrap method is |
|
191 * invoked with just the parameter types of static arguments, thereby supporting a wider |
|
192 * range of methods compatible with the static arguments (such as methods that don't declare |
|
193 * or require the lookup, name, and type meta-data parameters). |
|
194 * <p> For example, for dynamically-computed call site, a the first argument |
|
195 * could be {@code Object} instead of {@code MethodHandles.Lookup}, and the return type |
184 * could also be {@code Object} instead of {@code CallSite}. |
196 * could also be {@code Object} instead of {@code CallSite}. |
185 * (Note that the types and number of the stacked arguments limit |
197 * (Note that the types and number of the stacked arguments limit |
186 * the legal kinds of bootstrap methods to appropriately typed |
198 * the legal kinds of bootstrap methods to appropriately typed |
187 * static methods and constructors.) |
199 * static methods and constructors.) |
188 * <p> |
200 * <p> |
225 * </table> |
237 * </table> |
226 * The last example assumes that the extra arguments are of type |
238 * The last example assumes that the extra arguments are of type |
227 * {@code String} and {@code Integer} (or {@code int}), respectively. |
239 * {@code String} and {@code Integer} (or {@code int}), respectively. |
228 * The second-to-last example assumes that all extra arguments are of type |
240 * The second-to-last example assumes that all extra arguments are of type |
229 * {@code String}. |
241 * {@code String}. |
230 * The other examples work with all types of extra arguments. |
242 * The other examples work with all types of extra arguments. Note that all |
|
243 * the examples except the second and third also work with dynamically-computed |
|
244 * constants if the return type is changed to be compatible with the |
|
245 * constant's declared type (such as {@code Object}, which is always compatible). |
231 * <p> |
246 * <p> |
232 * Since dynamically-computed constants can be provided as static arguments to bootstrap |
247 * Since dynamically-computed constants can be provided as static arguments to bootstrap |
233 * methods, there are no limitations on the types of bootstrap arguments. |
248 * methods, there are no limitations on the types of bootstrap arguments. |
234 * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} |
249 * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} |
235 * cannot be <em>directly</em> supplied by {@code CONSTANT_Integer} |
250 * cannot be <em>directly</em> supplied by {@code CONSTANT_Integer} |