31  * Certain types in this package have special relations to dynamic

    31  * As described in the Java Virtual Machine Specification,

    32  * certain types in this package have special relations to dynamic

    45  * <h2><a name="jvm_mods"></a>Corresponding JVM bytecode format changes</h2>

    46  * <h2><a name="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h2>

    46  * <em>The following low-level information is presented here as a preview of

    47  * The following low-level information summarizes relevant parts of the

    47  * changes being made to the Java Virtual Machine specification for JSR 292.

    48  * Java Virtual Machine specification.  For full details, please see the

    48  * This information will be incorporated in a future version of the JVM specification.</em>

    49  * current version of that specification.

    49  *

    50  *

    50  * <h3><a name="indyinsn"></a>{@code invokedynamic} instruction format</h3>

    51  * Each occurrence of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>.

    51  * In bytecode, an {@code invokedynamic} instruction is formatted as five bytes.

    52  * <h3><a name="indyinsn"></a>{@code invokedynamic} instructions</h3>

    52  * The first byte is the opcode 186 (hexadecimal {@code BA}).

    53  * The next two bytes are a constant pool index (in the same format as for the other {@code invoke} instructions).

    54  * The final two bytes are reserved for future use and required to be zero.

    55  * The constant pool reference of an {@code invokedynamic} instruction is to a entry

    56  * with tag {@code CONSTANT_InvokeDynamic} (decimal 18).  See below for its format.

    57  * The entry specifies the following information:

    58  * <ul>

    59  * <li>a bootstrap method (a {@link java.lang.invoke.MethodHandle MethodHandle} constant)</li>

    60  * <li>the dynamic invocation name (a UTF8 string)</li>

    61  * <li>the argument and return types of the call (encoded as a type descriptor in a UTF8 string)</li>

    62  * <li>optionally, a sequence of additional <em>static arguments</em> to the bootstrap method ({@code ldc}-type constants)</li>

    63  * </ul>

    64  * <p>

    65  * Each instance of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>.

    66  * Multiple instances of an {@code invokedynamic} instruction can share a single

    67  * {@code CONSTANT_InvokeDynamic} entry.

    68  * In any case, distinct call sites always have distinct linkage state.

    69  * <p>

    72  * A dynamic call site is linked by means of a bootstrap method,

    55  * <p>

    73  * as <a href="#bsm">described below</a>.

    74  *

    75  * <h3><a name="indycon"></a>constant pool entries for {@code invokedynamic} instructions</h3>

    76  * If a constant pool entry has the tag {@code CONSTANT_InvokeDynamic} (decimal 18),

    77  * it must contain exactly four more bytes after the tag.

    78  * These bytes are interpreted as two 16-bit indexes, in the usual {@code u2} format.

    79  * The first pair of bytes after the tag must be an index into a side table called the

    80  * <em>bootstrap method table</em>, which is stored in the {@code BootstrapMethods}

    81  * attribute as <a href="#bsmattr">described below</a>.

    82  * The second pair of bytes must be an index to a {@code CONSTANT_NameAndType}.

    83  * <p>

    84  * The first index specifies a bootstrap method used by the associated dynamic call sites.

    85  * The second index specifies the method name, argument types, and return type of the dynamic call site.

    86  * The structure of such an entry is therefore analogous to a {@code CONSTANT_Methodref},

    87  * except that the bootstrap method specifier reference replaces

    88  * the {@code CONSTANT_Class} reference of a {@code CONSTANT_Methodref} entry.

    89  *

    90  * <h3><a name="mtcon"></a>constant pool entries for {@linkplain java.lang.invoke.MethodType method types}</h3>

    91  * If a constant pool entry has the tag {@code CONSTANT_MethodType} (decimal 16),

    92  * it must contain exactly two more bytes, which must be an index to a {@code CONSTANT_Utf8}

    93  * entry which represents a method type descriptor.

    94  * <p>

    95  * The JVM will ensure that on first

    96  * execution of an {@code ldc} instruction for this entry, a {@link java.lang.invoke.MethodType MethodType}

    97  * will be created which represents the type descriptor.

    98  * Any classes mentioned in the {@code MethodType} will be loaded if necessary,

    99  * but not initialized.

   100  * Access checking and error reporting is performed exactly as it is for

   101  * references by {@code ldc} instructions to {@code CONSTANT_Class} constants.

   102  *

   103  * <h3><a name="mhcon"></a>constant pool entries for {@linkplain java.lang.invoke.MethodHandle method handles}</h3>

   104  * If a constant pool entry has the tag {@code CONSTANT_MethodHandle} (decimal 15),

   105  * it must contain exactly three more bytes.  The first byte after the tag is a subtag

   106  * value which must be in the range 1 through 9, and the last two must be an index to a

   107  * {@code CONSTANT_Fieldref}, {@code CONSTANT_Methodref}, or

   108  * {@code CONSTANT_InterfaceMethodref} entry which represents a field or method

   109  * for which a method handle is to be created.

   110  * Furthermore, the subtag value and the type of the constant index value

   111  * must agree according to the table below.

   112  * <p>

   113  * The JVM will ensure that on first execution of an {@code ldc} instruction

   114  * for this entry, a {@link java.lang.invoke.MethodHandle MethodHandle} will be created which represents

   115  * the field or method reference, according to the specific mode implied by the subtag.

   116  * <p>

   117  * As with {@code CONSTANT_Class} and {@code CONSTANT_MethodType} constants,

   118  * the {@code Class} or {@code MethodType} object which reifies the field or method's

   119  * type is created.  Any classes mentioned in this reification will be loaded if necessary,

   120  * but not initialized, and access checking and error reporting performed as usual.

   121  * <p>

   122  * Unlike the reflective {@code Lookup} API, there are no security manager calls made

   123  * when these constants are resolved.

   124  * <p>

   125  * The method handle itself will have a type and behavior determined by the subtag as follows:

   126  * <code>

   127  * <table border=1 cellpadding=5 summary="CONSTANT_MethodHandle subtypes">

   128  * <tr><th>N</th><th>subtag name</th><th>member</th><th>MH type</th><th>bytecode behavior</th><th>lookup expression</th></tr>

   129  * <tr><td>1</td><td>REF_getField</td><td>C.f:T</td><td>(C)T</td><td>getfield C.f:T</td>

   130  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findGetter findGetter(C.class,"f",T.class)}</td></tr>

   131  * <tr><td>2</td><td>REF_getStatic</td><td>C.f:T</td><td>(&nbsp;)T</td><td>getstatic C.f:T</td>

   132  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStaticGetter findStaticGetter(C.class,"f",T.class)}</td></tr>

   133  * <tr><td>3</td><td>REF_putField</td><td>C.f:T</td><td>(C,T)void</td><td>putfield C.f:T</td>

   134  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findSetter findSetter(C.class,"f",T.class)}</td></tr>

   135  * <tr><td>4</td><td>REF_putStatic</td><td>C.f:T</td><td>(T)void</td><td>putstatic C.f:T</td>

   136  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStaticSetter findStaticSetter(C.class,"f",T.class)}</td></tr>

   137  * <tr><td>5</td><td>REF_invokeVirtual</td><td>C.m(A*)T</td><td>(C,A*)T</td><td>invokevirtual C.m(A*)T</td>

   138  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findVirtual findVirtual(C.class,"m",MT)}</td></tr>

   139  * <tr><td>6</td><td>REF_invokeStatic</td><td>C.m(A*)T</td><td>(C,A*)T</td><td>invokestatic C.m(A*)T</td>

   140  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStatic findStatic(C.class,"m",MT)}</td></tr>

   141  * <tr><td>7</td><td>REF_invokeSpecial</td><td>C.m(A*)T</td><td>(C,A*)T</td><td>invokespecial C.m(A*)T</td>

   142  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findSpecial findSpecial(C.class,"m",MT,this.class)}</td></tr>

   143  * <tr><td>8</td><td>REF_newInvokeSpecial</td><td>C.&lt;init&gt;(A*)void</td><td>(A*)C</td><td>new C; dup; invokespecial C.&lt;init&gt;(A*)void</td>

   144  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findConstructor findConstructor(C.class,MT)}</td></tr>

   145  * <tr><td>9</td><td>REF_invokeInterface</td><td>C.m(A*)T</td><td>(C,A*)T</td><td>invokeinterface C.m(A*)T</td>

   146  *               <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findVirtual findVirtual(C.class,"m",MT)}</td></tr>

   147  * </table>

   148  * </code>

   149  * Here, the type {@code C} is taken from the {@code CONSTANT_Class} reference associated

   150  * with the {@code CONSTANT_NameAndType} descriptor.

   151  * The field name {@code f} or method name {@code m} is taken from the {@code CONSTANT_NameAndType}

   152  * as is the result type {@code T} and (in the case of a method or constructor) the argument type sequence

   153  * {@code A*}.

   154  * <p>

   155  * Each method handle constant has an equivalent instruction sequence called its <em>bytecode behavior</em>.

   156  * In general, creating a method handle constant can be done in exactly the same circumstances that

   157  * the JVM would successfully resolve the symbolic references in the bytecode behavior.

   158  * Also, the type of a method handle constant is such that a valid {@code invokeExact} call

   159  * on the method handle has exactly the same JVM stack effects as the <em>bytecode behavior</em>.

   160  * Finally, calling a method handle constant on a valid set of arguments has exactly the same effect

   161  * and returns the same result (if any) as the corresponding <em>bytecode behavior</em>.

   162  * <p>

   163  * Each method handle constant also has an equivalent reflective <em>lookup expression</em>,

   164  * which is a query to a method in {@link java.lang.invoke.MethodHandles.Lookup}.

   165  * In the example lookup method expression given in the table above, the name {@code MT}

   166  * stands for a {@code MethodType} built from {@code T} and the sequence of argument types {@code A*}.

   167  * (Note that the type {@code C} is not prepended to the query type {@code MT} even if the member is non-static.)

   168  * In the case of {@code findSpecial}, the name {@code this.class} refers to the class containing

   169  * the bytecodes.

   170  * <p>

   171  * The special name {@code <clinit>} is not allowed.

   172  * The special name {@code <init>} is not allowed except for subtag 8 as shown.

   173  * <p>

   174  * The JVM verifier and linker apply the same access checks and restrictions for these references as for the hypothetical

   175  * bytecode instructions specified in the last column of the table.

   176  * A method handle constant will successfully resolve to a method handle if the symbolic references

   177  * of the corresponding bytecode instruction(s) would also resolve successfully.

   178  * Otherwise, an attempt to resolve the constant will throw equivalent linkage errors.

   179  * In particular, method handles to

   180  * private and protected members can be created in exactly those classes for which the corresponding

   181  * normal accesses are legal.

   182  * <p>

   183  * A constant may refer to a method or constructor with the {@code varargs}

   184  * bit (hexadecimal {@code 0x0080}) set in its modifier bitmask.

   185  * The method handle constant produced for such a method behaves as if

   186  * it were created by {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector}.

   187  * In other words, the constant method handle will exhibit variable arity,

   188  * when invoked via {@code MethodHandle.invoke}.

   189  * On the other hand, its behavior with respect to {@code invokeExact} will be the same

   190  * as if the {@code varargs} bit were not set.

   191  * <p>

   192  * Although the {@code CONSTANT_MethodHandle} and {@code CONSTANT_MethodType} constant types

   193  * resolve class names, they do not force class initialization.

   194  * Method handle constants for subtags {@code REF_getStatic}, {@code REF_putStatic}, and {@code REF_invokeStatic}

   195  * may force class initialization on their first invocation, just like the corresponding bytecodes.

   196  * <p>

   197  * The rules of section 5.4.3 of

   198  * <cite>The Java&trade; Virtual Machine Specification</cite>

   199  * apply to the resolution of {@code CONSTANT_MethodType}, {@code CONSTANT_MethodHandle},

   200  * and {@code CONSTANT_InvokeDynamic} constants,

   201  * by the execution of {@code invokedynamic} and {@code ldc} instructions.

   202  * (Roughly speaking, this means that every use of a constant pool entry

   203  * must lead to the same outcome.

   204  * If the resolution succeeds, the same object reference is produced

   205  * by every subsequent execution of the same instruction.

   206  * If the resolution of the constant causes an error to occur,

   207  * the same error will be re-thrown on every subsequent attempt

   208  * to use this particular constant.)

   209  * <p>

   210  * Constants created by the resolution of these constant pool types are not necessarily

   211  * interned.  Except for {@code CONSTANT_Class} and {@code CONSTANT_String} entries,

   212  * two distinct constant pool entries might not resolve to the same reference

   213  * even if they contain the same symbolic reference.

   214  *

   215  * <h2><a name="bsm"></a>Bootstrap Methods</h2>

   237  * Next, the bootstrap method call is started, with at least four values being stacked:

    77  * The bootstrap method is invoked on at least three values:

   243  * <li>optionally, one or more <a href="#args">additional static arguments</a> </li>

    82  * <li>optionally, between 1 and 251 additional static arguments taken from the constant pool </li>

   245  * The method handle is then applied to the other values as if by

    84  * Invocation is as if by

   253  * As long as each bootstrap method can be correctly invoked

    92  * As documented in the JVM specification, all failures arising from

   254  * by <code>MethodHandle.invoke</code>, its detailed type is arbitrary.

    93  * the linkage of a dynamic call site are reported

   255  * For example, the first argument could be {@code Object}

    94  * by a {@link java.lang.BootstrapMethodError BootstrapMethodError},

   256  * instead of {@code MethodHandles.Lookup}, and the return type

   257  * could also be {@code Object} instead of {@code CallSite}.

   258  * (Note that the types and number of the stacked arguments limit

   259  * the legal kinds of bootstrap methods to appropriately typed

   260  * static methods and constructors of {@code CallSite} subclasses.)

   261  * <p>

   262  * After resolution, the linkage process may fail in a variety of ways.

   263  * All failures are reported by a {@link java.lang.BootstrapMethodError BootstrapMethodError},

   266  * The following circumstances will cause this:

    97  * If this happens, the same error will the thrown for all subsequent

   267  * <ul>

    98  * attempts to execute the dynamic call site.

   268  * <li>the index to the bootstrap method specifier is out of range </li>

    99  *

   269  * <li>the bootstrap method cannot be resolved </li>

   100  * <h3>timing of linkage</h3>

   270  * <li>the {@code MethodType} to pass to the bootstrap method cannot be resolved </li>

   271  * <li>a static argument to the bootstrap method cannot be resolved

   272  *     (i.e., a {@code CONSTANT_Class}, {@code CONSTANT_MethodType},

   273  *     or {@code CONSTANT_MethodHandle} argument cannot be linked) </li>

   274  * <li>the bootstrap method has the wrong arity,

   275  *     causing {@code MethodHandle.invoke} to throw {@code WrongMethodTypeException} </li>

   276  * <li>the bootstrap method has a wrong argument or return type </li>

   277  * <li>the bootstrap method invocation completes abnormally </li>

   278  * <li>the result from the bootstrap invocation is not a reference to

   279  *     an object of type {@link java.lang.invoke.CallSite CallSite} </li>

   280  * <li>the target of the {@code CallSite} does not have a target of

   281  *     the expected {@code MethodType} </li>

   282  * </ul>

   283  *

   284  * <h3><a name="linktime"></a>timing of linkage</h3>

   309  *

   125 

   318  * <h3><a name="bsmattr">the {@code BootstrapMethods} attribute </h3>

   134  * <h3>types of bootstrap methods</h3>

   319  * Each {@code CONSTANT_InvokeDynamic} entry contains an index which references

   135  * As long as each bootstrap method can be correctly invoked

   320  * a bootstrap method specifier; all such specifiers are contained in a separate array.

   136  * by {@code MethodHandle.invoke}, its detailed type is arbitrary.

   321  * This array is defined by a class attribute named {@code BootstrapMethods}.

   137  * For example, the first argument could be {@code Object}

   322  * The body of this attribute consists of a sequence of byte pairs, all interpreted as

   138  * instead of {@code MethodHandles.Lookup}, and the return type

   323  * as 16-bit counts or constant pool indexes, in the {@code u2} format.

   139  * could also be {@code Object} instead of {@code CallSite}.

   324  * The attribute body starts with a count of bootstrap method specifiers,

   140  * (Note that the types and number of the stacked arguments limit

   325  * which is immediately followed by the sequence of specifiers.

   141  * the legal kinds of bootstrap methods to appropriately typed

   326  * <p>

   142  * static methods and constructors of {@code CallSite} subclasses.)

   327  * Each bootstrap method specifier contains an index to a

   328  * {@code CONSTANT_MethodHandle} constant, which is the bootstrap

   329  * method itself.

   330  * This is followed by a count, and then a sequence (perhaps empty) of

   331  * indexes to <a href="#args">additional static arguments</a>

   332  * for the bootstrap method.

   333  * <p>

   334  * During class loading, the verifier must check the structure of the

   335  * {@code BootstrapMethods} attribute.  In particular, each constant

   336  * pool index must be of the correct type.  A bootstrap method index

   337  * must refer to a {@code CONSTANT_MethodHandle} (tag 15).

   338  * Every other index must refer to a valid operand of an

   339  * {@code ldc_w} or {@code ldc2_w} instruction (tag 3..8 or 15..16).

   340  *

   341  * <h3><a name="args">static arguments to the bootstrap method</h3>

   342  * An {@code invokedynamic} instruction specifies at least three arguments

   343  * to pass to its bootstrap method:

   344  * The caller class (expressed as a {@link java.lang.invoke.MethodHandles.Lookup Lookup object},

   345  * the name (extracted from the {@code CONSTANT_NameAndType} entry),

   346  * and the type (also extracted from the {@code CONSTANT_NameAndType} entry).

   347  * The {@code invokedynamic} instruction may specify additional metadata values

   348  * to pass to its bootstrap method.

   349  * Collectively, these values are called <em>static arguments</em> to the

   350  * {@code invokedynamic} instruction, because they are used once at link

   351  * time to determine the instruction's behavior on subsequent sets of

   352  * <em>dynamic arguments</em>.

   353  * <p>

   354  * Static arguments are used to communicate application-specific meta-data

   355  * to the bootstrap method.

   356  * Drawn from the constant pool, they may include references to classes, method handles,

   357  * strings, or numeric data that may be relevant to the task of linking that particular call site.

   358  * <p>

   359  * Static arguments are specified constant pool indexes stored in the {@code BootstrapMethods} attribute.

   360  * Before the bootstrap method is invoked, each index is used to compute an {@code Object}

   361  * reference to the indexed value in the constant pool.

   362  * The valid constant pool entries are listed in this table:

   363  * <code>

   364  * <table border=1 cellpadding=5 summary="Static argument types">

   365  * <tr><th>entry type</th><th>argument type</th><th>argument value</th></tr>

   366  * <tr><td>CONSTANT_String</td><td><code>java.lang.String</code></td><td>the indexed string literal</td></tr>

   367  * <tr><td>CONSTANT_Class</td><td><code>java.lang.Class</code></td><td>the indexed class, resolved</td></tr>

   368  * <tr><td>CONSTANT_Integer</td><td><code>java.lang.Integer</code></td><td>the indexed int value</td></tr>

   369  * <tr><td>CONSTANT_Long</td><td><code>java.lang.Long</code></td><td>the indexed long value</td></tr>

   370  * <tr><td>CONSTANT_Float</td><td><code>java.lang.Float</code></td><td>the indexed float value</td></tr>

   371  * <tr><td>CONSTANT_Double</td><td><code>java.lang.Double</code></td><td>the indexed double value</td></tr>

   372  * <tr><td>CONSTANT_MethodHandle</td><td><code>java.lang.invoke.MethodHandle</code></td><td>the indexed method handle constant</td></tr>

   373  * <tr><td>CONSTANT_MethodType</td><td><code>java.lang.invoke.MethodType</code></td><td>the indexed method type constant</td></tr>

   374  * </table>

   375  * </code>

   383  * at most 252 extra arguments can be supplied.)

   150  * at most 251 extra arguments can be supplied, since the bootstrap method

   151  * handle itself and its first three arguments must also be stacked.)

   393  * and the {@code java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.)

   161  * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.)