1 /*
  2  * Copyright (c) 2015, 2023, 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.access;
 27 
 28 import jdk.internal.foreign.abi.NativeEntryPoint;
 29 
 30 import java.lang.invoke.MethodHandle;
 31 import java.lang.invoke.MethodHandles.Lookup;
 32 import java.lang.invoke.MethodType;
 33 import java.lang.invoke.VarHandle;
 34 import java.lang.reflect.Constructor;
 35 import java.lang.reflect.Field;
 36 import java.nio.ByteOrder;
 37 import java.util.List;
 38 import java.util.Map;
 39 import java.util.stream.Stream;
 40 
 41 public interface JavaLangInvokeAccess {
 42     /**
 43      * Returns the declaring class for the given ResolvedMethodName.
 44      * Used by {@code StackFrameInfo}.
 45      */
 46     Class<?> getDeclaringClass(Object rmname);
 47 
 48     /**
 49      * Returns the {@code MethodType} for the given method descriptor
 50      * and class loader.
 51      * Used by {@code StackFrameInfo}.
 52      */
 53     MethodType getMethodType(String descriptor, ClassLoader loader);
 54 
 55     /**
 56      * Returns true if the given flags has MN_CALLER_SENSITIVE flag set.
 57      */
 58     boolean isCallerSensitive(int flags);
 59 
 60     /**
 61      * Returns true if the given flags has MN_HIDDEN_MEMBER flag set.
 62      */
 63     boolean isHiddenMember(int flags);
 64 
 65     /**
 66      * Returns a map of class name in internal forms to its corresponding
 67      * class bytes per the given stream of LF_RESOLVE and SPECIES_RESOLVE
 68      * trace logs. Used by GenerateJLIClassesPlugin to enable generation
 69      * of such classes during the jlink phase.
 70      */
 71     Map<String, byte[]> generateHolderClasses(Stream<String> traces);
 72 
 73     /**
 74      * Returns a var handle view of a given memory segment.
 75      * Used by {@code jdk.internal.foreign.LayoutPath} and
 76      * {@code java.lang.invoke.MethodHandles}.
 77      */
 78     VarHandle memorySegmentViewHandle(Class<?> carrier, long alignmentMask, ByteOrder order);
 79 
 80     /**
 81      * Var handle carrier combinator.
 82      * Used by {@code java.lang.invoke.MethodHandles}.
 83      */
 84     VarHandle filterValue(VarHandle target, MethodHandle filterToTarget, MethodHandle filterFromTarget);
 85 
 86     /**
 87      * Var handle filter coordinates combinator.
 88      * Used by {@code java.lang.invoke.MethodHandles}.
 89      */
 90     VarHandle filterCoordinates(VarHandle target, int pos, MethodHandle... filters);
 91 
 92     /**
 93      * Var handle drop coordinates combinator.
 94      * Used by {@code java.lang.invoke.MethodHandles}.
 95      */
 96     VarHandle dropCoordinates(VarHandle target, int pos, Class<?>... valueTypes);
 97 
 98     /**
 99      * Var handle permute coordinates combinator.
100      * Used by {@code java.lang.invoke.MethodHandles}.
101      */
102     VarHandle permuteCoordinates(VarHandle target, List<Class<?>> newCoordinates, int... reorder);
103 
104     /**
105      * Var handle collect coordinates combinator.
106      * Used by {@code java.lang.invoke.MethodHandles}.
107      */
108     VarHandle collectCoordinates(VarHandle target, int pos, MethodHandle filter);
109 
110     /**
111      * Var handle insert coordinates combinator.
112      * Used by {@code java.lang.invoke.MethodHandles}.
113      */
114     VarHandle insertCoordinates(VarHandle target, int pos, Object... values);
115 
116     /**
117      * Returns a native method handle with given arguments as fallback and steering info.
118      *
119      * Will allow JIT to intrinsify.
120      *
121      * @param nep the native entry point
122      * @return the native method handle
123      */
124     MethodHandle nativeMethodHandle(NativeEntryPoint nep);
125 
126     /**
127      * Produces a method handle unreflecting from a {@code Constructor} with
128      * the trusted lookup
129      */
130     MethodHandle unreflectConstructor(Constructor<?> ctor) throws IllegalAccessException;
131 
132     /**
133      * Produces a method handle unreflecting from a {@code Field} with
134      * the trusted lookup
135      */
136     MethodHandle unreflectField(Field field, boolean isSetter) throws IllegalAccessException;
137 
138     /**
139      * Produces a method handle of a virtual method with the trusted lookup.
140      */
141     MethodHandle findVirtual(Class<?> defc, String name, MethodType type) throws IllegalAccessException;
142 
143     /**
144      * Produces a method handle of a static method with the trusted lookup.
145      */
146     MethodHandle findStatic(Class<?> defc, String name, MethodType type) throws IllegalAccessException;
147 
148     /**
149      * Returns a method handle of an invoker class injected for core reflection
150      * implementation with the following signature:
151      *     reflect_invoke_V(MethodHandle mh, Object target, Object[] args)
152      *
153      * The invoker class is a hidden class which has the same
154      * defining class loader, runtime package, and protection domain
155      * as the given caller class.
156      */
157     MethodHandle reflectiveInvoker(Class<?> caller);
158 
159     /**
160      * A best-effort method that tries to find any exceptions thrown by the given method handle.
161      * @param handle the handle to check
162      * @return an array of exceptions, or {@code null}.
163      */
164     Class<?>[] exceptionTypes(MethodHandle handle);
165 
166     /**
167      * Returns a method handle that allocates an instance of the given class
168      * and then invoke the given constructor of one of its superclasses.
169      *
170      * This method should only be used by ReflectionFactory::newConstructorForSerialization.
171      */
172     MethodHandle serializableConstructor(Class<?> decl, Constructor<?> ctorToCall) throws IllegalAccessException;
173 }