New API, within new metadata package.

Author: kimeta

sdk/mx.sdk/suite.py

@@ -970,6 +970,7 @@ class UniversalDetector {
         "exports" : [
           "com.oracle.svm.core.annotate",
           "org.graalvm.nativeimage.hosted",
+          "org.graalvm.nativeimage.dynamicaccess",
           "org.graalvm.nativeimage.c.function",
           "org.graalvm.nativeimage.c.struct",
           "org.graalvm.nativeimage.c.type",

sdk/src/org.graalvm.nativeimage/snapshot.sigtest

@@ -1020,10 +1020,10 @@ meth public abstract java.nio.file.Path getImagePath()
 CLSS public abstract interface static org.graalvm.nativeimage.hosted.Feature$AfterRegistrationAccess
  outer org.graalvm.nativeimage.hosted.Feature
 intf org.graalvm.nativeimage.hosted.Feature$FeatureAccess
-meth public abstract org.graalvm.nativeimage.hosted.RuntimeJNIAccess getRuntimeJNIAccess()
-meth public abstract org.graalvm.nativeimage.hosted.RuntimeReflection getRuntimeReflection()
-meth public abstract org.graalvm.nativeimage.hosted.RuntimeResourceAccess getRuntimeResourceAccess()
-meth public abstract org.graalvm.nativeimage.hosted.RuntimeForeignAccess getRuntimeForeignAccess()
+meth public abstract org.graalvm.nativeimage.dynamicaccess.JNIAccess getJNIAccess()
+meth public abstract org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess getReflectiveAccess()
+meth public abstract org.graalvm.nativeimage.dynamicaccess.ResourceAccess getResourceAccess()
+meth public abstract org.graalvm.nativeimage.dynamicaccess.ForeignAccess getForeignAccess()
 
 CLSS public abstract interface static org.graalvm.nativeimage.hosted.Feature$BeforeAnalysisAccess
  outer org.graalvm.nativeimage.hosted.Feature
@@ -1113,34 +1113,23 @@ meth public !varargs static void initializeAtRunTime(java.lang.Class<?>[])
 meth public !varargs static void initializeAtRunTime(java.lang.String[])
 supr java.lang.Object
 
-CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeForeignAccess
+CLSS public final org.graalvm.nativeimage.hosted.RuntimeForeignAccess
 meth public !varargs static void registerForDirectUpcall(java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
 meth public !varargs static void registerForDowncall(java.lang.Object,java.lang.Object[])
 meth public !varargs static void registerForUpcall(java.lang.Object,java.lang.Object[])
-meth public !varargs abstract void registerForDirectUpcall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
-meth public !varargs abstract void registerForDowncall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Object,java.lang.Object[])
-meth public !varargs abstract void registerForUpcall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Object,java.lang.Object[])
-
-CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeJNIAccess
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Executable[])
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Field[])
+supr java.lang.Object
+
+CLSS public final org.graalvm.nativeimage.hosted.RuntimeJNIAccess
 meth public !varargs static void register(java.lang.Class<?>[])
 meth public !varargs static void register(java.lang.reflect.Executable[])
 meth public !varargs static void register(java.lang.reflect.Field[])
+supr java.lang.Object
 
 CLSS public final org.graalvm.nativeimage.hosted.RuntimeProxyCreation
 meth public !varargs static void register(java.lang.Class<?>[])
 supr java.lang.Object
 
-CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeReflection
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
-meth public abstract void registerClassLookup(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
-meth public !varargs abstract void registerUnsafeAllocation(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Executable[])
-meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Field[])
-meth public !varargs abstract void registerForSerialization(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
-meth public !varargs abstract java.lang.Class<?> registerProxy(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
+CLSS public final org.graalvm.nativeimage.hosted.RuntimeReflection
 meth public !varargs static void register(boolean,boolean,java.lang.reflect.Field[])
  anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="21.1")
 meth public !varargs static void register(boolean,java.lang.reflect.Field[])
@@ -1166,16 +1155,41 @@ meth public static void registerAllRecordComponents(java.lang.Class<?>)
 meth public static void registerAllSigners(java.lang.Class<?>)
 meth public static void registerClassLookup(java.lang.String)
 meth public static void registerFieldLookup(java.lang.Class<?>,java.lang.String)
+supr java.lang.Object
 
-CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeResourceAccess
-meth public abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Module,java.lang.String)
-meth public void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
-meth public abstract void registerResourceBundle(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Module,java.lang.String)
-meth public void registerResourceBundle(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
+CLSS public final org.graalvm.nativeimage.hosted.RuntimeResourceAccess
 meth public static void addResource(java.lang.Module,java.lang.String)
 meth public static void addResource(java.lang.Module,java.lang.String,byte[])
 meth public static void addResourceBundle(java.lang.Module,java.lang.String)
 meth public static void addResourceBundle(java.lang.Module,java.lang.String,java.util.Locale[])
+supr java.lang.Object
+
+CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
+meth public abstract void registerClassLookup(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
+meth public !varargs abstract void registerUnsafeAllocation(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Executable[])
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Field[])
+meth public !varargs abstract void registerForSerialization(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
+meth public !varargs abstract java.lang.Class<?> registerProxy(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
+
+CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ResourceAccess
+meth public abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Module,java.lang.String)
+meth public void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
+meth public abstract void registerResourceBundle(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.util.ResourceBundle)
+meth public abstract void registerResourceBundle(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Module,java.lang.String)
+meth public void registerResourceBundle(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
+
+CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.JNIAccess
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Executable[])
+meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Field[])
+
+CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ForeignAccess
+meth public !varargs abstract void registerForDirectUpcall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
+meth public !varargs abstract void registerForDowncall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Object,java.lang.Object[])
+meth public !varargs abstract void registerForUpcall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Object,java.lang.Object[])
+
 
 CLSS public final org.graalvm.nativeimage.hosted.RuntimeSerialization
 meth public !varargs static void register(java.lang.Class<?>[])

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/dynamicaccess/AccessCondition.java

@@ -41,10 +41,6 @@
 package org.graalvm.nativeimage.dynamicaccess;
 
 import org.graalvm.nativeimage.impl.TypeReachabilityCondition;
-import org.graalvm.nativeimage.dynamicaccess.ForeignAccess;
-import org.graalvm.nativeimage.dynamicaccess.JNIAccess;
-import org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess;
-import org.graalvm.nativeimage.dynamicaccess.ResourceAccess;
 
 /**
  * A condition that must be satisfied to register elements for dynamic access (i.e., reflection,

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/dynamicaccess/ForeignAccess.java

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.nativeimage.dynamicaccess;
+
+import org.graalvm.nativeimage.hosted.Feature;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodType;
+
+/**
+ * This interface is used to register classes, methods, and fields for foreign access at runtime. An
+ * instance of this interface is acquired via
+ * {@link Feature.AfterRegistrationAccess#getForeignAccess()}.
+ * <p>
+ * All methods in {@link ForeignAccess} require a {@link AccessCondition} as their first parameter.
+ * Registration for foreign access will happen only if the specified condition is satisfied.
+ *
+ * <h3>How to use</h3>
+ *
+ * {@link ForeignAccess} should only be used during {@link Feature#afterRegistration}. Any attempt
+ * to register metadata in any other phase will result in an error.
+ * <p>
+ * <strong>Example:</strong>
+ *
+ * <pre>{@code @Override
+ * public void afterRegistration(AfterRegistrationAccess access) {
+ *     ForeignAccess foreignAccess = access.getForeignAccess();
+ *     AccessCondition condition = AccessCondition.typeReached(ConditionType.class);
+ *     foreignAccess.registerForDowncall(condition, java.lang.foreign.ValueLayout.JAVA_INT);
+ * }
+ * }</pre>
+ *
+ * @since 25.0
+ */
+public interface ForeignAccess {
+
+    /**
+     * Registers the provided function descriptor and options pair at image build time for downcalls
+     * into foreign code, if the {@code condition} is satisfied. Required to get a downcall method
+     * handle using {@link java.lang.foreign.Linker#downcallHandle} for the same descriptor and
+     * options at runtime.
+     * <p>
+     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * performed to ensure that the arguments have the expected type. It will be deprecated in favor
+     * of strongly typed variant as soon as possible.
+     *
+     * @param condition represents the condition that needs to be satisfied in order to access
+     *            target resources.
+     * @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for downcalls.
+     * @param options An array of {@link java.lang.foreign.Linker.Option} used for the downcalls.
+     *
+     * @since 25.0
+     */
+    void registerForDowncall(AccessCondition condition, Object desc, Object... options);
+
+    /**
+     * Registers the provided function descriptor and options pair at image build time for upcalls
+     * from foreign code, if the {@code condition} is satisfied. Required to get an upcall stub
+     * function pointer using {@link java.lang.foreign.Linker#upcallStub} for the same descriptor
+     * and options at runtime.
+     * <p>
+     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * performed to ensure that the arguments have the expected type. It will be deprecated in favor
+     * of strongly typed variant as soon as possible.
+     *
+     * @param condition represents the condition that needs to be satisfied in order to access
+     *            target resources.
+     * @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for upcalls.
+     * @param options An array of {@link java.lang.foreign.Linker.Option} used for the upcalls.
+     *
+     * @since 25.0
+     */
+    void registerForUpcall(AccessCondition condition, Object desc, Object... options);
+
+    /**
+     * Registers a specific static method (denoted by a method handle) as a fast upcall target, if
+     * the {@code condition} is satisfied. This will create a specialized upcall stub that will
+     * invoke only the specified method, which is much faster than using
+     * {@link #registerForUpcall(AccessCondition, Object, Object...)}).
+     * <p>
+     * The provided method handle must be a direct method handle. Those are most commonly created
+     * using {@link java.lang.invoke.MethodHandles.Lookup#findStatic(Class, String, MethodType)}.
+     * However, a strict requirement is that it must be possible to create a non-empty descriptor
+     * for the method handle using {@link MethodHandle#describeConstable()}. The denoted static
+     * method will also be registered for reflective access since run-time code will also create a
+     * method handle to denoted static method.
+     * </p>
+     * <p>
+     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * performed to ensure that the arguments have the expected type. It will be deprecated in favor
+     * of strongly typed variant as soon as possible.
+     * </p>
+     *
+     * @param condition represents the condition that needs to be satisfied in order to access
+     *            target resources.
+     * @param target A direct method handle denoting a static method.
+     * @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for upcalls.
+     * @param options An array of {@link java.lang.foreign.Linker.Option} used for the upcalls.
+     *
+     * @since 25.0
+     */
+    void registerForDirectUpcall(AccessCondition condition, MethodHandle target, Object desc, Object... options);
+}