[GR-62940] API for metadata registration that uses conditions

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

@@ -1011,6 +1011,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.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
@@ -1089,6 +1093,10 @@ CLSS public abstract interface org.graalvm.nativeimage.hosted.FieldValueTransfor
 meth public abstract java.lang.Object transform(java.lang.Object,java.lang.Object)
 meth public boolean isAvailable()
 
+CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.AccessCondition
+meth public static org.graalvm.nativeimage.dynamicaccess.AccessCondition alwaysTrue()
+meth public static org.graalvm.nativeimage.dynamicaccess.AccessCondition typeReached(java.lang.Class<?>)
+
 CLSS public final org.graalvm.nativeimage.hosted.RuntimeClassInitialization
 meth public !varargs static void initializeAtBuildTime(java.lang.Class<?>[])
 meth public !varargs static void initializeAtBuildTime(java.lang.String[])
@@ -1147,6 +1155,32 @@ 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.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<?>[])
 meth public !varargs static void registerProxyClass(java.lang.Class<?>[])

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

@@ -0,0 +1,135 @@
+/*
+ * 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.impl.TypeReachabilityCondition;
+
+/**
+ * A condition that must be satisfied to register elements for dynamic access (e.g., reflection,
+ * serialization, JNI access, resource access, and foreign access at runtime).
+ * {@link AccessCondition} is used for programmatic metadata registration in conjunction with:
+ * <ul>
+ * <li>{@link ReflectiveAccess}</li>
+ * <li>{@link ResourceAccess}</li>
+ * <li>{@link JNIAccess}</li>
+ * <li>{@link ForeignAccess}</li>
+ * </ul>
+ * Conditions prevent unnecessary growth of the native binary size.
+ * <p>
+ * There are currently two types of conditions:
+ * <ul>
+ * <li>{@link #typeReached} - satisfied when the type is both reachable by static analysis at build
+ * time, and reached at run time.</li>
+ * <li>{@link #unconditional} - a condition that is always satisfied.</li>
+ * </ul>
+ * <p>
+ * Conditions can be created via the {@link #unconditional} and {@link #typeReached} factory
+ * methods.
+ *
+ * @since 25.0
+ */
+public interface AccessCondition {
+
+    /**
+     * Creates the condition that is always satisfied. Any metadata that is predicated with this
+     * condition will always be included.
+     *
+     * @return instance of the condition
+     *
+     * @since 25.0
+     */
+    static AccessCondition unconditional() {
+        return TypeReachabilityCondition.JAVA_LANG_OBJECT_REACHED;
+    }
+
+    /**
+     * Creates the {@code typeReached} condition that is satisfied when the type is reached at
+     * runtime. A type is reached at runtime, right before the class-initialization routine starts
+     * for that type, or any of the type's subtypes are reached. Metadata predicated with this
+     * condition is only included if the condition is satisfied.
+     * <p>
+     * <strong>Example:</strong>
+     * 
+     * <pre>{@code
+     * class SuperType {
+     *     static {
+     *         // ConditionType reached (subtype reached) => metadata is available
+     *     }
+     * }
+     * 
+     * class ConditionType extends SuperType {
+     *     static {
+     *         // ConditionType reached (before static initializer) => metadata is available
+     *     }
+     * 
+     *     static ConditionType singleton() {
+     *         // ConditionType reached (already initialized) => metadata is available
+     *     }
+     * }
+     * 
+     * public class App {
+     *     public static void main(String[] args) {
+     *         // ConditionType not reached => metadata is not available
+     *         Class<?> clazz = ConditionType.class;
+     *         // ConditionType not reached (ConditionType.class doesn't start class initialization)
+     *         // => metadata is not available
+     *         ConditionType.singleton();
+     *         // ConditionType reached (already initialized) => metadata is available
+     *     }
+     * }
+     * }</pre>
+     * <p>
+     * Type is also reached, if it is marked as {@code --initialize-at-build-time} or any of its
+     * subtypes are marked as {@code --initialize-at-build-time} and they exist on the classpath.
+     * Array types are never marked as reached and therefore cannot be used as the type in a
+     * condition.
+     *
+     * @param type the type that has to be reached for this condition to be satisfied, must not be
+     *            {@code null}
+     *
+     * @return instance of the condition
+     *
+     * @since 25.0
+     */
+    static AccessCondition typeReached(Class<?> type) {
+        return TypeReachabilityCondition.create(type, true);
+    }
+}

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(Condition.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 register
+     *            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 register
+     *            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 register
+     *            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);
+}