https://openjdk.java.net/ 
/*
 * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.lang.invoke;

import java.lang.invoke.MethodHandles.Lookup;


An interface providing full static information about a particular
call to a
bootstrap method of an
dynamic call site or dynamic constant.
This information includes the method itself, the associated
name and type, and any associated static arguments.

 If a bootstrap method declares exactly two arguments, and is not of variable arity, then it is fed only two arguments by the JVM, the lookup object and an instance of BootstrapCallInfo which supplies the rest of the information about the call. 

The API for accessing the static arguments allows the bootstrap
method to reorder the resolution (in the constant pool) of the
static arguments, and to catch errors resulting from the resolution.
This mode of evaluation pulls bootstrap parameters from
the JVM under control of the bootstrap method, as opposed to
the JVM pushing parameters to a bootstrap method
by resolving them all before the bootstrap method is called.

API Note:

 The lookup object is not included in this
bundle of information, so as not to obscure the access control
logic of the program.
In cases where there are many thousands of parameters, it may
be preferable to pull their resolved values, either singly or in
batches, rather than wait until all of them have been resolved
before a constant or call site can be used.


A push mode bootstrap method can be adapted to a pull mode
bootstrap method, and vice versa.  For example, this generic
adapter pops a push-mode bootstrap method from the beginning
of the static argument list, eagerly resolves all the remaining
static arguments, and invokes the popped method in push mode.
The callee has no way of telling that it was not called directly
from the JVM.


static Object genericBSM(Lookup lookup, BootstrapCallInfo<Object> bsci)
throws Throwable {
ArrayList<Object> args = new ArrayList<>();
args.add(lookup);
args.add(bsci.invocationName());
args.add(bsci.invocationType());
MethodHandle bsm = (MethodHandle) bsci.get(0);
List<Object> restOfArgs = bsci.asList().subList(1, bsci.size();
// the next line eagerly resolves all remaining static arguments:
args.addAll(restOfArgs);
return bsm.invokeWithArguments(args);



 In the other direction, here is a combinator which pops a pull-mode bootstrap method from the beginning of a list of static argument values (already resolved), reformats all of the arguments into a pair of a lookup and a BootstrapCallInfo, and invokes the popped method. Again the callee has no way of telling it was not called directly by the JVM, except that all of the constant values will appear as resolved. Put another way, if any constant fails to resolve, the callee will not be able to catch the resulting error, since the error will be thrown by the JVM before the bootstrap method is entered. 

static Object genericBSM(Lookup lookup, String name, Object type,
MethodHandle bsm, Object... args)
throws Throwable {
ConstantGroup cons = ConstantGroup.makeConstantGroup(Arrays.asList(args));
BootstrapCallInfo<Object> bsci = makeBootstrapCallInfo(bsm, name, type, cons);
return bsm.invoke(lookup, bsci);

Since:1.10
/**
 * An interface providing full static information about a particular
 * call to a
 * <a href="package-summary.html#bsm">bootstrap method</a> of an
 * dynamic call site or dynamic constant.
 * This information includes the method itself, the associated
 * name and type, and any associated static arguments.
 * <p>
 * If a bootstrap method declares exactly two arguments, and is
 * not of variable arity, then it is fed only two arguments by
 * the JVM, the {@linkplain Lookup lookup object} and an instance
 * of {@code BootstrapCallInfo} which supplies the rest of the
 * information about the call.
 * <p>
 * The API for accessing the static arguments allows the bootstrap
 * method to reorder the resolution (in the constant pool) of the
 * static arguments, and to catch errors resulting from the resolution.
 * This mode of evaluation <em>pulls</em> bootstrap parameters from
 * the JVM under control of the bootstrap method, as opposed to
 * the JVM <em>pushing</em> parameters to a bootstrap method
 * by resolving them all before the bootstrap method is called.
 * @apiNote
 * <p>
 * The {@linkplain Lookup lookup object} is <em>not</em> included in this
 * bundle of information, so as not to obscure the access control
 * logic of the program.
 * In cases where there are many thousands of parameters, it may
 * be preferable to pull their resolved values, either singly or in
 * batches, rather than wait until all of them have been resolved
 * before a constant or call site can be used.
 * <p>
 * A push mode bootstrap method can be adapted to a pull mode
 * bootstrap method, and vice versa.  For example, this generic
 * adapter pops a push-mode bootstrap method from the beginning
 * of the static argument list, eagerly resolves all the remaining
 * static arguments, and invokes the popped method in push mode.
 * The callee has no way of telling that it was not called directly
 * from the JVM.
 * <blockquote><pre>{@code
static Object genericBSM(Lookup lookup, BootstrapCallInfo<Object> bsci)
    throws Throwable {
  ArrayList<Object> args = new ArrayList<>();
  args.add(lookup);
  args.add(bsci.invocationName());
  args.add(bsci.invocationType());
  MethodHandle bsm = (MethodHandle) bsci.get(0);
  List<Object> restOfArgs = bsci.asList().subList(1, bsci.size();
  // the next line eagerly resolves all remaining static arguments:
  args.addAll(restOfArgs);
  return bsm.invokeWithArguments(args);
}
 * }</pre></blockquote>
 *
 * <p>
 * In the other direction, here is a combinator which pops
 * a pull-mode bootstrap method from the beginning of a list of
 * static argument values (already resolved), reformats all of
 * the arguments into a pair of a lookup and a {@code BootstrapCallInfo},
 * and invokes the popped method.  Again the callee has no way of
 * telling it was not called directly by the JVM, except that
 * all of the constant values will appear as resolved.
 * Put another way, if any constant fails to resolve, the
 * callee will not be able to catch the resulting error,
 * since the error will be thrown by the JVM before the
 * bootstrap method is entered.
 * <blockquote><pre>{@code
static Object genericBSM(Lookup lookup, String name, Object type,
                         MethodHandle bsm, Object... args)
    throws Throwable {
  ConstantGroup cons = ConstantGroup.makeConstantGroup(Arrays.asList(args));
  BootstrapCallInfo<Object> bsci = makeBootstrapCallInfo(bsm, name, type, cons);
  return bsm.invoke(lookup, bsci);
}
 * }</pre></blockquote>
 *
 * @since 1.10
 */
// public
interface BootstrapCallInfo<T> extends ConstantGroup {
    
Returns the bootstrap method for this call.

Returns:the bootstrap method
/** Returns the bootstrap method for this call.
     * @return the bootstrap method
     */
    MethodHandle bootstrapMethod();

    
Returns the method name or constant name for this call.

Returns:the method name or constant name
/** Returns the method name or constant name for this call.
     * @return the method name or constant name
     */
    String invocationName();

    
Returns the method type or constant type for this call.

Returns:the method type or constant type
/** Returns the method type or constant type for this call.
     * @return the method type or constant type
     */
    T invocationType();

    
Make a new bootstrap call descriptor with the given components.

Params:
  • bsm – bootstrap method
  • name – invocation name
  • type – invocation type
  • constants – the additional static arguments for the bootstrap method
Type parameters:
Returns:a new bootstrap call descriptor with the given components
/**
     * Make a new bootstrap call descriptor with the given components.
     * @param bsm bootstrap method
     * @param name invocation name
     * @param type invocation type
     * @param constants the additional static arguments for the bootstrap method
     * @param <T> the type of the invocation type, either {@link MethodHandle} or {@link Class}
     * @return a new bootstrap call descriptor with the given components
     */
    static <T> BootstrapCallInfo<T> makeBootstrapCallInfo(MethodHandle bsm,
                                                          String name,
                                                          T type,
                                                          ConstantGroup constants) {
        AbstractConstantGroup.BSCIWithCache<T> bsci = new AbstractConstantGroup.BSCIWithCache<>(bsm, name, type, constants.size());
        final Object NP = AbstractConstantGroup.BSCIWithCache.NOT_PRESENT;
        bsci.initializeCache(constants.asList(NP), NP);
        return bsci;
    }
}