1 /*
  2  * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
  3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  4  *
  5  * This code is free software; you can redistribute it and/or modify it
  6  * under the terms of the GNU General Public License version 2 only, as
  7  * published by the Free Software Foundation.  Oracle designates this
  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package jdk.internal.reflect;
 27 
 28 import java.lang.annotation.Retention;
 29 import java.lang.annotation.RetentionPolicy;
 30 import java.lang.annotation.Target;
 31 
 32 import static java.lang.annotation.ElementType.METHOD;
 33 
 34 /**
 35  * A method annotated @CallerSensitiveAdapter is an adapter method corresponding
 36  * to a caller-sensitive method, which is annotated with @CallerSensitive.
 37  *
 38  * A caller-sensitive adapter is private and has the same name as its
 39  * corresponding caller-sensitive method with a trailing caller class parameter.
 40  *
 41  * When a caller-sensitive method is invoked via Method::invoke or MethodHandle
 42  * the core reflection and method handle implementation will find if
 43  * an @CallerSensitiveAdapter method for that CSM is present. If present,
 44  * the runtime will invoke the adapter method with the caller class
 45  * argument instead. This special calling sequence ensures that the same caller
 46  * class is passed to a caller-sensitive method via Method::invoke,
 47  * MethodHandle::invokeExact, or a mix of these methods.
 48  *
 49  * For example, CSM::returnCallerClass is a caller-sensitive method
 50  * with an adapter method:
 51  * {@code
 52  * class CSM {
 53  *     @CallerSensitive
 54  *     static Class<?> returnCallerClass() {
 55  *         return returnCallerClass(Reflection.getCallerClass());
 56  *     }
 57  *     @CallerSensitiveAdapter
 58  *     private static Class<?> returnCallerClass(Class<?> caller) {
 59  *         return caller;
 60  *     }
 61  * }
 62  *
 63  * class Test {
 64  *     void test() throws Throwable {
 65  *         // calling CSM::returnCallerClass via reflection
 66  *         var csm = CSM.class.getMethod("returnCallerClass");
 67  *         // expect Foo to be the caller class
 68  *         var caller = csm.invoke(null);
 69  *         assert(caller == Test.class);
 70  *     }
 71  *     void test2() throws Throwable {
 72  *         // method handle for Method::invoke
 73  *         MethodHandle mh = MethodHandles.lookup().findVirtual(Method.class, "invoke",
 74  *                                  methodType(Object.class, Object.class, Object[].class));
 75  *         var csm = CSM.class.getMethod("returnCallerClass");
 76  *         // invoke Method::invoke via method handle and the target method
 77  *         // being invoked reflectively is CSM::returnCallerClass
 78  *         var caller = mh.invoke(csm, null, null);
 79  *         assert(caller == Test.class);
 80  *     }
 81  * }
 82  * }
 83  *
 84  *
 85  * Both CSM::returnCallerClass and Method::invoke can have an adapter method
 86  * with a caller-class parameter defined. Test::test calls CSM::returnCallerClass
 87  * via Method::invoke which does the stack walking to find the caller's class.
 88  * It will pass the caller's class directly to the adapter method for
 89  * CSM::returnCallerClass.
 90  *
 91  * Similarly, Test::test2 invokes the method handle of Method::invoke to
 92  * call CSM::returnCallerClass reflectively.  In that case, MethodHandle::invokeExact
 93  * uses the lookup class of the Lookup object producing the method handle
 94  * as the caller's class, so no stack walking involved. The lookup class is Test.
 95  * It will invoke the adapter method of Method::invoke with Test as the caller's
 96  * class, which in turn invokes the adapter method of CSM::returnCallerClass
 97  * with Test as the caller. The calling sequence eliminates the need for
 98  * multiple stack walks when a caller-sensitive method is invoked reflectively.
 99  *
100  * For caller-sensitive methods that require an exact caller class, the adapter
101  * method must be defined for correctness. {@link java.lang.invoke.MethodHandles#lookup()}
102  * and {@link ClassLoader#registerAsParallelCapable()} are the only two methods
103  * in the JDK that need the exact caller class.
104  *
105  * On the other hand, for caller-sensitive methods that use the caller's class
106  * for access checks or security permission checks, i.e., based on its runtime
107  * package, defining loader, or protection domain, the adapter method is optional.
108  */
109 @Retention(RetentionPolicy.CLASS)
110 @Target({METHOD})
111 public @interface CallerSensitiveAdapter {
112 }