Review comments

Author: vjovanov

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

@@ -44,7 +44,7 @@
 
 /**
  * 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>
@@ -63,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
  */
@@ -82,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}

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

@@ -46,7 +46,7 @@
 import java.lang.invoke.MethodType;
 
 /**
- * This interface is used to register classes, methods, and fields for foreign access at runtime. An
+ * This interface is used to register classes, methods, and fields for foreign access at run time. An
  * instance of this interface is acquired via
  * {@link Feature.AfterRegistrationAccess#getForeignAccess()}.
  * <p>
@@ -76,9 +76,9 @@ 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.
+     * options at run time.
      * <p>
-     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * Even though this method is weakly typed for compatibility reasons, run-time 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.
      *
@@ -95,9 +95,9 @@ public interface ForeignAccess {
      * 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.
+     * and options at run time.
      * <p>
-     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * Even though this method is weakly typed for compatibility reasons, run-time 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.
      *
@@ -124,7 +124,7 @@ public interface ForeignAccess {
      * method handle to denoted static method.
      * </p>
      * <p>
-     * Even though this method is weakly typed for compatibility reasons, runtime checks will be
+     * Even though this method is weakly typed for compatibility reasons, run-time 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>

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

@@ -78,23 +78,23 @@
  */
 public interface JNIAccess {
     /**
-     * Registers the provided classes for JNI access at runtime, if the {@code condition} is
+     * Registers the provided classes for JNI access at run time, if the {@code condition} is
      * satisfied.
      *
      * @since 25.0
      */
     void register(AccessCondition condition, Class<?>... classes);
 
     /**
-     * Registers the provided methods for JNI access at runtime, if the {@code condition} is
+     * Registers the provided methods for JNI access at run time, if the {@code condition} is
      * satisfied.
      *
      * @since 25.0
      */
     void register(AccessCondition condition, Executable... methods);
 
     /**
-     * Registers the provided fields for JNI access at runtime, if the {@code condition} is
+     * Registers the provided fields for JNI access at run time, if the {@code condition} is
      * satisfied.
      *
      * @since 25.0

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

@@ -40,34 +40,38 @@
  */
 package org.graalvm.nativeimage.dynamicaccess;
 
-import org.graalvm.nativeimage.hosted.Feature;
-
 import java.lang.reflect.Executable;
 import java.lang.reflect.Field;
 
+import org.graalvm.nativeimage.hosted.Feature;
+
 /**
  * This interface is used to register classes, methods, and fields for use with the
- * {@link java.lang.reflect} API at runtime, and for serialization at runtime. An instance of this
+ * {@link java.lang.reflect} API at run time, and for serialization at run time. An instance of this
  * interface is acquired via {@link Feature.AfterRegistrationAccess#getReflectiveAccess()}.
  * <p>
  * All methods in {@link ReflectiveAccess} require a {@link AccessCondition} as their first
- * parameter. A class and its members will be registered for dynamic access only if the specified
- * condition is satisfied.
+ * parameter. A class and its members will be accessible at run-time only if the specified condition
+ * is satisfied.
  *
  * <h3>How to use</h3>
  *
- * {@link ReflectiveAccess} should only be used during {@link Feature#afterRegistration}. Any
- * attempt to register metadata in any other phase will result in an error.
+ * {@link ReflectiveAccess} should only be used during {@link Feature#afterRegistration}. Attempts
+ * to register metadata in any other phase of the {@link Feature} API will result in an error.
  * <p>
  * <strong>Example:</strong>
  *
  * <pre>{@code @Override
  * public void afterRegistration(AfterRegistrationAccess access) {
  *     ReflectionAccess reflection = access.getReflectionAccess();
+ *
  *     AccessCondition condition = AccessCondition.typeReached(ConditionType.class);
  *     reflection.register(condition, Foo.class, Bar.class);
+ *
  *     reflection.register(AccessCondition.unconditional(), Foo.class.getMethod("method"));
+ *
  *     reflection.registerUnsafeAllocation(condition, Foo.class);
+ *
  *     Class<?> proxyClass = reflection.registerProxy(condition, Interface1.class, Interface2.class);
  *     reflection.registerForSerialization(AccessCondition.unconditional(), proxyClass);
  * }
@@ -78,19 +82,25 @@
 public interface ReflectiveAccess {
 
     /**
-     * Registers the provided classes for reflection at runtime, if the {@code condition} is
-     * satisfied. This means all reflection methods defined by the {@link java.lang.Class} are
-     * accessible at runtime for those classes.
+     * Registers the provided classes for reflection at run time, if the {@code condition} is
+     * satisfied. This means all reflection methods defined by the {@link java.lang.Class} (except
+     * {@link Class#arrayType()}) are accessible at run time for those classes.
      * <p>
-     * If a class is not registered for reflection at runtime, {@link Class#forName} will throw
-     * {@link ClassNotFoundException}.
+     * If a class is not registered for reflection at run time, the following methods will throw
+     * {@link ClassNotFoundException}:
+     * <ul>
+     * <li>{@link Class#forName(String)}</li>
+     * <li>{@link Class#forName(Module, String)}</li>
+     * <li>{@link Class#forName(String, boolean, ClassLoader)}</li>
+     * <li>{@link ClassLoader#loadClass(String)}</li>
+     * </ul>
      *
      * @since 25.0
      */
     void register(AccessCondition condition, Class<?>... classes);
 
     /**
-     * Registers a class with the provided {@code className} for reflection at runtime, if the
+     * Registers a class with the provided {@code className} for reflection at run time, if the
      * {@code condition} is satisfied. This method should be used when
      * {@code --exact-reachability-metadata} is set: it makes calls to
      * {@code Class.forName(className)} throw {@link ClassNotFoundException} instead of throwing
@@ -103,29 +113,20 @@ public interface ReflectiveAccess {
     void registerClassLookup(AccessCondition condition, String className);
 
     /**
-     * Registers the provided {@code classes} for unsafe allocation at runtime, if the
-     * {@code condition} is satisfied. Unsafe allocation can happen via
-     * {@link sun.misc.Unsafe#allocateInstance(Class)} or from native code via
-     * {@code AllocObject(jClass)}.
-     *
-     * @since 25.0
-     */
-    void registerUnsafeAllocation(AccessCondition condition, Class<?>... classes);
-
-    /**
-     * Registers the provided {@code methods} for reflective invocation at runtime, if the
-     * {@code condition} is satisfied. This method also registers the declaring classes of the
-     * provided methods for reflection at runtime. The methods will be invocable at runtime via
+     * Registers the provided {@code executables} (methods and constructors) for reflective
+     * invocation at run time, if the {@code condition} is satisfied. This method also registers the
+     * declaring classes of the provided executables for reflection at run time. The executables
+     * will be invocable at run time via
      * {@link java.lang.reflect.Method#invoke(java.lang.Object, java.lang.Object...)}.
      *
      * @since 25.0
      */
-    void register(AccessCondition condition, Executable... methods);
+    void register(AccessCondition condition, Executable... executables);
 
     /**
-     * Registers the provided {@code fields} for reflective access at runtime, if the
+     * Registers the provided {@code fields} for reflective access at run time, if the
      * {@code condition} is satisfied. This method also registers the declaring classes of the
-     * provided fields for reflection at runtime. The fields will be accessible at runtime via
+     * provided fields for reflection at run time. The fields will be accessible at run time via
      * {@link java.lang.reflect.Field#set(java.lang.Object, java.lang.Object)} and
      * {@link java.lang.reflect.Field#get(Object)}.
      *
@@ -134,8 +135,8 @@ public interface ReflectiveAccess {
     void register(AccessCondition condition, Field... fields);
 
     /**
-     * Registers the provided classes for serialization at runtime, if the {@code condition} is
-     * satisfied. This method also registers the provided classes for reflection at runtime.
+     * Registers the provided classes for serialization at run time, if the {@code condition} is
+     * satisfied. This method also registers the provided classes for reflection at run time.
      *
      * @since 25.0
      */
@@ -145,13 +146,14 @@ public interface ReflectiveAccess {
      * Registers a {@link java.lang.reflect.Proxy} class in the system classloader that implements
      * the specified {@code interfaces}, if the {@code condition} is satisfied. The proxy class is
      * fully specified by the interfaces it implements, and proxy instances matching that
-     * specification can be created at runtime. The returned proxy class can be used in registration
-     * for reflection and serialization at runtime. <blockquote> <strong>NOTE</strong>: The order of
-     * the interfaces provided in the {@code interfaces} parameter is significant; different
-     * orderings will produce distinct proxy classes. </blockquote>
+     * specification can be created at run time. The returned proxy class can be used in
+     * registration for reflection and serialization at run time. <blockquote>
+     * <strong>NOTE</strong>: The order of the interfaces provided in the {@code interfaces}
+     * parameter is significant; different orderings will produce distinct proxy classes.
+     * </blockquote>
      * <p>
      * <strong>Example</strong>:
-     * 
+     *
      * <pre>{@code
      * Class<?> proxyClass = reflection.registerProxy(AccessCondition.unconditional(), Interface1.class, Interface2.class);
      * reflection.register(AccessCondition.unconditional(), proxyClass);
@@ -164,4 +166,14 @@ public interface ReflectiveAccess {
      * @since 25.0
      */
     Class<?> registerProxy(AccessCondition condition, Class<?>... interfaces);
+
+    /**
+     * Registers the provided {@code classes} for unsafe allocation at run time, if the
+     * {@code condition} is satisfied. Unsafe allocation can happen via
+     * {@link sun.misc.Unsafe#allocateInstance(Class)} or from native code via
+     * {@code AllocObject(jClass)}.
+     *
+     * @since 25.0
+     */
+    void registerForUnsafeAllocation(AccessCondition condition, Class<?>... classes);
 }

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

@@ -40,33 +40,37 @@
  */
 package org.graalvm.nativeimage.dynamicaccess;
 
-import org.graalvm.nativeimage.hosted.Feature;
-
 import java.util.ResourceBundle;
 
+import org.graalvm.nativeimage.hosted.Feature;
+
 /**
  * This interface is used to register Java resources and {@link java.util.ResourceBundle}s that
- * should be accessible at runtime. An instance of this interface is acquired via
+ * should be accessible at run time. An instance of this interface is acquired via
  * {@link Feature.AfterRegistrationAccess#getResourceAccess()}.
  * <p>
  * All methods in {@link ResourceAccess} require a {@link AccessCondition} as their first parameter.
- * Resources will be registered for runtime access only if the specified condition is satisfied.
+ * Resources will be registered for run-time access only if the specified <code>condition</code> is
+ * satisfied.
  *
  * <h3>How to use</h3>
  *
- * {@link ResourceAccess} should only be used during {@link Feature#afterRegistration}. Any attempt
- * to register metadata in any other phase will result in an error.
+ * {@link ResourceAccess} should only be used during {@link Feature#afterRegistration}. Attempts to
+ * register metadata in any other phase of the {@link Feature} API will result in an error.
  * <p>
  * <strong>Example:</strong>
  *
- * <pre>{@code
- * @Override
+ * <pre>{@code @Override
  * public void afterRegistration(AfterRegistrationAccess access) {
  *     ResourceAccess resources = access.getResourceAccess();
  *     AccessCondition condition = AccessCondition.typeReached(ConditionType.class);
+ *
  *     resources.register(condition, "example/**");
+ *
  *     resources.register(AccessCondition.unconditional(), "example/directory/concreteResource");
+ *
  *     resources.register(condition, "example/concreteResourceStar\\*");
+ *
  *     try {
  *         ResourceBundle bundle2 = ResourceBundle.getBundle("bundlePath1");
  *         resources.registerResourceBundle(condition, bundle1, bundle2);
@@ -82,7 +86,7 @@ public interface ResourceAccess {
 
     /**
      * Registers resources matching the specified {@code glob} in the provided {@code module} for
-     * runtime access, if the {@code condition} is satisfied.
+     * run-time access, if the {@code condition} is satisfied.
      * <p>
      * The {@code glob} uses a subset of
      * <a href="https://en.wikipedia.org/wiki/Glob_(programming)">glob-pattern</a> rules for
@@ -142,7 +146,7 @@ public interface ResourceAccess {
     void register(AccessCondition condition, Module module, String glob);
 
     /**
-     * Registers resources matching the specified {@code glob} from the classpath for runtime
+     * Registers resources matching the specified {@code glob} from the classpath for run-time
      * access, if the {@code condition} is satisfied.
      * <p>
      * The {@code glob} uses a subset of
@@ -202,15 +206,14 @@ default void register(AccessCondition condition, String glob) {
     }
 
     /**
-     * Registers the provided {@link java.util.ResourceBundle}s for runtime access, if the
+     * Registers the provided {@link java.util.ResourceBundle}s for run-time access, if the
      * {@code condition} is satisfied. Each {@link java.util.ResourceBundle} must be obtained using
      * any version of the {@link java.util.ResourceBundle#getBundle} method. A bundle created in any
      * other way will result in an error.
      *
      * <blockquote> <strong>Recommended use to avoid crashes during image building:</strong>
      * 
-     * <pre>{@code
-     * @Override
+     * <pre>{@code @Override
      * public void afterRegistration(AfterRegistrationAccess access) {
      *     ResourceAccess resources = access.getResourceAccess();
      *     AccessCondition condition = AccessCondition.typeReached(ConditionType.class);