/*

 * Copyright (c) 2008, 2010, 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.dyn;

//import sun.dyn.*;

import sun.dyn.Access;

import sun.dyn.MethodHandleImpl;

import static java.dyn.MethodHandles.invokers;  // package-private API

import static sun.dyn.MemberName.newIllegalArgumentException;  // utility

/**

 * A method handle is a typed, directly executable reference to a method,

 * constructor, field, or similar low-level operation, with optional

 * transformations of arguments or return values.

 * <p>

 * Method handles are strongly typed according to signature.

 * They are not distinguished by method name or enclosing class.

 * A method handle must be invoked under a signature which matches

 * <p>

 * The structure of this type is a series of classes, one of which is

 * the return type of the method (or {@code void.class} if none).

 * <p>

 * Every method handle appears as an object containing a method named

 * the method handle's type.

 * A Java method call expression, which compiles to an

 * {@code invokevirtual} instruction,

 * can invoke this method from Java source code.

 * <p>

 * Every call to a method handle specifies an intended method type,

 * which must exactly match the type of the method handle.

 * (The type is specified in the {@code invokevirtual} instruction,

 * via a {@code CONSTANT_NameAndType} constant pool entry.)

 * The call looks within the receiver object for a method

 * The call fails with a {@link WrongMethodTypeException}

 * method of a closely similar signature.

 * As with other kinds

 * of methods in the JVM, signature matching during method linkage

 * is exact, and does not allow for language-level implicit conversions

 * such as {@code String} to {@code Object} or {@code short} to {@code int}.

 * <p>

 * A method handle is an unrestricted capability to call a method.

 * A method handle can be formed on a non-public method by a class

 * that has access to that method; the resulting handle can be used

 * in any place by any caller who receives a reference to it.  Thus, access

 * checking is performed when the method handle is created, not

 * (as in reflection) every time it is called.  Handles to non-public

 * methods, or in non-public classes, should generally be kept secret.

 * <p>

 * The receiver class type must be {@code MethodHandle} and the method name

 * (after resolving symbolic type names) must exactly match the method type

 * of the target method.

 * <p>

 * which is to say that there is no static restriction on what a method handle

 * can throw.  Since the JVM does not distinguish between checked

 * and unchecked exceptions (other than by their class, of course),

 * there is no particular effect on bytecode shape from ascribing

 * checked exceptions to method handle invocations.  But in Java source

 * code, methods which perform method handle calls must either explicitly

 * <p>

 * for any accessible method from a {@code ldc} instruction

 * which refers to a {@code CONSTANT_Methodref} or

 * {@code CONSTANT_InterfaceMethodref} constant pool entry.

 * <p>

 * for creating and calling method handles.

 * <p>

 * A method reference may refer either to a static or non-static method.

 * In the non-static case, the method handle type includes an explicit

 * receiver argument, prepended before any other arguments.

 * In the method handle's type, the initial receiver argument is typed

 * according to the class under which the method was initially requested.

 * (E.g., if a non-static method handle is obtained via {@code ldc},

 * the type of the receiver is the class named in the constant pool entry.)

 * <p>

 * When a method handle to a virtual method is invoked, the method is

 * always looked up in the receiver (that is, the first argument).

 * <p>

 * A non-virtual method handles to a specific virtual method implementation

 * can also be created.  These do not perform virtual lookup based on

 * receiver type.  Such a method handle simulates the effect of

 * an {@code invokespecial} instruction to the same method.

 * <p>

 * Here are some examples of usage:

 * <p><blockquote><pre>

Object x, y; String s; int i;

MethodType mt; MethodHandle mh;

MethodHandles.Lookup lookup = MethodHandles.lookup();

// mt is {(char,char) => String}

mt = MethodType.methodType(String.class, char.class, char.class);

mh = lookup.findVirtual(String.class, "replace", mt);

// (Ljava/lang/String;CC)Ljava/lang/String;

s = mh.<String>invokeExact("daddy",'d','n');

assert(s.equals("nanny"));

// weakly typed invocation (using MHs.invoke)

assert(s.equals("savvy"));

// mt is {Object[] => List}

mt = MethodType.methodType(java.util.List.class, Object[].class);

mh = lookup.findStatic(java.util.Arrays.class, "asList", mt);

// mt is {(Object,Object,Object) => Object}

mt = MethodType.genericMethodType(3);

mh = MethodHandles.collectArguments(mh, mt);

// mt is {(Object,Object,Object) => Object}

// (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;

x = mh.invokeExact((Object)1, (Object)2, (Object)3);

assert(x.equals(java.util.Arrays.asList(1,2,3)));

// mt is { => int}

mt = MethodType.methodType(int.class);

mh = lookup.findVirtual(java.util.List.class, "size", mt);

// (Ljava/util/List;)I

i = mh.<int>invokeExact(java.util.Arrays.asList(1,2,3));

assert(i == 3);

 * </pre></blockquote>

 * Each of the above calls generates a single invokevirtual instruction

 * with the name {@code invoke} and the type descriptors indicated in the comments.

 * The argument types are taken directly from the actual arguments,

 * while the return type is taken from the type parameter.

 * (This type parameter may be a primitive, and it defaults to {@code Object}.)

 * <p>

 * <em>A note on generic typing:</em>  Method handles do not represent

 * their function types in terms of Java parameterized (generic) types,

 * because there are three mismatches between function types and parameterized

 * Java types.

 * <ol>

 * <li>Method types range over all possible arities,

 * Generics are not variadic, and so cannot represent this.</li>

 * <li>Method types can specify arguments of primitive types,

 * which Java generic types cannot range over.</li>

 * <li>Higher order functions over method handles (combinators) are

 * often generic across a wide range of function types, including

 * those of multiple arities.  It is impossible to represent such

 * genericity with a Java type parameter.</li>

 * </ol>

 * Signature polymorphic methods in this class appear to be documented

 * as having type parameters for return types and a parameter, but that is

 * merely a documentation convention.  These type parameters do

 * not play a role in type-checking method handle invocations.

 * <p>

 * Like classes and strings, method handles that correspond to accessible

 * fields, methods, and constructors can be represented directly

 * in a class file's constant pool as constants to be loaded by {@code ldc} bytecodes.

 * Loading such a constant causes the component classes of its type to be loaded as necessary.

 *

 * @see MethodType

 * @see MethodHandles

 * @author John Rose, JSR 292 EG

 */

public abstract class MethodHandle

        // Note: This is an implementation inheritance hack, and will be removed

        // with a JVM change which moves the required hidden state onto this class.

        extends MethodHandleImpl

{

    private static Access IMPL_TOKEN = Access.getToken();

    // interface MethodHandle<R throws X extends Exception,A...>

    // { MethodType<R throws X,A...> type(); public R invokeExact(A...) throws X; }

    /**

     * Internal marker interface which distinguishes (to the Java compiler)

     * those methods which are signature polymorphic.

     */

    @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD,java.lang.annotation.ElementType.TYPE})

    @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME)

    @interface PolymorphicSignature { }

    private MethodType type;

    /**

     * Report the type of this method handle.

     * @return the method handle type

     */

    public final MethodType type() {

        return type;

    }

    /**

     */

    protected MethodHandle(Access token, MethodType type) {

        super(token);

        Access.check(token);

        this.type = type;

    }

    private void initType(MethodType type) {

        type.getClass();  // elicit NPE

        if (this.type != null)  throw new InternalError();

        this.type = type;

    }

    static {

        // This hack allows the implementation package special access to

        // the internals of MethodHandle.  In particular, the MTImpl has all sorts

        // of cached information useful to the implementation code.

        MethodHandleImpl.setMethodHandleFriend(IMPL_TOKEN, new MethodHandleImpl.MethodHandleFriend() {

            public void initType(MethodHandle mh, MethodType type) { mh.initType(type); }

        });

    }

     */

    @Override

    public String toString() {

        return MethodHandleImpl.getNameString(IMPL_TOKEN, this);

    }

    /**

     * Invoke the method handle, allowing any caller signature, but requiring an exact signature match.

     * The signature at the call site of {@code invokeExact} must

     * No conversions are allowed on arguments or return values.

     */

    public final native @PolymorphicSignature <R,A> R invokeExact(A... args) throws Throwable;

    /**

     * Invoke the method handle, allowing any caller signature,

     * <p>

     * <p>

     * Otherwise, the call proceeds as if this method handle were first

     * to the required type, and then the call proceeds as if by

     */

    public final native @PolymorphicSignature <R,A> R invokeGeneric(A... args) throws Throwable;

    /**

     * Perform a varargs invocation, passing the arguments in the given array

     * which mentions only the type {@code Object}, and whose arity is the length

     * of the argument array.

     * <p>

     * <p>

     * conversions are applied as necessary:

     * <ul>

     * <li>reference casting

     * <li>unboxing

     * </ul>

     * The result returned by the call is boxed if it is a primitive,

     * or forced to null if the return type is void.

     * <p>

     * This call is equivalent to the following code:

     * <p><blockquote><pre>

     * </pre></blockquote>

     * @param arguments the arguments to pass to the target

     * @return the result returned by the target

     */

        int argc = arguments == null ? 0 : arguments.length;

        MethodType type = type();

        if (argc <= 10) {

            MethodHandle invoker = MethodHandles.invokers(type).genericInvoker();

            switch (argc) {

                case 0:  return invoker.invokeExact(this);

                case 1:  return invoker.invokeExact(this,

                                    arguments[0]);

                case 2:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1]);

                case 3:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2]);

                case 4:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3]);

                case 5:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4]);

                case 6:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4], arguments[5]);

                case 7:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4], arguments[5],

                                    arguments[6]);

                case 8:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4], arguments[5],

                                    arguments[6], arguments[7]);

                case 9:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4], arguments[5],

                                    arguments[6], arguments[7], arguments[8]);

                case 10:  return invoker.invokeExact(this,

                                    arguments[0], arguments[1], arguments[2],

                                    arguments[3], arguments[4], arguments[5],

                                    arguments[6], arguments[7], arguments[8],

                                    arguments[9]);

            }

        }

        // more than ten arguments get boxed in a varargs list:

        MethodHandle invoker = MethodHandles.invokers(type).varargsInvoker(0);

        return invoker.invokeExact(this, arguments);

    }

    public final Object invokeVarargs(java.util.List<?> arguments) throws Throwable {

    }

     * Produce an adapter method handle which adapts the type of the

     * which is equal to the desired new type.

     * <p>

     * If the original type and new type are equal, returns {@code this}.

     * <p>

     * <p>

     * <p>

     * @param newType the expected type of the new method handle

     * @return a method handle which delegates to {@code this} after performing

     *           any necessary argument conversions, and arranges for any

     *           necessary return value conversions

     * @see MethodHandles#convertArguments

     */

    public MethodHandle asType(MethodType newType) {

        return MethodHandles.convertArguments(this, newType);

    }

    /**

     * Produce a method handle which adapts, as its <i>target</i>,

     * the current method handle.  The type of the adapter will be

     * <p>

     * When called, the adapter replaces a trailing array argument

     * by the array's elements, each as its own argument to the target.

     * (The order of the arguments is preserved.)

     * They are converted pairwise by casting and/or unboxing

     * to the types of the trailing parameters of the target.

     * Finally the target is called.