New API, within new metadata package.

Author: kimeta

sdk/mx.sdk/suite.py

@@ -976,6 +976,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,14 +41,10 @@
 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,
- * serialization, JNI access, resource access, and foreign access at runtime).
+ * serialization, JNI access, resource access, and foreign access at run time).
  * {@link AccessCondition} is used for programmatic metadata registration in conjunction with:
  * <ul>
  * <li>{@link ReflectiveAccess}</li>
@@ -67,7 +63,12 @@
  * </ul>
  * <p>
  * Conditions can only be created via the {@link #unconditional} and {@link #typeReached} factory
- * methods.
+ * methods. These methods are best used with static import methods. For example:
+ *
+ * <pre>{@code
+ * reflection.register(unconditional(), ReflectivelyAccessed.class);
+ * reflection.register(typeReached(ConditionType.class), ConditionallyAccessed.class)
+ * }</pre>
  *
  * @since 25.0
  */
@@ -86,46 +87,47 @@ static AccessCondition unconditional() {
     }
 
     /**
-     * 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.
+     * Creates the {@code typeReached} condition that is satisfied when the type is 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. Elements predicated with this condition
+     * will be included in the image only if the type is <em>reachable</em> at build time, but will
+     * be accessible when the type is <em>reached</em> at run time.
      * <p>
      * <strong>Example:</strong>
      * 
      * <pre>{@code
      * class SuperType {
      *     static {
-     *         // ConditionType reached (subtype reached) => metadata is available
+     *         // ConditionType reached (subtype reached) => element access allowed
      *     }
      * }
      * 
      * class ConditionType extends SuperType {
      *     static {
-     *         // ConditionType reached (before static initializer) => metadata is available
+     *         // ConditionType reached (before static initializer) => element access allowed
      *     }
      * 
      *     static ConditionType singleton() {
-     *         // ConditionType reached (already initialized) => metadata is available
+     *         // ConditionType reached (already initialized) => element access allowed
      *     }
      * }
      * 
      * public class App {
      *     public static void main(String[] args) {
-     *         // ConditionType not reached => metadata is not available
+     *         // ConditionType not reached => element access not allowed
      *         Class<?> clazz = ConditionType.class;
      *         // ConditionType not reached (ConditionType.class doesn't start class initialization)
-     *         // => metadata is not available
+     *         // => element access not allowed
      *         ConditionType.singleton();
-     *         // ConditionType reached (already initialized) => metadata is available
+     *         // ConditionType reached (already initialized) => element access allowed
      *     }
      * }
      * }</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.
+     * Array types (e.g., <code>int[]</code>) are never marked as reached and therefore cannot be
+     * used as the <code>type</code> in a condition.
      *
      * @param type the type that has to be reached for this condition to be satisfied, must not be
      *            {@code null}