/*

 * 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

 * <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.

     * @return the bootstrap method

     */

    MethodHandle bootstrapMethod();

    /** 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.

     * @return the method type or constant type

     */

    T invocationType();

    /**

     * 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;

    }

}