/*

 * 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 java.lang.reflect.Constructor;

import sun.dyn.Access;

import sun.dyn.MemberName;

import sun.dyn.MethodHandleImpl;

import sun.dyn.util.VerifyAccess;

import sun.dyn.util.Wrapper;

import java.lang.reflect.Field;

import java.lang.reflect.Method;

import java.lang.reflect.Modifier;

import java.util.List;

import java.util.ArrayList;

import java.util.Arrays;

import sun.dyn.Invokers;

import sun.dyn.MethodTypeImpl;

import sun.reflect.Reflection;

import static sun.dyn.MemberName.newIllegalArgumentException;

import static sun.dyn.MemberName.newNoAccessException;

/**

 * This class consists exclusively of static methods that operate on or return

 * method handles. They fall into several categories:

 * <ul>

 * <li>Factory methods which create method handles for methods and fields.

 * <li>Invoker methods which can invoke method handles on dynamically typed arguments and/or varargs arrays.

 * <li>Combinator methods, which combine or transforming pre-existing method handles into new ones.

 * <li>Factory methods which create method handles that emulate other common JVM operations or control flow patterns.

 * </ul>

 * <p>

 * @author John Rose, JSR 292 EG

 */

public class MethodHandles {

    private MethodHandles() { }  // do not instantiate

    private static final Access IMPL_TOKEN = Access.getToken();

    private static final MemberName.Factory IMPL_NAMES = MemberName.getFactory(IMPL_TOKEN);

    static { MethodHandleImpl.initStatics(); }

    // See IMPL_LOOKUP below.

    //// Method handle creation from ordinary methods.

    /**

     * Return a {@link Lookup lookup object} on the caller,

     * which has the capability to access any method handle that the caller has access to,

     * including direct method handles to private fields and methods.

     * This lookup object is a <em>capability</em> which may be delegated to trusted agents.

     * Do not store it in place where untrusted code can access it.

     */

    public static Lookup lookup() {

        return new Lookup();

    }

    /**

     * Return a {@link Lookup lookup object} which is trusted minimally.

     * It can only be used to create method handles to

     * publicly accessible fields and methods.

     */

    public static Lookup publicLookup() {

        return Lookup.PUBLIC_LOOKUP;

    }

    /**

     * A <em>lookup object</em> is a factory for creating method handles,

     * when the creation requires access checking.

     * Method handles do not perform

     * access checks when they are called; this is a major difference

     * from reflective {@link Method}, which performs access checking

     * against every caller, on every call.

     * Therefore, method handle access

     * restrictions must be enforced when a method handle is created.

     * The caller class against which those restrictions are enforced

     * is known as the {@linkplain #lookupClass lookup class}.

     * A lookup object embodies an

     * authenticated lookup class, and can be used to create any number

     * of access-checked method handles, all checked against a single

     * lookup class.

     * <p>

     * A class which needs to create method handles will call

     * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.

     * It may then use this factory to create method handles on

     * all of its methods, including private ones.

     * It may also delegate the lookup (e.g., to a metaobject protocol)

     * by passing the {@code Lookup} object to other code.

     * If this other code creates method handles, they will be access

     * checked against the original lookup class, and not with any higher

     * privileges.

     * <p>

     * Access checks only apply to named and reflected methods.

     * Other method handle creation methods, such as

     * {@link #convertArguments MethodHandles.convertArguments},

     * do not require any access checks, and can be done independently

     * of any lookup class.

     * <h3>How access errors are handled</h3>

     * A lookup can fail, because

     * the containing class is not accessible to the lookup class, or

     * because the desired class member is missing, or because the

     * desired class member is not accessible to the lookup class.

     * It can also fail if a security manager is installed and refuses

     * access.  In any of these cases, an exception will be

     * thrown from the attempted lookup.

     * In general, the conditions under which a method handle may be

     * created for a method {@code M} are exactly as restrictive as the conditions

     * under which the lookup class could have compiled a call to {@code M}.

     * At least some of these error conditions are likely to be

     * represented by checked exceptions in the final version of this API.

     */

    public static final

    class Lookup {

        /** The class on behalf of whom the lookup is being performed. */

        private final Class<?> lookupClass;

        /** The allowed sorts of members which may be looked up (public, etc.), with STRICT for package. */

        private final int allowedModes;

        private static final int

            PUBLIC    = Modifier.PUBLIC,

            PACKAGE   = Modifier.STRICT,

            PROTECTED = Modifier.PROTECTED,

            PRIVATE   = Modifier.PRIVATE,

            ALL_MODES = (PUBLIC | PACKAGE | PROTECTED | PRIVATE),

            TRUSTED   = -1;

        private static int fixmods(int mods) {

            mods &= (ALL_MODES - PACKAGE);

            return (mods != 0) ? mods : PACKAGE;

        }

        /** Which class is performing the lookup?  It is this class against

         *  which checks are performed for visibility and access permissions.

         *  <p>

         *  This value is null if and only if this lookup was produced

         *  by {@link MethodHandles#publicLookup}.

         */

        public Class<?> lookupClass() {

            return lookupClass;

        }

        // This is just for calling out to MethodHandleImpl.

        private Class<?> lookupClassOrNull() {

            return (allowedModes == TRUSTED) ? null : lookupClass;

        }

        /** Which types of members can this lookup object produce?

         *  The result is a bit-mask of the modifier bits PUBLIC, PROTECTED, PRIVATE, and STRICT.

         *  The modifier bit STRICT stands in for the (non-existent) package protection mode.

         */

        int lookupModes() {

            return allowedModes & ALL_MODES;

        }

        /** Embody the current class (the lookupClass) as a lookup class

         * for method handle creation.

         * Must be called by from a method in this package,

         * which in turn is called by a method not in this package.

         * <p>

         * Also, don't make it private, lest javac interpose

         * an access$N method.

         */

        Lookup() {

            this(getCallerClassAtEntryPoint(), ALL_MODES);

            // make sure we haven't accidentally picked up a privileged class:

            checkUnprivilegedlookupClass(lookupClass);

        }

        Lookup(Access token, Class<?> lookupClass) {

            this(lookupClass, ALL_MODES);

            Access.check(token);

        }

        private Lookup(Class<?> lookupClass, int allowedModes) {

            this.lookupClass = lookupClass;

            this.allowedModes = allowedModes;

        }

        /**

         * Create a lookup on the specified new lookup class.

         * The resulting object will report the specified

         * class as its own {@link #lookupClass}.

         * <p>

         * However, the resulting {@code Lookup} object is guaranteed

         * to have no more access capabilities than the original.

         * In particular:<ul>

         * <li>If the new lookup class differs from the old one,

         * protected members will not be accessible by virtue of inheritance.

         * <li>If the new lookup class is in a different package

         * than the old one, protected and default (package) members will not be accessible.

         * <li>If the new lookup class is not within the same package member

         * as the old one, private members will not be accessible.

         * <li>In all cases, public members will continue to be accessible.

         * </ul>

         */

        public Lookup in(Class<?> requestedLookupClass) {

            requestedLookupClass.getClass();  // null check

            if (allowedModes == TRUSTED)  // IMPL_LOOKUP can make any lookup at all

                return new Lookup(requestedLookupClass, ALL_MODES);

            if (requestedLookupClass == this.lookupClass)

                return this;  // keep same capabilities

            int newModes = (allowedModes & (ALL_MODES & ~PROTECTED));

            if ((newModes & PACKAGE) != 0

                && !VerifyAccess.isSamePackage(this.lookupClass, requestedLookupClass)) {

                newModes &= ~(PACKAGE|PRIVATE);

            }

            if ((newModes & PRIVATE) != 0

                && !VerifyAccess.isSamePackageMember(this.lookupClass, requestedLookupClass)) {

                newModes &= ~PRIVATE;

            }

            checkUnprivilegedlookupClass(requestedLookupClass);

            return new Lookup(requestedLookupClass, newModes);

        }

        // Make sure outer class is initialized first.

        static { IMPL_TOKEN.getClass(); }

        /** Version of lookup which is trusted minimally.

         *  It can only be used to create method handles to

         *  publicly accessible members.

         */

        static final Lookup PUBLIC_LOOKUP = new Lookup(Object.class, PUBLIC);

        /** Package-private version of lookup which is trusted. */

        static final Lookup IMPL_LOOKUP = new Lookup(Object.class, TRUSTED);

        static { MethodHandleImpl.initLookup(IMPL_TOKEN, IMPL_LOOKUP); }

        private static void checkUnprivilegedlookupClass(Class<?> lookupClass) {

            String name = lookupClass.getName();

            if (name.startsWith("java.dyn.") || name.startsWith("sun.dyn."))

                throw newIllegalArgumentException("illegal lookupClass: "+lookupClass);

        }

        /** Display the name of the class.

         *  If there are restrictions on the access permitted to this lookup,

         *  display those also.

         */

        @Override

        public String toString() {

            String modestr;

            String cname = lookupClass.getName();

            switch (allowedModes) {

            case TRUSTED:

                return "/trusted";

            case PUBLIC:

                modestr = "/public";

                if (lookupClass == Object.class)

                    return modestr;

                break;

            case PUBLIC|PACKAGE:

                return cname + "/package";

            case 0:  // should not happen

                return cname + "/empty";

            case ALL_MODES:

                return cname;

            }

            StringBuilder buf = new StringBuilder(cname);

            if ((allowedModes & PUBLIC) != 0)     buf.append("/public");

            if ((allowedModes & PACKAGE) != 0)    buf.append("/package");

            if ((allowedModes & PROTECTED) != 0)  buf.append("/protected");

            if ((allowedModes & PRIVATE) != 0)    buf.append("/private");

            return buf.toString();

        }

        // call this from an entry point method in Lookup with extraFrames=0.

        private static Class<?> getCallerClassAtEntryPoint() {

            final int CALLER_DEPTH = 4;

            // 0: Reflection.getCC, 1: getCallerClassAtEntryPoint,

            // 2: Lookup.<init>, 3: MethodHandles.*, 4: caller

            // Note:  This should be the only use of getCallerClass in this file.

            assert(Reflection.getCallerClass(CALLER_DEPTH-1) == MethodHandles.class);

            return Reflection.getCallerClass(CALLER_DEPTH);

        }

        /**

         * Produce a method handle for a static method.

         * The type of the method handle will be that of the method.

         * (Since static methods do not take receivers, there is no

         * additional receiver argument inserted into the method handle type,

         * as there would be with {@link #findVirtual} or {@link #findSpecial}.)

         * The method and all its argument types must be accessible to the lookup class.

         * If the method's class has not yet been initialized, that is done

         * immediately, before the method handle is returned.

         * @param refc the class from which the method is accessed

         * @param name the name of the method

         * @param type the type of the method

         * @return the desired method handle

         * @exception SecurityException <em>TBD</em>

         * @exception NoAccessException if the method does not exist or access checking fails

         */

        public

        MethodHandle findStatic(Class<?> refc, String name, MethodType type) throws NoAccessException {

            MemberName method = resolveOrFail(refc, name, type, true);

            checkMethod(refc, method, true);

            return MethodHandleImpl.findMethod(IMPL_TOKEN, method, false, lookupClassOrNull());

        }

        /**

         * Produce a method handle for a virtual method.

         * The type of the method handle will be that of the method,

         * with the receiver type (usually {@code refc}) prepended.

         * The method and all its argument types must be accessible to the lookup class.

         * <p>

         * (<em>BUG NOTE:</em> The type {@code Object} may be prepended instead

         * of the receiver type, if the receiver type is not on the boot class path.

         * This is due to a temporary JVM limitation, in which MethodHandle

         * claims to be unable to access such classes.  To work around this

         * bug, use {@code convertArguments} to normalize the type of the leading

         * argument to a type on the boot class path, such as {@code Object}.)

         * <p>

         * When called, the handle will treat the first argument as a receiver

         * and dispatch on the receiver's type to determine which method

         * implementation to enter.

         * (The dispatching action is identical with that performed by an

         * {@code invokevirtual} or {@code invokeinterface} instruction.)

         * @param refc the class or interface from which the method is accessed

         * @param name the name of the method

         * @param type the type of the method, with the receiver argument omitted

         * @return the desired method handle

         * @exception SecurityException <em>TBD</em>

         * @exception NoAccessException if the method does not exist or access checking fails

         */

        public MethodHandle findVirtual(Class<?> refc, String name, MethodType type) throws NoAccessException {

            MemberName method = resolveOrFail(refc, name, type, false);

            checkMethod(refc, method, false);

            MethodHandle mh = MethodHandleImpl.findMethod(IMPL_TOKEN, method, true, lookupClassOrNull());

            return restrictProtectedReceiver(method, mh);

        }

        /**

         * Produce a method handle which creates an object and initializes it, using

         * the constructor of the specified type.

         * The parameter types of the method handle will be those of the constructor,

         * while the return type will be a reference to the constructor's class.

         * The constructor and all its argument types must be accessible to the lookup class.

         * If the constructor's class has not yet been initialized, that is done

         * immediately, before the method handle is returned.

         * <p>

         * Note:  The requested type must have a return type of {@code void}.

         * This is consistent with the JVM's treatment of constructor signatures.

         * @param refc the class or interface from which the method is accessed

         * @param type the type of the method, with the receiver argument omitted, and a void return type

         * @return the desired method handle

         * @exception SecurityException <em>TBD</em>

         * @exception NoAccessException if the method does not exist or access checking fails

         */

        public MethodHandle findConstructor(Class<?> refc, MethodType type) throws NoAccessException {

            String name = "<init>";

            MemberName ctor = resolveOrFail(refc, name, type, false, false, lookupClassOrNull());

            assert(ctor.isConstructor());

            checkAccess(refc, ctor);

            MethodHandle rawMH = MethodHandleImpl.findMethod(IMPL_TOKEN, ctor, false, lookupClassOrNull());

            return MethodHandleImpl.makeAllocator(IMPL_TOKEN, rawMH);

        }

        /**

         * Produce an early-bound method handle for a virtual method,

         * as if called from an {@code invokespecial}

         * instruction from {@code caller}.

         * The type of the method handle will be that of the method,

         * with a suitably restricted receiver type (such as {@code caller}) prepended.

         * The method and all its argument types must be accessible

         * to the caller.

         * <p>

         * When called, the handle will treat the first argument as a receiver,

         * but will not dispatch on the receiver's type.

         * (This direct invocation action is identical with that performed by an

         * {@code invokespecial} instruction.)

         * <p>

         * If the explicitly specified caller class is not identical with the

         * lookup class, a security check TBD is performed.

         * @param refc the class or interface from which the method is accessed

         * @param name the name of the method (which must not be "<init>")

         * @param type the type of the method, with the receiver argument omitted

         * @param specialCaller the proposed calling class to perform the {@code invokespecial}

         * @return the desired method handle

         * @exception SecurityException <em>TBD</em>

         * @exception NoAccessException if the method does not exist or access checking fails

         */

        public MethodHandle findSpecial(Class<?> refc, String name, MethodType type,

                                        Class<?> specialCaller) throws NoAccessException {

            checkSpecialCaller(specialCaller);

            MemberName method = resolveOrFail(refc, name, type, false, false, specialCaller);

            checkMethod(refc, method, false);

            MethodHandle mh = MethodHandleImpl.findMethod(IMPL_TOKEN, method, false, specialCaller);

            return restrictReceiver(method, mh, specialCaller);

        }

        /**

         * <em>PROVISIONAL API, WORK IN PROGRESS:</em>

         * Produce a method handle giving read access to a non-static field.

         * The type of the method handle will have a return type of the field's

         * value type.

         * The method handle's single argument will be the instance containing

         * the field.

         * Access checking is performed immediately on behalf of the lookup class.

         * @param name the field's name

         * @param type the field's type

         * @return a method handle which can load values from the field

         * @exception NoAccessException if access checking fails

         */

        public MethodHandle findGetter(Class<?> refc, String name, Class<?> type) throws NoAccessException {

            return makeAccessor(refc, name, type, false, false);

        }

        /**

         * <em>PROVISIONAL API, WORK IN PROGRESS:</em>

         * Produce a method handle giving write access to a non-static field.

         * The type of the method handle will have a void return type.

         * The method handle will take two arguments, the instance containing

         * the field, and the value to be stored.

         * The second argument will be of the field's value type.

         * Access checking is performed immediately on behalf of the lookup class.

         * @param name the field's name

         * @param type the field's type

         * @return a method handle which can store values into the field

         * @exception NoAccessException if access checking fails

         */

        public MethodHandle findSetter(Class<?> refc, String name, Class<?> type) throws NoAccessException {

            return makeAccessor(refc, name, type, false, true);

        }

        /**

         * <em>PROVISIONAL API, WORK IN PROGRESS:</em>

         * Produce a method handle giving read access to a static field.

         * The type of the method handle will have a return type of the field's

         * value type.

         * The method handle will take no arguments.

         * Access checking is performed immediately on behalf of the lookup class.

         * @param name the field's name

         * @param type the field's type

         * @return a method handle which can load values from the field

         * @exception NoAccessException if access checking fails

         */

        public MethodHandle findStaticGetter(Class<?> refc, String name, Class<?> type) throws NoAccessException {

            return makeAccessor(refc, name, type, true, false);

        }

        /**

         * <em>PROVISIONAL API, WORK IN PROGRESS:</em>

         * Produce a method handle giving write access to a static field.

         * The type of the method handle will have a void return type.

         * The method handle will take a single

         * argument, of the field's value type, the value to be stored.

         * Access checking is performed immediately on behalf of the lookup class.

         * @param name the field's name

         * @param type the field's type

         * @return a method handle which can store values into the field

         * @exception NoAccessException if access checking fails

         */

        public MethodHandle findStaticSetter(Class<?> refc, String name, Class<?> type) throws NoAccessException {

            return makeAccessor(refc, name, type, true, true);

        }

        /**

         * Produce an early-bound method handle for a non-static method.

         * The receiver must have a supertype {@code defc} in which a method

         * of the given name and type is accessible to the lookup class.

         * The method and all its argument types must be accessible to the lookup class.

         * The type of the method handle will be that of the method,

         * without any insertion of an additional receiver parameter.

         * The given receiver will be bound into the method handle,

         * so that every call to the method handle will invoke the

         * requested method on the given receiver.

         * <p>

         * This is equivalent to the following expression:

         * <code>

         * {@link #insertArguments insertArguments}({@link #findVirtual findVirtual}(defc, name, type), receiver)

         * </code>

         * where {@code defc} is either {@code receiver.getClass()} or a super

         * type of that class, in which the requested method is accessible

         * to the lookup class.

         * @param receiver the object from which the method is accessed

         * @param name the name of the method

         * @param type the type of the method, with the receiver argument omitted

         * @return the desired method handle

         * @exception SecurityException <em>TBD</em>