Introduction of new API for metadata registration based on conditions. User must create DynamicAccess object via factory method inside AfterRegistrationAccess.

Author: Mihailo Markovic

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

@@ -0,0 +1,127 @@
+package org.graalvm.nativeimage.hosted;
+
+import java.lang.reflect.Executable;
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.Locale;
+import java.util.Objects;
+
+import org.graalvm.nativeimage.ImageSingletons;
+import org.graalvm.nativeimage.impl.RuntimeResourceSupport;
+
+/**
+ * Dynamic access allows users to register classes, methods, fields that should be available for
+ * reflection, serialization and JNI access at runtime, as well as registration of Java resources
+ * and ResourceBundles that should be available at runtime.
+ *
+ * It should only be used at {@link Feature#afterRegistration}.
+ */
+public interface DynamicAccess {
+    /**
+     * Makes the provided classes available for reflection at run time and all of their accessible
+     * members available for reflection queries at run time. A call to {@link Class#forName} for the
+     * names of the classes will return the classes at run time.
+     *
+     * @param condition needs to be satisfied for inclusion of types for reflection at runtime
+     */
+    void registerForReflection(InclusionCondition condition, Class<?>... classes);
+
+    /**
+     * Makes the provided class available for reflection at run time if the condition is satisfied.
+     * A call to {@link Class#forName} for the name of the class will return the class (if it
+     * exists) or a {@link ClassNotFoundException} at run time.
+     */
+    void registerClassLookup(InclusionCondition condition, String className);
+
+    /**
+     * Makes the provided methods available for reflection at run time if the condition is
+     * satisfied. The methods will be returned by {@link Class#getMethod},
+     * {@link Class#getDeclaredMethod(String, Class[])}, and all the other methods on {@link Class}
+     * that return a single method.
+     */
+    void registerForReflection(InclusionCondition condition, Executable... methods);
+
+    /**
+     * Makes the provided classes available for serialization and reflection at runtime if the
+     * condition is satisfied.
+     */
+    void registerForSerialization(InclusionCondition condition, Class<?>... classes);
+
+    /**
+     * Makes the provided classes available for JNI access at run time if the condition is
+     * satisfied. Needed when native code looks up Java classes via <a href=
+     * "https://docs.oracle.com/en/java/javase/17/docs/specs/jni/functions.html#findclass">FindClass</a>.
+     */
+    void registerForJNIAccess(InclusionCondition condition, Class<?>... classes);
+
+    /**
+     * Makes the provided methods available for JNI access at run time if the condition is
+     * satisfied. Needed when native code looks up Java methods via <a href=
+     * "https://docs.oracle.com/en/java/javase/17/docs/specs/jni/functions.html#getmethodid">GetMethodID</a>
+     * or <a href=
+     * "https://docs.oracle.com/en/java/javase/17/docs/specs/jni/functions.html#getstaticmethodid">GetStaticMethodID</a>.
+     */
+    void registerForJNIAccess(InclusionCondition condition, Executable... methods);
+
+    /**
+     * Makes the provided methods available for JNI access at run time if the condition is
+     * satisfied. Needed when native code looks up Java methods via <a href=
+     * "https://docs.oracle.com/en/java/javase/17/docs/specs/jni/functions.html#getmethodid">GetMethodID</a>
+     * or <a href=
+     * "https://docs.oracle.com/en/java/javase/17/docs/specs/jni/functions.html#getstaticmethodid">GetStaticMethodID</a>.
+     */
+    void registerForJNIAccess(InclusionCondition condition, Field... fields);
+
+    /// TO-DO: Ask what is best for resource registration
+
+    /**
+     * Make Java resource {@code resourcePath} from {@code module} available at run time. If the
+     * given {@code module} is unnamed, the resource is looked up on the classpath instead.
+     */
+    public static void addResource(Module module, String resourcePath) {
+        Objects.requireNonNull(module);
+        Objects.requireNonNull(resourcePath);
+        ImageSingletons.lookup(RuntimeResourceSupport.class).addResource(module, resourcePath, "Manually added via RuntimeResourceAccess");
+    }
+
+    /**
+     * Inject a Java resource at {@code resourcePath} in {@code module} with the specified
+     * {@code resourceContent}. At runtime the resource can be accessed as if it was part of the
+     * original application. If the given {@code module} is unnamed, the resource is placed on the
+     * classpath instead.
+     */
+    public static void addResource(Module module, String resourcePath, byte[] resourceContent) {
+        Objects.requireNonNull(module);
+        Objects.requireNonNull(resourcePath);
+        Objects.requireNonNull(resourceContent);
+        ImageSingletons.lookup(RuntimeResourceSupport.class).injectResource(module, resourcePath, resourceContent, "Manually added via RuntimeResourceAccess");
+        ImageSingletons.lookup(RuntimeResourceSupport.class).addCondition(InclusionCondition.alwaysTrue(), module, resourcePath);
+    }
+
+    /**
+     * Make Java ResourceBundle that is specified by a {@code baseBundleName} and {@code locales}
+     * from module {@code module} available at run time. If the given {@code module} is unnamed, the
+     * ResourceBundle is looked up on the classpath instead.
+     */
+    public static void addResourceBundle(Module module, String baseBundleName, Locale[] locales) {
+        Objects.requireNonNull(locales);
+        RuntimeResourceSupport.singleton().addResourceBundles(InclusionCondition.alwaysTrue(),
+                        withModuleName(module, baseBundleName), Arrays.asList(locales));
+    }
+
+    /**
+     * Make Java ResourceBundle that is specified by a {@code bundleName} from module {@code module}
+     * available at run time. If the given {@code module} is unnamed, the ResourceBundle is looked
+     * up on the classpath instead.
+     */
+    public static void addResourceBundle(Module module, String bundleName) {
+        RuntimeResourceSupport.singleton().addResourceBundles(InclusionCondition.alwaysTrue(),
+                        withModuleName(module, bundleName));
+    }
+
+    private static String withModuleName(Module module, String str) {
+        Objects.requireNonNull(module);
+        Objects.requireNonNull(str);
+        return (module.isNamed() ? module.getName() : "ALL-UNNAMED") + ":" + str;
+    }
+}

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

@@ -171,6 +171,12 @@ interface IsInConfigurationAccess extends FeatureAccess {
      */
     @Platforms(Platform.HOSTED_ONLY.class)
     interface AfterRegistrationAccess extends FeatureAccess {
+        /**
+         * Creates access for runtime registration. All registrations should happen in
+         * {@link Feature#afterRegistration}
+         *
+         */
+        DynamicAccess createDynamicAccess();
     }
 
     /**

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

@@ -42,6 +42,22 @@
 
 import org.graalvm.nativeimage.impl.TypeCondition;
 
+/**
+ * Condition that needs to be satisfied for inclusion of elements for runtime access.
+ * {@link InclusionCondition} is used with {@link DynamicAccess} for programmatic registration of
+ * metadata.
+ * <p>
+ * Currently, there is only two types of condition:
+ * <li><code>typeReached</code> (the default) that signifies that the type must be both reachable by
+ * static analysis at build time, and reached at run time. A type is reached at run time, right
+ * before the class-initialization routine starts for that type, or any of the type's subtypes are
+ * reached.</li>
+ * <p>
+ *
+ * User can only create <code>typeReached</code> conditions, since <code>typeReachable</code> are
+ * deprecated. Conditions are created via {@link InclusionCondition#alwaysTrue} and
+ * {@link InclusionCondition#typeReached} factory methods.
+ */
 public interface InclusionCondition {
 
     /**
@@ -55,8 +71,7 @@ static InclusionCondition alwaysTrue() {
     }
 
     /**
-     * Creates the default type-reached condition that is satisfied when the type is reached at
-     * runtime.
+     * Creates the type-reached condition that is satisfied when the type is reached at runtime.
      *
      * @param type that has to be reached for this condition to be satisfied
      * @return instance of the condition

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

@@ -220,7 +220,7 @@ public static void registerAllDeclaredConstructors(Class<?> declaringClass) {
      * @since 23.0
      */
     public static void registerAllFields(Class<?> declaringClass) {
-        ImageSingletons.lookup(RuntimeReflectionSupport.class).registerAllFields(MetadataCondition.alwaysTrue(), declaringClass);
+        ImageSingletons.lookup(RuntimeReflectionSupport.class).registerAllFields(InclusionCondition.alwaysTrue(), declaringClass);
     }
 
     /**

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

@@ -44,22 +44,24 @@
 import java.lang.reflect.Field;
 import java.util.Arrays;
 
+import org.graalvm.nativeimage.hosted.InclusionCondition;
+
 public interface ReflectionRegistry {
-    default void register(MetadataCondition condition, Class<?>... classes) {
+    default void register(InclusionCondition condition, Class<?>... classes) {
         Arrays.stream(classes).forEach(clazz -> register(condition, false, clazz));
     }
 
-    void register(MetadataCondition condition, boolean unsafeAllocated, Class<?> clazz);
+    void register(InclusionCondition condition, boolean unsafeAllocated, Class<?> clazz);
 
-    void register(MetadataCondition condition, boolean queriedOnly, Executable... methods);
+    void register(InclusionCondition condition, boolean queriedOnly, Executable... methods);
 
-    void register(MetadataCondition condition, boolean finalIsWritable, Field... fields);
+    void register(InclusionCondition condition, boolean finalIsWritable, Field... fields);
 
-    void registerClassLookup(MetadataCondition condition, String typeName);
+    void registerClassLookup(InclusionCondition condition, String typeName);
 
-    void registerFieldLookup(MetadataCondition condition, Class<?> declaringClass, String fieldName);
+    void registerFieldLookup(InclusionCondition condition, Class<?> declaringClass, String fieldName);
 
-    void registerMethodLookup(MetadataCondition condition, Class<?> declaringClass, String methodName, Class<?>... parameterTypes);
+    void registerMethodLookup(InclusionCondition condition, Class<?> declaringClass, String methodName, Class<?>... parameterTypes);
 
-    void registerConstructorLookup(MetadataCondition condition, Class<?> declaringClass, Class<?>... parameterTypes);
+    void registerConstructorLookup(InclusionCondition condition, Class<?> declaringClass, Class<?>... parameterTypes);
 }

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

@@ -45,16 +45,21 @@
 import java.util.stream.Collectors;
 
 import org.graalvm.nativeimage.ImageSingletons;
+import org.graalvm.nativeimage.hosted.InclusionCondition;
 
 public interface RuntimeSerializationSupport<C> {
 
     @SuppressWarnings("unchecked")
-    static RuntimeSerializationSupport<MetadataCondition> singleton() {
+    static RuntimeSerializationSupport<InclusionCondition> singleton() {
         return ImageSingletons.lookup(RuntimeSerializationSupport.class);
     }
 
     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);

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

@@ -45,18 +45,8 @@
 import org.graalvm.nativeimage.hosted.InclusionCondition;
 
 /**
- * A condition that describes if a reflectively-accessed element in Native Image is visible by the
- * user at run time.
- * <p>
- * Currently, there is only two types of condition:
- * <li><code>typeReached</code> (the default) that signifies that the type must be both reachable by
- * static analysis at build time, and reached at run time. A type is reached at run time, right
- * before the class-initialization routine starts for that type, or any of the type's subtypes are
- * reached.</li>
- * <li><code>typeReachable</code> (legacy) that signifies that the type must be reachable by static
- * analysis at build time.</li>
- * <p>
- * When {@link TypeCondition#runtimeChecked} is <code>true</code> denotes that this is a
+ * Type that represents both type-reached and type-reachable condition. When
+ * {@link TypeCondition#runtimeChecked} is <code>true</code> denotes that this is a
  * <code>typeReached</code> condition.
  */
 public class TypeCondition implements InclusionCondition {

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

@@ -32,7 +32,7 @@
 import java.util.function.Consumer;
 
 import org.graalvm.nativeimage.hosted.Feature;
-import org.graalvm.nativeimage.impl.MetadataCondition;
+import org.graalvm.nativeimage.hosted.InclusionCondition;
 import org.graalvm.nativeimage.impl.TypeCondition;
 
 import com.oracle.svm.core.util.VMError;
@@ -42,7 +42,7 @@ public abstract class ConditionalConfigurationRegistry {
     private Feature.BeforeAnalysisAccess beforeAnalysisAccess;
     private final Map<Class<?>, Collection<Runnable>> pendingReachabilityHandlers = new ConcurrentHashMap<>();
 
-    protected void registerConditionalConfiguration(MetadataCondition condition, Consumer<MetadataCondition> consumer) {
+    protected void registerConditionalConfiguration(InclusionCondition condition, Consumer<InclusionCondition> consumer) {
         Objects.requireNonNull(condition, "Cannot use null value as condition for conditional configuration. Please ensure that you register a non-null condition.");
         Objects.requireNonNull(consumer, "Cannot use null value as runnable for conditional configuration. Please ensure that you register a non-null runnable.");
         if (((TypeCondition) condition).isRuntimeChecked() && !((TypeCondition) condition).isAlwaysTrue()) {
@@ -53,25 +53,19 @@ protected void registerConditionalConfiguration(MetadataCondition condition, Con
              */
             ClassInitializationSupport.singleton().addForTypeReachedTracking(((TypeCondition) condition).getKey());
         }
-        if (MetadataCondition.alwaysTrue().equals(condition)) {
+        if (((TypeCondition) condition).isAlwaysTrue()) {
             /* analysis optimization to include new types as early as possible */
-            consumer.accept(MetadataCondition.alwaysTrue());
+            consumer.accept(InclusionCondition.alwaysTrue());
         } else {
-            MetadataCondition runtimeCondition;
-            if (((TypeCondition) condition).isRuntimeChecked()) {
-                runtimeCondition = condition;
-            } else {
-                runtimeCondition = MetadataCondition.alwaysTrue();
-            }
+            InclusionCondition runtimeCondition = ((TypeCondition) condition).isRuntimeChecked() ? condition : InclusionCondition.alwaysTrue();
+
             if (beforeAnalysisAccess == null) {
                 Collection<Runnable> handlers = pendingReachabilityHandlers.computeIfAbsent(((TypeCondition) condition).getKey(), key -> new ConcurrentLinkedQueue<>());
                 handlers.add(() -> consumer.accept(runtimeCondition));
             } else {
                 beforeAnalysisAccess.registerReachabilityHandler(access -> consumer.accept(runtimeCondition), ((TypeCondition) condition).getKey());
             }
-
         }
-
     }
 
     public void setAnalysisAccess(Feature.BeforeAnalysisAccess beforeAnalysisAccess) {