Introduction of new API for metadata registration based on conditions.

Author: Mihailo Markovic

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/DynamicJNIAccess.java

@@ -0,0 +1,35 @@
+package org.graalvm.nativeimage.hosted;
+
+import java.lang.reflect.Executable;
+import java.lang.reflect.Field;
+
+/**
+ * This interface is used to register classes, methods, fields for JNI access at runtime.
+ *
+ * All methods in {@link DynamicJNIAccess} require a {@link RegistrationCondition} as their first
+ * parameter. A class and its members will be registered for dynamic access only if the specified
+ * condition is satisfied.
+ *
+ * {@link DynamicJNIAccess} should only be used during {@link Feature#afterRegistration}. Any
+ * attempt of registration in any other phase will result in an error.
+ */
+public interface DynamicJNIAccess {
+
+    /**
+     * Registers the provided classes for JNI access at runtime, if the {@code condition} is
+     * satisfied.
+     */
+    void register(RegistrationCondition condition, Class<?>... classes);
+
+    /**
+     * Registers the provided methods for JNI access at runtime, if the {@code condition} is
+     * satisfied.
+     */
+    void register(RegistrationCondition condition, Executable... methods);
+
+    /**
+     * Registers the provided fields for JNI access at runtime, if the {@code condition} is
+     * satisfied.
+     */
+    void register(RegistrationCondition condition, Field... fields);
+}

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/Feature.java

@@ -171,6 +171,24 @@ interface IsInConfigurationAccess extends FeatureAccess {
      */
     @Platforms(Platform.HOSTED_ONLY.class)
     interface AfterRegistrationAccess extends FeatureAccess {
+
+        /**
+         * Returns the access instance used to register elements for reflection at runtime. All
+         * registrations should happen in {@link Feature#afterRegistration}.
+         */
+        ReflectionDynamicAccess getReflectionDynamicAccess();
+
+        /**
+         * Returns the access instance used to register resources for runtime access. All
+         * registrations should happen in {@link Feature#afterRegistration}.
+         */
+        ResourceDynamicAccess getResourceDynamicAccess();
+
+        /**
+         * Returns the access instance used to register elements for JNI access at runtime. All
+         * registrations should happen in {@link Feature#afterRegistration}.
+         */
+        DynamicJNIAccess getDynamicJNIAccess();
     }
 
     /**

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/ReflectionDynamicAccess.java

@@ -0,0 +1,85 @@
+package org.graalvm.nativeimage.hosted;
+
+import java.lang.reflect.Executable;
+import java.lang.reflect.Field;
+
+/**
+ * This interface is used to register classes, methods, fields, and proxy definitions for
+ * reflection, serialization, and proxy creation at runtime.
+ *
+ * All methods in {@link ReflectionDynamicAccess} require a {@link RegistrationCondition} as their
+ * first parameter. A class and its members will be registered for dynamic access only if the
+ * specified condition is satisfied.
+ *
+ * {@link ReflectionDynamicAccess} should only be used during {@link Feature#afterRegistration}. Any
+ * attempt of registration in any other phase will result in an error.
+ */
+public interface ReflectionDynamicAccess {
+
+    /**
+     * Registers the provided classes for reflection at runtime, and all of their accessible members
+     * available for reflection queries at runtime, if the {@code condition} is satisfied. A call to
+     * {@link Class#forName} for the names of the classes will return the classes at runtime.
+     *
+     * If a class is not registered for reflection at runtime, {@link Class#forName} will throw
+     * {@link org.graalvm.nativeimage.MissingReflectionRegistrationError}.
+     */
+    void register(RegistrationCondition condition, Class<?>... classes);
+
+    /**
+     * If the {@code condition} is satisfied, this method registers the class with the provided name
+     * for reflection at runtime.
+     * <ul>
+     * <li>If the class exists, a call to {@link Class#forName} for the name of the class will
+     * return the class at runtime.</li>
+     * <li>Otherwise, {@link Class#forName} will throw {@link ClassNotFoundException} at
+     * runtime.</li>
+     * </ul>
+     *
+     * If a class is not registered for reflection at runtime, {@link Class#forName} will throw
+     * {@link org.graalvm.nativeimage.MissingReflectionRegistrationError}.
+     */
+    void registerClassLookup(RegistrationCondition condition, String className);
+
+    /**
+     * Registers the provided classes for reflection and unsafe allocation at runtime, and all of
+     * their accessible members available for reflection queries at runtime, if the
+     * {@code condition} is satisfied.
+     *
+     * If a class is not registered for reflection at runtime, {@link Class#forName} will throw
+     * {@link org.graalvm.nativeimage.MissingReflectionRegistrationError}.
+     */
+    void registerUnsafeAllocated(RegistrationCondition condition, Class<?>... classes);
+
+    /**
+     * Registers the provided methods for reflective invocation at runtime, along with the declaring
+     * classes of those methods, including all their members, for reflection queries at runtime, if
+     * the {@code condition} is satisfied. The methods will be invocable via
+     * {@link java.lang.reflect.Method#invoke(java.lang.Object, java.lang.Object...)}.
+     */
+    void register(RegistrationCondition condition, Executable... methods);
+
+    /**
+     * Registers the provided fields for reflective access at runtime, along with the declaring
+     * classes of those fields, including all their members, for reflection queries at runtime, if
+     * the {@code condition} is satisfied. The fields will be accessible via
+     * {@link java.lang.reflect.Field#set(java.lang.Object, java.lang.Object)} and
+     * {@link java.lang.reflect.Field#get(Object)}.
+     */
+    void register(RegistrationCondition condition, Field... fields);
+
+    /**
+     * Registers the provided classes for both serialization and reflection at runtime, if the
+     * {@code condition} is satisfied.
+     */
+    void registerForSerialization(RegistrationCondition condition, Class<?>... classes);
+
+    /**
+     * Registers interfaces that define {@link java.lang.reflect.Proxy} classes, if the
+     * {@code condition} is satisfied. Proxy objects that match the registered definition can be
+     * created at runtime. The proxy class is fully defined by the interfaces it implements.
+     *
+     * @return Proxy class defined by the provided interfaces
+     */
+    Class<?> registerProxy(RegistrationCondition condition, Class<?>... interfaces);
+}

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/ResourceDynamicAccess.java

@@ -0,0 +1,60 @@
+package org.graalvm.nativeimage.hosted;
+
+/**
+ * This interface is used to register Java resources and {@link java.util.ResourceBundle} that
+ * should be accessible at runtime.
+ *
+ * All methods in {@link ResourceDynamicAccess} require a {@link RegistrationCondition} as their
+ * first parameter. A class and its members will be registered for dynamic access only if the
+ * specified condition is satisfied.
+ *
+ * {@link ResourceDynamicAccess} should only be used during {@link Feature#afterRegistration}. Any
+ * attempt of registration in any other phase will result in an error.
+ */
+public interface ResourceDynamicAccess {
+
+    /**
+     * Registers resources from the given {@code module} described with the provided {@code glob},
+     * for dynamic access, if the {@code condition} is satisfied.
+     *
+     * @param condition represents the condition that needs to be satisfied in order to register
+     *            target resources.
+     * @param module represents the Java module instance that contains target resources. If the
+     *            provided value is {@code null} or an unnamed module, resources are looked up on
+     *            the classpath instead.
+     * @param glob can either be exact Java resource path, or a glob that contains wildcards such as
+     *            star(*) or globstar(**). Find glob syntax explanation <a href=
+     *            "/https://www.graalvm.org/latest/reference-manual/native-image/metadata/#resources">here</a>.
+     */
+    void register(RegistrationCondition condition, Module module, String glob);
+
+    /**
+     * Registers resources from the classpath described with the provided {@code glob}, for dynamic
+     * access, if the {@code condition} is satisfied.
+     *
+     * @param condition represents the condition that needs to be satisfied in order to register
+     *            target resources.
+     * @param glob can either be exact Java resource path, or glob that contains wildcards such as
+     *            star(*) or globstar(**). Find glob syntax explanation <a href=
+     *            "/https://www.graalvm.org/latest/reference-manual/native-image/metadata/#resources">here</a>.
+     */
+    default void register(RegistrationCondition condition, String glob) {
+        register(condition, null, glob);
+    }
+
+    /**
+     * Registers {@link java.util.ResourceBundle} that is specified by a {@code bundleName} from the
+     * provided {@code module} for dynamic access, if the {@code condition} is satisfied. If the
+     * given {@code module} is unnamed or the value is {@code null}, the
+     * {@link java.util.ResourceBundle} is looked up on the classpath instead.
+     */
+    void registerResourceBundle(RegistrationCondition condition, Module module, String bundleName);
+
+    /**
+     * Registers {@link java.util.ResourceBundle} that is specified by a {@code bundleName} from the
+     * classpath for dynamic access if the {@code condition} is satisfied.
+     */
+    default void registerResourceBundle(RegistrationCondition condition, String bundleName) {
+        registerResourceBundle(condition, null, bundleName);
+    }
+}

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/impl/RuntimeProxyCreationSupport.java

@@ -44,4 +44,6 @@
 
 public interface RuntimeProxyCreationSupport {
     void addProxyClass(RegistrationCondition condition, Class<?>... interfaces);
+
+    Class<?> registerProxyClass(RegistrationCondition condition, Class<?>... interfaces);
 }

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/impl/RuntimeReflectionSupport.java

@@ -48,6 +48,10 @@ public interface RuntimeReflectionSupport extends ReflectionRegistry {
 
     void registerAllDeclaredMethodsQuery(RegistrationCondition condition, boolean queriedOnly, Class<?> clazz);
 
+    void registerAllFieldsQuery(RegistrationCondition condition, boolean queriedOnly, Class<?> clazz);
+
+    void registerAllDeclaredFieldsQuery(RegistrationCondition condition, boolean queriedOnly, Class<?> clazz);
+
     void registerAllConstructorsQuery(RegistrationCondition condition, boolean queriedOnly, Class<?> clazz);
 
     void registerAllDeclaredConstructorsQuery(RegistrationCondition condition, boolean queriedOnly, Class<?> clazz);

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/impl/RuntimeSerializationSupport.java

@@ -56,6 +56,10 @@ static RuntimeSerializationSupport<RegistrationCondition> singleton() {
 
     void registerIncludingAssociatedClasses(C condition, Class<?> clazz);
 
+    default void register(C condition, Class<?>... classes) {
+        Arrays.stream(classes).forEach(clazz -> register(condition, clazz));
+    }
+
     void register(C condition, Class<?> clazz);
 
     void register(C condition, String clazz);

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/reflect/proxy/DynamicProxySupport.java

@@ -121,6 +121,12 @@ public synchronized void addProxyClass(RegistrationCondition condition, Class<?>
         proxyCache.get(key).getConditions().addCondition(condition);
     }
 
+    @Override
+    public Class<?> registerProxyClass(RegistrationCondition condition, Class<?>... interfaces) {
+        addProxyClass(condition, interfaces);
+        return createProxyClassFromImplementedInterfaces(interfaces);
+    }
+
     @Platforms(Platform.HOSTED_ONLY.class)
     private static Object createProxyClass(Class<?>[] interfaces) {
         try {

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/DynamicAccessSupport.java

@@ -0,0 +1,15 @@
+package com.oracle.svm.hosted;
+
+import com.oracle.svm.core.util.UserError;
+
+public final class DynamicAccessSupport {
+    private static boolean afterRegistrationFinished = false;
+
+    static void setAfterRegistrationFinished() {
+        afterRegistrationFinished = true;
+    }
+
+    public static void printUserError(String registrationEntry) {
+        UserError.guarantee(!afterRegistrationFinished, "Registration for runtime access after Feature#afterRegistration is not allowed. You tried to register %s", registrationEntry);
+    }
+}

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/DynamicJNIAccessImpl.java

@@ -0,0 +1,31 @@
+package com.oracle.svm.hosted;
+
+import java.lang.reflect.Executable;
+import java.lang.reflect.Field;
+import java.util.Arrays;
+
+import org.graalvm.nativeimage.ImageSingletons;
+import org.graalvm.nativeimage.hosted.DynamicJNIAccess;
+import org.graalvm.nativeimage.hosted.RegistrationCondition;
+import org.graalvm.nativeimage.impl.RuntimeJNIAccessSupport;
+
+public class DynamicJNIAccessImpl implements DynamicJNIAccess {
+
+    @Override
+    public void register(RegistrationCondition condition, Class<?>... classes) {
+        DynamicAccessSupport.printUserError("following classes for JNI access: " + Arrays.toString(classes));
+        ImageSingletons.lookup(RuntimeJNIAccessSupport.class).register(condition, classes);
+    }
+
+    @Override
+    public void register(RegistrationCondition condition, Executable... methods) {
+        DynamicAccessSupport.printUserError("following methods for JNI access: " + Arrays.toString(methods));
+        ImageSingletons.lookup(RuntimeJNIAccessSupport.class).register(condition, false, methods);
+    }
+
+    @Override
+    public void register(RegistrationCondition condition, Field... fields) {
+        DynamicAccessSupport.printUserError("following fields for JNI access: " + Arrays.toString(fields));
+        ImageSingletons.lookup(RuntimeJNIAccessSupport.class).register(condition, false, fields);
+    }
+}

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/FeatureImpl.java

@@ -47,10 +47,13 @@
 
 import org.graalvm.collections.Pair;
 import org.graalvm.nativeimage.AnnotationAccess;
+import org.graalvm.nativeimage.hosted.DynamicJNIAccess;
 import org.graalvm.nativeimage.hosted.Feature;
 import org.graalvm.nativeimage.hosted.Feature.DuringAnalysisAccess;
 import org.graalvm.nativeimage.hosted.FieldValueTransformer;
+import org.graalvm.nativeimage.hosted.ReflectionDynamicAccess;
 import org.graalvm.nativeimage.hosted.RegistrationCondition;
+import org.graalvm.nativeimage.hosted.ResourceDynamicAccess;
 import org.graalvm.nativeimage.hosted.RuntimeReflection;
 
 import com.oracle.graal.pointsto.BigBang;
@@ -192,6 +195,21 @@ public void setMainEntryPoint(Pair<Method, CEntryPointData> mainEntryPoint) {
         public Pair<Method, CEntryPointData> getMainEntryPoint() {
             return mainEntryPoint;
         }
+
+        @Override
+        public ReflectionDynamicAccess getReflectionDynamicAccess() {
+            return new ReflectionDynamicAccessImpl();
+        }
+
+        @Override
+        public ResourceDynamicAccess getResourceDynamicAccess() {
+            return new ResourceDynamicAccessImpl();
+        }
+
+        @Override
+        public DynamicJNIAccess getDynamicJNIAccess() {
+            return new DynamicJNIAccessImpl();
+        }
     }
 
     abstract static class AnalysisAccessBase extends FeatureAccessImpl {