/*

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

import sun.invoke.util.ValueConversions;

import sun.invoke.util.VerifyAccess;

import sun.invoke.util.Wrapper;

import sun.reflect.Reflection;

import static java.lang.invoke.MethodHandleStatics.*;

import static java.lang.invoke.MethodHandleNatives.Constants.*;

/**

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

 * method handles. They fall into several categories:

 * <ul>

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

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

 * <li>Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.

 * <li>Wrapper methods which can convert between method handles and interface types.

 * </ul>

 * <p>

 * @author John Rose, JSR 292 EG

 */

public class MethodHandles {

    private MethodHandles() { }  // do not instantiate

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

    static { MethodHandleImpl.initStatics(); }

    // See IMPL_LOOKUP below.

    //// Method handle creation from ordinary methods.

    /**

     * Returns 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() {

    }

    /**

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

     * It can only be used to create method handles to

     * publicly accessible fields and methods.

     * <p>

     * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}

     * of this lookup object will be {@link java.lang.Object}.

     * <p>

     * The lookup class can be changed to any other class {@code C} using an expression of the form

     * {@linkplain Lookup#in <code>publicLookup().in(C.class)</code>}.

     * Since all classes have equal access to public names,

     * such a change would confer no new access rights.

     */

    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, but rather when they are created.

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

     * <p>

     * A lookup class which needs to create method handles will call

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

     * When the {@code Lookup} factory object is created, the identity of the lookup class is

     * determined, and securely stored in the {@code Lookup} object.

     * The lookup class (or its delegates) may then use factory methods

     * on the {@code Lookup} object to create method handles for access-checked members.

     * This includes all methods, constructors, and fields which are allowed to the lookup class,

     * even private ones.

     * <p>

     * The factory methods on a {@code Lookup} object correspond to all major

     * use cases for methods, constructors, and fields.

     * Here is a summary of the correspondence between these factory methods and

     * the behavior the resulting method handles:

     * <code>

     * <table border=1 cellpadding=5 summary="lookup method behaviors">

     * <tr><th>lookup expression</th><th>member</th><th>behavior</th></tr>

     * <tr>

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

     *     <td>FT f;</td><td>(T) this.f;</td>

     * </tr>

     * <tr>

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

     *     <td>static<br>FT f;</td><td>(T) C.f;</td>

     * </tr>

     * <tr>

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

     *     <td>FT f;</td><td>this.f = x;</td>

     * </tr>

     * <tr>

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

     *     <td>static<br>FT f;</td><td>C.f = arg;</td>

     * </tr>

     * <tr>

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

     *     <td>T m(A*);</td><td>(T) this.m(arg*);</td>

     * </tr>

     * <tr>

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

     *     <td>static<br>T m(A*);</td><td>(T) C.m(arg*);</td>

     * </tr>

     * <tr>

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

     *     <td>T m(A*);</td><td>(T) super.m(arg*);</td>

     * </tr>

     * <tr>

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

     *     <td>C(A*);</td><td>(T) new C(arg*);</td>

     * </tr>

     * <tr>

     *     <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</td>

     *     <td>(static)?<br>FT f;</td><td>(FT) aField.get(thisOrNull);</td>

     * </tr>

     * <tr>

     *     <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>

     *     <td>(static)?<br>FT f;</td><td>aField.set(thisOrNull, arg);</td>

     * </tr>

     * <tr>

     *     <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>

     *     <td>(static)?<br>T m(A*);</td><td>(T) aMethod.invoke(thisOrNull, arg*);</td>

     * </tr>

     * <tr>

     *     <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>

     *     <td>C(A*);</td><td>(C) aConstructor.newInstance(arg*);</td>

     * </tr>

     * <tr>

     *     <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>

     *     <td>(static)?<br>T m(A*);</td><td>(T) aMethod.invoke(thisOrNull, arg*);</td>

     * </tr>

     * </table>

     * </code>

     * Here, the type {@code C} is the class or interface being searched for a member,

     * documented as a parameter named {@code refc} in the lookup methods.

     * The method or constructor type {@code MT} is composed from the return type {@code T}

     * and the sequence of argument types {@code A*}.

     * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.

     * The formal parameter {@code this} stands for the self-reference of type {@code C};

     * if it is present, it is always the leading argument to the method handle invocation.

     * (In the case of some {@code protected} members, {@code this} may be

     * restricted in type to the lookup class; see below.)

     * The name {@code arg} stands for all the other method handle arguments.

     * In the code examples for the Core Reflection API, the name {@code thisOrNull}

     * stands for a null reference if the accessed method or field is static,

     * and {@code this} otherwise.

     * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand

     * for reflective objects corresponding to the given members.

     * <p>

     * In cases where the given member is of variable arity (i.e., a method or constructor)

     * the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}.

     * In all other cases, the returned method handle will be of fixed arity.

     * <p>

     * The equivalence between looked-up method handles and underlying

     * class members can break down in a few ways:

     * <ul>

     * <li>If {@code C} is not symbolically accessible from the lookup class's loader,

     * the lookup can still succeed, even when there is no equivalent

     * Java expression or bytecoded constant.

     * <li>Likewise, if {@code T} or {@code MT}

     * is not symbolically accessible from the lookup class's loader,

     * the lookup can still succeed.

     * For example, lookups for {@code MethodHandle.invokeExact} and

     * {@code MethodHandle.invoke} will always succeed, regardless of requested type.

     * <li>If there is a security manager installed, it can forbid the lookup

     * on various grounds (<a href="#secmgr">see below</a>).

     * By contrast, the {@code ldc} instruction is not subject to

     * security manager checks.

     * </ul>

     *

     * <h3><a name="access"></a>Access checking</h3>

     * Access checks are applied in the factory methods of {@code Lookup},

     * when a method handle is created.

     * This is a key difference from the Core Reflection API, since

     * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}

     * performs access checking against every caller, on every call.

     * <p>

     * All access checks start from a {@code Lookup} object, which

     * compares its recorded lookup class against all requests to

     * create method handles.

     * A single {@code Lookup} object can be used to create any number

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

     * lookup class.

     * <p>

     * A {@code Lookup} object can be shared with other trusted code,

     * such as a metaobject protocol.

     * A shared {@code Lookup} object delegates the capability

     * to create method handles on private members of the lookup class.

     * Even if privileged code uses the {@code Lookup} object,

     * the access checking is confined to the privileges of the

     * original lookup class.

     * <p>

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

     * In any of these cases, a {@code ReflectiveOperationException} will be

     * thrown from the attempted lookup.  The exact class will be one of

     * the following:

     * <ul>

     * <li>NoSuchMethodException &mdash; if a method is requested but does not exist

     * <li>NoSuchFieldException &mdash; if a field is requested but does not exist

     * <li>IllegalAccessException &mdash; if the member exists but an access check fails

     * </ul>

     * <p>

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

     * looked up for a method {@code M} are exactly equivalent to the conditions

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

     * And the effect of invoking the method handle resulting from the lookup

     * is exactly equivalent to executing the compiled and resolved call to {@code M}.

     * The same point is true of fields and constructors.

     * <p>

     * If the desired member is {@code protected}, the usual JVM rules apply,

     * including the requirement that the lookup class must be either be in the

     * same package as the desired member, or must inherit that member.

     * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.)

     * In addition, if the desired member is a non-static field or method

     * in a different package, the resulting method handle may only be applied

     * to objects of the lookup class or one of its subclasses.

     * This requirement is enforced by narrowing the type of the leading

     * {@code this} parameter from {@code C}

     * (which will necessarily be a superclass of the lookup class)

     * to the lookup class itself.

     * <p>

     * In some cases, access between nested classes is obtained by the Java compiler by creating

     * an wrapper method to access a private method of another class

     * in the same top-level declaration.

     * For example, a nested class {@code C.D}

     * can access private members within other related classes such as

     * {@code C}, {@code C.D.E}, or {@code C.B},

     * but the Java compiler may need to generate wrapper methods in

     * those related classes.  In such cases, a {@code Lookup} object on

     * {@code C.E} would be unable to those private members.

     * A workaround for this limitation is the {@link Lookup#in Lookup.in} method,

     * which can transform a lookup on {@code C.E} into one on any of those other

     * classes, without special elevation of privilege.

     * <p>

     * Although bytecode instructions can only refer to classes in

     * a related class loader, this API can search for methods in any

     * class, as long as a reference to its {@code Class} object is

     * available.  Such cross-loader references are also possible with the

     * Core Reflection API, and are impossible to bytecode instructions

     * such as {@code invokestatic} or {@code getfield}.

     * There is a {@linkplain java.lang.SecurityManager security manager API}

     * to allow applications to check such cross-loader references.

     * These checks apply to both the {@code MethodHandles.Lookup} API

     * and the Core Reflection API

     * (as found on {@link java.lang.Class Class}).

     * <p>

     * Access checks only apply to named and reflected methods,

     * constructors, and fields.

     * Other method handle creation methods, such as

     * {@link MethodHandle#asType MethodHandle.asType},

     * do not require any access checks, and are done

     * with static methods of {@link MethodHandles},

     * independently of any {@code Lookup} object.

     *

     * <h3>Security manager interactions</h3>

     * <a name="secmgr"></a>

     * If a security manager is present, member lookups are subject to

     * additional checks.

     * From one to four calls are made to the security manager.

     * Any of these calls can refuse access by throwing a

     * {@link java.lang.SecurityException SecurityException}.

     * Define {@code smgr} as the security manager,

     * {@code refc} as the containing class in which the member

     * is being sought, and {@code defc} as the class in which the

     * member is actually defined.

     * The calls are made according to the following rules:

     * <ul>

     * <li>In all cases, {@link SecurityManager#checkMemberAccess

     *     smgr.checkMemberAccess(refc, Member.PUBLIC)} is called.

     * <li>If the class loader of the lookup class is not

     *     the same as or an ancestor of the class loader of {@code refc},

     *     then {@link SecurityManager#checkPackageAccess

     *     smgr.checkPackageAccess(refcPkg)} is called,

     *     where {@code refcPkg} is the package of {@code refc}.

     * <li>If the retrieved member is not public,

     *     {@link SecurityManager#checkMemberAccess

     *     smgr.checkMemberAccess(defc, Member.DECLARED)} is called.

     *     (Note that {@code defc} might be the same as {@code refc}.)

     *     The default implementation of this security manager method

     *     inspects the stack to determine the original caller of

     *     the reflective request (such as {@code findStatic}),

     *     and performs additional permission checks if the

     *     class loader of {@code defc} differs from the class

     *     loader of the class from which the reflective request came.

     * <li>If the retrieved member is not public,

     *     and if {@code defc} and {@code refc} are in different class loaders,

     *     and if the class loader of the lookup class is not

     *     the same as or an ancestor of the class loader of {@code defc},

     *     then {@link SecurityManager#checkPackageAccess

     *     smgr.checkPackageAccess(defcPkg)} is called,

     *     where {@code defcPkg} is the package of {@code defc}.

     * </ul>

     */

    // FIXME in MR1: clarify that the bytecode behavior of a caller-ID method (like Class.forName) is relative to the lookupClass used to create the method handle, not the dynamic caller of the method handle

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

        private final int allowedModes;

        /** A single-bit mask representing {@code public} access,

         *  which may contribute to the result of {@link #lookupModes lookupModes}.

         *  The value, {@code 0x01}, happens to be the same as the value of the

         *  {@code public} {@linkplain java.lang.reflect.Modifier#PUBLIC modifier bit}.

         */

        public static final int PUBLIC = Modifier.PUBLIC;

        /** A single-bit mask representing {@code private} access,

         *  which may contribute to the result of {@link #lookupModes lookupModes}.

         *  The value, {@code 0x02}, happens to be the same as the value of the

         *  {@code private} {@linkplain java.lang.reflect.Modifier#PRIVATE modifier bit}.

         */

        public static final int PRIVATE = Modifier.PRIVATE;

        /** A single-bit mask representing {@code protected} access,

         *  which may contribute to the result of {@link #lookupModes lookupModes}.

         *  The value, {@code 0x04}, happens to be the same as the value of the

         *  {@code protected} {@linkplain java.lang.reflect.Modifier#PROTECTED modifier bit}.

         */

        public static final int PROTECTED = Modifier.PROTECTED;

        /** A single-bit mask representing {@code package} access (default access),

         *  which may contribute to the result of {@link #lookupModes lookupModes}.

         *  The value is {@code 0x08}, which does not correspond meaningfully to

         *  any particular {@linkplain java.lang.reflect.Modifier modifier bit}.

         */

        public static final int PACKAGE = Modifier.STATIC;

        private static final int ALL_MODES = (PUBLIC | PRIVATE | PROTECTED | PACKAGE);

        private static final int TRUSTED   = -1;

        private static int fixmods(int mods) {

            mods &= (ALL_MODES - PACKAGE);

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

        }

        /** Tells which class is performing the lookup.  It is this class against

         *  which checks are performed for visibility and access permissions.

         *  <p>

         *  The class implies a maximum level of access permission,

         *  but the permissions may be additionally limited by the bitmask

         *  {@link #lookupModes lookupModes}, which controls whether non-public members

         *  can be accessed.

         */

        public Class<?> lookupClass() {

            return lookupClass;

        }

        // This is just for calling out to MethodHandleImpl.

        private Class<?> lookupClassOrNull() {

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

        }

        /** Tells which access-protection classes of members this lookup object can produce.

         *  The result is a bit-mask of the bits

         *  {@linkplain #PUBLIC PUBLIC (0x01)},

         *  {@linkplain #PRIVATE PRIVATE (0x02)},

         *  {@linkplain #PROTECTED PROTECTED (0x04)},

         *  and {@linkplain #PACKAGE PACKAGE (0x08)}.

         *  <p>

         *  A freshly-created lookup object

         *  on the {@linkplain java.lang.invoke.MethodHandles#lookup() caller's class}

         *  has all possible bits set, since the caller class can access all its own members.

         *  A lookup object on a new lookup class

         *  {@linkplain java.lang.invoke.MethodHandles.Lookup#in created from a previous lookup object}

         *  may have some mode bits set to zero.

         *  The purpose of this is to restrict access via the new lookup object,

         *  so that it can access only names which can be reached by the original

         *  lookup object, and also by the new lookup class.

         */

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

         */

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

            checkUnprivilegedlookupClass(lookupClass);

        }

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

            this.lookupClass = lookupClass;

            this.allowedModes = allowedModes;

        }

        /**

         * Creates a lookup on the specified new lookup class.

         * The resulting object will report the specified

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

         * <p>

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

         * to have no more access capabilities than the original.

         * In particular, access capabilities can be lost as follows:<ul>

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

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

         * (Protected members may continue to be accessible because of package sharing.)

         * <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>If the new lookup class is not accessible to the old lookup class,

         * then no members, not even public members, will be accessible.

         * (In all other cases, public members will continue to be accessible.)

         * </ul>

         *

         * @param requestedLookupClass the desired lookup class for the new lookup object

         * @return a lookup object which reports the desired lookup class

         * @throws NullPointerException if the argument is null

         */

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

            }

            // Allow nestmate lookups to be created without special privilege:

            if ((newModes & PRIVATE) != 0

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

                newModes &= ~PRIVATE;

            }

            if ((newModes & PUBLIC) != 0

                && !VerifyAccess.isClassAccessible(requestedLookupClass, this.lookupClass, allowedModes)) {

                // The requested class it not accessible from the lookup class.

                // No permissions.

                newModes = 0;

            }

            checkUnprivilegedlookupClass(requestedLookupClass);

            return new Lookup(requestedLookupClass, newModes);

        }

        // Make sure outer class is initialized first.

        static { IMPL_NAMES.getClass(); }

        /** Version of lookup which is trusted minimally.