< prev index next >

src/java.base/share/classes/java/lang/invoke/package-info.java

Print this page

        

*** 94,134 **** * Resolving a dynamically-computed call site or constant * starts with resolving constants from the constant pool for the * following items: * <ul> * <li>the bootstrap method, a {@code CONSTANT_MethodHandle}</li> ! * <li>the {@code Class} or {@code MethodType} derived from * type component of the {@code CONSTANT_NameAndType} descriptor</li> * <li>static arguments, if any (note that static arguments can themselves be * dynamically-computed constants)</li> * </ul> * <p> ! * The bootstrap method is then invoked, as if by * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}, * with the following arguments: * <ul> * <li>a {@code MethodHandles.Lookup}, which is a lookup object on the <em>caller class</em> * in which dynamically-computed constant or call site occurs</li> * <li>a {@code String}, the name mentioned in the {@code CONSTANT_NameAndType}</li> ! * <li>a {@code MethodType} or {@code Class}, the resolved type descriptor of the {@code CONSTANT_NameAndType}</li> ! * <li>a {@code Class}, the resolved type descriptor of the constant, if it is a dynamic constant </li> * <li>the additional resolved static arguments, if any</li> * </ul> * <p> * For a dynamically-computed call site, the returned result must be a non-null reference to a * {@link java.lang.invoke.CallSite CallSite}. * The type of the call site's target must be exactly equal to the type * derived from the invocation's type descriptor and passed to * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. * On success the call site then becomes permanently linked to the {@code invokedynamic} * instruction. * <p> ! * For a dynamically-computed constant, the first parameter of the bootstrap ! * method must be assignable to {@code MethodHandles.Lookup}. If this condition ! * is not met, a {@code BootstrapMethodError} is thrown. ! * On success the result of the bootstrap method is cached as the resolved ! * constant value. * <p> * If an exception, {@code E} say, occurs during execution of the bootstrap method, then * resolution fails and terminates abnormally. {@code E} is rethrown if the type of * {@code E} is {@code Error} or a subclass, otherwise a * {@code BootstrapMethodError} that wraps {@code E} is thrown. --- 94,139 ---- * Resolving a dynamically-computed call site or constant * starts with resolving constants from the constant pool for the * following items: * <ul> * <li>the bootstrap method, a {@code CONSTANT_MethodHandle}</li> ! * <li>the {@code MethodType} or {@code Class} derived from * type component of the {@code CONSTANT_NameAndType} descriptor</li> * <li>static arguments, if any (note that static arguments can themselves be * dynamically-computed constants)</li> * </ul> * <p> ! * The bootstrap method is then invoked, in general, as if by * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}, * with the following arguments: * <ul> * <li>a {@code MethodHandles.Lookup}, which is a lookup object on the <em>caller class</em> * in which dynamically-computed constant or call site occurs</li> * <li>a {@code String}, the name mentioned in the {@code CONSTANT_NameAndType}</li> ! * <li>for a dynamically-computed call site a {@code MethodType} (the resolved ! * type descriptor of the call site), or for a dynamically computed constant, ! * a {@code Class} (the resolved type descriptor of the constant)</li> * <li>the additional resolved static arguments, if any</li> * </ul> + * For dynamically computed constant, if the bootstrap method has no parameters + * or the first parameter type is not assignable to {@code MethodHandles.Lookup} + * then the method is invoked as described above but with just the arguments + * that are the additional resolved static arguments, if any. * <p> * For a dynamically-computed call site, the returned result must be a non-null reference to a * {@link java.lang.invoke.CallSite CallSite}. * The type of the call site's target must be exactly equal to the type * derived from the invocation's type descriptor and passed to * the bootstrap method. If these conditions are not met, a {@code BootstrapMethodError} is thrown. * On success the call site then becomes permanently linked to the {@code invokedynamic} * instruction. * <p> ! * For a dynamically-computed constant, the result of the bootstrap method is ! * cached as the resolved constant value. The constant value must be ! * convertible to the {@code Class} derived from type component of the ! * {@code CONSTANT_NameAndType} descriptor, otherwise a ! * {@code BootstrapMethodError} is thrown. * <p> * If an exception, {@code E} say, occurs during execution of the bootstrap method, then * resolution fails and terminates abnormally. {@code E} is rethrown if the type of * {@code E} is {@code Error} or a subclass, otherwise a * {@code BootstrapMethodError} that wraps {@code E} is thrown.
*** 174,198 **** * <h3>Types of bootstrap methods</h3> * For a dynamically-computed call site, the bootstrap method is invoked with parameter * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types * of any static arguments; the return type is {@code CallSite}. * <p> ! * For a dynamically-computed constant, the bootstrap method is invoked with parameter types ! * {@code MethodHandles.Lookup}, {@code String}, {@code Class}, and the types of any ! * static arguments; the return type is the type represented by the {@code Class}. * <p> * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for * adaptations between the invoked method type and the bootstrap method handle's method type, * there is flexibility in the declaration of the bootstrap method. - * For a dynamically-computed constant the first parameter type of the bootstrap method handle - * must be assignable to {@code MethodHandles.Lookup}, other than that constraint the same degree - * of flexibility applies to bootstrap methods of dynamically-computed call sites and - * dynamically-computed constants. - * Note: this constraint allows for the future possibility where the bootstrap method is - * invoked with just the parameter types of static arguments, thereby supporting a wider - * range of methods compatible with the static arguments (such as methods that don't declare - * or require the lookup, name, and type meta-data parameters). * <p> For example, for dynamically-computed call site, a the first argument * could be {@code Object} instead of {@code MethodHandles.Lookup}, and the return type * could also be {@code Object} instead of {@code CallSite}. * (Note that the types and number of the stacked arguments limit * the legal kinds of bootstrap methods to appropriately typed --- 179,200 ---- * <h3>Types of bootstrap methods</h3> * For a dynamically-computed call site, the bootstrap method is invoked with parameter * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types * of any static arguments; the return type is {@code CallSite}. * <p> ! * For a dynamically-computed constant, if the first parameter of the bootstrap ! * method is assignable to {@code MethodHandles.Lookup} then the bootstrap ! * method is invoked with parameter types {@code MethodHandles.Lookup}, ! * {@code String}, {@code Class}, and the types of any static arguments. ! * Otherwise, the bootstrap method is invoked with just the parameter types of ! * any static arguments. In either case the return type is the type represented ! * by the {@code Class} (regardless of whether the bootstrap is invoked with ! * just the static arguments). * <p> * Because {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke} allows for * adaptations between the invoked method type and the bootstrap method handle's method type, * there is flexibility in the declaration of the bootstrap method. * <p> For example, for dynamically-computed call site, a the first argument * could be {@code Object} instead of {@code MethodHandles.Lookup}, and the return type * could also be {@code Object} instead of {@code CallSite}. * (Note that the types and number of the stacked arguments limit * the legal kinds of bootstrap methods to appropriately typed
*** 203,219 **** * then some or all of the arguments specified here may be collected into a trailing array parameter. * (This is not a special rule, but rather a useful consequence of the interaction * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) * <p> ! * Given these rules, here are examples of legal bootstrap method declarations for * dynamically-computed call sites, given various numbers {@code N} of extra arguments. * The first row (marked {@code *}) will work for any number of extra arguments. * <table class="plain" style="vertical-align:top"> * <caption style="display:none">Static argument types</caption> * <thead> ! * <tr><th scope="col">N</th><th scope="col">Sample bootstrap method</th></tr> * </thead> * <tbody> * <tr><th scope="row" style="font-weight:normal; vertical-align:top">*</th><td> * <ul style="list-style:none; padding-left: 0; margin:0"> * <li><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code> --- 205,223 ---- * then some or all of the arguments specified here may be collected into a trailing array parameter. * (This is not a special rule, but rather a useful consequence of the interaction * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) * <p> ! * Given these rules the following examples and explanations are presented for ! * legal bootstrap method declarations. ! * Here are examples of legal bootstrap method declarations for * dynamically-computed call sites, given various numbers {@code N} of extra arguments. * The first row (marked {@code *}) will work for any number of extra arguments. * <table class="plain" style="vertical-align:top"> * <caption style="display:none">Static argument types</caption> * <thead> ! * <tr><th scope="col">N</th><th scope="col">Sample bootstrap method for a dynamically-computed call site</th></tr> * </thead> * <tbody> * <tr><th scope="row" style="font-weight:normal; vertical-align:top">*</th><td> * <ul style="list-style:none; padding-left: 0; margin:0"> * <li><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code>
*** 237,272 **** * </table> * The last example assumes that the extra arguments are of type * {@code String} and {@code Integer} (or {@code int}), respectively. * The second-to-last example assumes that all extra arguments are of type * {@code String}. ! * The other examples work with all types of extra arguments. Note that all ! * the examples except the second and third also work with dynamically-computed ! * constants if the return type is changed to be compatible with the ! * constant's declared type (such as {@code Object}, which is always compatible). ! * <p> ! * Since dynamically-computed constants can be provided as static arguments to bootstrap ! * methods, there are no limitations on the types of bootstrap arguments. ! * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} ! * cannot be <em>directly</em> supplied by {@code CONSTANT_Integer} ! * constant pool entries, since the {@code asType} conversions do ! * not perform the necessary narrowing primitive conversions. ! * <p> ! * In the above examples, the return type is always {@code CallSite}, ! * but that is not a necessary feature of bootstrap methods. ! * In the case of a dynamically-computed call site, the only requirement is that ! * the return type of the bootstrap method must be convertible ! * (using the {@code asType} conversions) to {@code CallSite}, which * means the bootstrap method return type might be {@code Object} or * {@code ConstantCallSite}. ! * In the case of a dynamically-resolved constant, the return type of the bootstrap ! * method must be convertible to the type of the constant, as ! * represented by its field type descriptor. For example, if the ! * dynamic constant has a field type descriptor of {@code "C"} ! * ({@code char}) then the bootstrap method return type could be ! * {@code Object}, {@code Character}, or {@code char}, but not ! * {@code int} or {@code Integer}. * * @author John Rose, JSR 292 EG * @since 1.7 */ --- 241,317 ---- * </table> * The last example assumes that the extra arguments are of type * {@code String} and {@code Integer} (or {@code int}), respectively. * The second-to-last example assumes that all extra arguments are of type * {@code String}. ! * The other examples work with all types of extra arguments. ! * <p> ! * Since dynamically-computed constants can be provided as static arguments to ! * bootstrap methods for both dynamically-computed call sites and ! * dynamically-computed constants, there are no limitations on the types of ! * bootstrap arguments. However, arguments of type {@code boolean}, ! * {@code byte}, {@code short}, or {@code char} cannot be <em>directly</em> ! * supplied by {@code CONSTANT_Integer} constant pool entries, since the ! * {@code asType} conversions do not perform the necessary narrowing primitive ! * conversions. ! * <p> ! * In the above examples, the return type is always {@code CallSite}, but that ! * is not a necessary feature of call site bootstrap methods. The only ! * requirement is that the return type of the bootstrap method must be ! * convertible (using the {@code asType} conversions) to {@code CallSite}, which * means the bootstrap method return type might be {@code Object} or * {@code ConstantCallSite}. ! * <p> ! * Here are examples of legal bootstrap method declarations for ! * dynamically-computed constants, given various numbers {@code N} of extra ! * arguments. The first row (marked {@code *}) will work for any number of ! * extra arguments. ! * <table class="plain" style="vertical-align:top"> ! * <caption style="display:none">Static argument types</caption> ! * <thead> ! * <tr><th scope="col">N</th><th scope="col">Sample bootstrap method for a dynamically-computed constant</th></tr> ! * </thead> ! * <tbody> ! * <tr><th scope="row" style="font-weight:normal; vertical-align:top">*</th><td> ! * <ul style="list-style:none; padding-left: 0; margin:0"> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type, Object... args)</code> ! * <li><code>Object bootstrap(Object... args)</code> ! * <li><code>Object bootstrap(Object firstArg, Object... otherArgs)</code> ! * </ul></td></tr> ! * <tr><th scope="row" style="font-weight:normal; vertical-align:top">0</th><td> ! * <ul style="list-style:none; padding-left: 0; margin:0"> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type)</code> ! * <li><code>Object bootstrap(Lookup caller, Object... nameAndType)</code> ! * <li><code>Object bootstrap()</code> ! * <li><code>Object bootstrap(Object... args)</code> ! * </ul></td></tr> ! * <tr><th scope="row" style="font-weight:normal; vertical-align:top">1</th><td> ! * <ul style="list-style:none; padding-left: 0; margin:0"> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type, Object arg)</code> ! * <li><code>Object bootstrap(Object arg)</code> ! * </ul></td></tr> ! * <tr><th scope="row" style="font-weight:normal; vertical-align:top">2</th><td> ! * <ul style="list-style:none; padding-left: 0; margin:0"> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type, Object... args)</code> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type, String... args)</code> ! * <li><code>Object bootstrap(Lookup caller, String name, Class type, String x, int y)</code> ! * <li><code>Object bootstrap(Object... args)</code> ! * <li><code>Object bootstrap(String... args)</code> ! * <li><code>Object bootstrap(String x, int y)</code> ! * </ul></td></tr> ! * </tbody> ! * </table> ! * The example methods whose first parameter type, if any, is not {@code Lookup} ! * will be invoked with just the static arguments. ! * <p> ! * In the above examples, the return type is always {@code Object}, but that ! * is not a necessary feature of dynamic constant bootstrap methods. The only ! * requirement is that method must be convertible to the type of the constant, ! * as represented by its field type descriptor. For example, if the dynamic ! * constant has a field type descriptor of {@code "C"} ({@code char}) then the ! * bootstrap method return type could be {@code Object}, {@code Character}, or ! * {@code char}, but not {@code int} or {@code Integer}. * * @author John Rose, JSR 292 EG * @since 1.7 */
< prev index next >