Merge pull request #360 from graalvm/Preserve_add_ReportDynamicAccess

Preserve demo: add report dynamic access

Author: ban-mi

native-image/preserve-package/README.md

@@ -1,165 +1,225 @@
-# Using Native Image `Preserve` Option
+# GraalVM Native Image: Using the `-H:Preserve` Option
 
-Reflection is a feature of the Java programming language that enables a running Java program to examine and modify attributes of its classes, interfaces, fields, and methods.
-GraalVM Native Image automatically supports some uses of reflection.
-Native Image uses static analysis to identify what classes, methods, and fields are needed by an application, but it may not detect some elements of your application that are accessed using the [Java Reflection API](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/reflect/package-summary.html).
-You must declare any undetected reflection usage to the `native-image` tool, either as metadata ([precomputed in code or as JSON configuration files](https://www.graalvm.org/latest/reference-manual/native-image/metadata/)) or using the `-H:Preserve` option (experimental in GraalVM for JDK 25).
+This demo shows how to use GraalVM Native Image’s experimental -H:Preserve
+option to ensure classes accessed via reflection are included in your native
+executable. You’ll learn how to identify missing classes, use build reports, and
+apply the new option for reliable runtime behavior.
 
-This guide demonstrates how to declare reflection configuration using the `-H:Preserve` option.
+## Introduction
 
-## Preparation
+Java reflection lets a running program inspect and invoke classes, fields, and
+methods at runtime. GraalVM Native Image supports many common cases
+automatically by performing static analysis to discover what must be included in
+the native executable. However, elements that are only accessed reflectively may
+not be detected and therefore can be missing at runtime unless you declare them.
 
-1. Download and install the latest GraalVM for JDK 25 (or the early access build before 2025-09-16) using [SDKMAN!](https://sdkman.io/).
+You can declare reflective access either via metadata (in code or JSON) or,
+starting in GraalVM 25, via the experimental `-H:Preserve` option. This demo
+shows how to use `-H:Preserve` to keep specific packages available at runtime.
 
-    ```shell
-    sdk install java 25.ea.29-graal
-    ```
+## Prerequisites
 
-2. Download or clone this repository, and navigate into the `native-image/preserve-package` directory:
+- GraalVM 25
+- Maven 3.9+
+- SDKMAN! (recommended for installing GraalVM)
 
-    ```shell
-    git clone https://github.com/graalvm/graalvm-demos
-    cd graalvm-demos/native-image/preserve-package
-    ```
+Install GraalVM 25 with SDKMAN!:
 
-## Example Using Reflection on the JVM
+```bash
+sdk install java 25-graal
+sdk use java 25-graal
+```
 
-The `ReflectionExample` class uses command line argument values to reflectively create an instance of a class and invoke a method with a provided argument. The core code is:
+Clone the example repository:
 
-```java
-    Class<?> clazz = Class.forName(className);
-    Method method = clazz.getDeclaredMethod(methodName, String.class);
-    Object result = method.invoke(null, input);
+```bash
+git clone https://github.com/graalvm/graalvm-demos
+cd graalvm-demos/native-image/preserve-package
 ```
 
-This approach works on the JVM as long as the required classes and methods are available on the classpath.
+## How the Example Works
 
-1. Compile the application and create a JAR file using Maven:
+`ReflectionExample` uses command-line arguments to reflectively:
+- load a class by name,
+- find a method,
+- and invoke it with a string argument.
 
-    ```shell
-    ./mvnw package
-    ```
+The core code is:
 
-2. Run `ReflectionExample` (the JAR entry point) to invoke the `StringReverser` action:
+```java
+Class<?> clazz = Class.forName(className);
+Method method = clazz.getDeclaredMethod(methodName, String.class);
+Object result = method.invoke(null, input);
+```
 
-    ```shell
-    $JAVA_HOME/bin/java -jar target/preserve-package-1.0-SNAPSHOT.jar \
-       org.graalvm.example.action.StringReverser reverse "hello"
-    ```
+Two sample actions are provided:
+- `org.graalvm.example.action.StringReverser#reverse(String)`
+- `org.graalvm.example.action.StringCapitalizer#capitalize(String)`
 
-    Expected output:
+This works on the JVM as long as those classes are on the classpath.
 
-    ```shell
-    olleh
-    ```
+### Run on the JVM
 
-3. Run the same command for the `StringCapitalizer` action:
+1. Build the JAR:
 
-    ```shell
-    $JAVA_HOME/bin/java -jar target/preserve-package-1.0-SNAPSHOT.jar \
-       org.graalvm.example.action.StringCapitalizer capitalize "hello"
-    ```
+```bash
+./mvnw package
+```
 
-    Expected output:
+2. Invoke `StringReverser`:
 
-    ```shell
-    HELLO
-    ```
+```bash
+java -jar target/preserve-package-1.0-SNAPSHOT.jar \
+  org.graalvm.example.action.StringReverser reverse "hello"
+```
 
-## GraalVM Native Image
+Expected output:
 
-You can compile the project with Native Image, specifying `ReflectionExample` as the main entry point.
-The [_pom.xml_](pom.xml) file uses the [Native Build Tools Maven plugin](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html) to compile the project with the `native-image` tool.
+```
+olleh
+```
 
-1. Build a native executable using the `native-default` profile (see the [_pom.xml_](pom.xml) file):
+3. Invoke `StringCapitalizer`:
 
-    ```shell
-    ./mvnw package -Pnative-default
-    ```
+```bash
+java -jar target/preserve-package-1.0-SNAPSHOT.jar \
+  org.graalvm.example.action.StringCapitalizer capitalize "hello"
+```
 
-2. Run the resulting `example-default` native executable:
+Expected output:
 
-    ```bash
-    ./target/example-default \
-       org.graalvm.example.action.StringReverser reverse "hello"
-    ```
+```
+HELLO
+```
+
+## Build a Native Image
+
+The project uses the Native Build Tools Maven plugin to drive `native-image`.
+The `native-default` profile produces an executable without additional
+reflection configuration.
 
-    You will see a `ClassNotFoundException` similar to:
+1. Build:
 
-    ```shell
-    Exception in thread "main" java.lang.ClassNotFoundException: org.graalvm.example.action.StringReverser
-        at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.ClassForNameSupport.forName(ClassForNameSupport.java:339)
-        at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.ClassForNameSupport.forName(ClassForNameSupport.java:298)
-        at java.base@25/java.lang.Class.forName(DynamicHub.java:1758)
-        at java.base@25/java.lang.Class.forName(DynamicHub.java:1704)
-        at java.base@25/java.lang.Class.forName(DynamicHub.java:1691)
-        at org.graalvm.example.ReflectionExample.main(ReflectionExample.java:56)
-        at java.base@25/java.lang.invoke.LambdaForm$DMH/sa346b79c.invokeStaticInit(LambdaForm$DMH)
-    ```
+```bash
+./mvnw package -Pnative-default
+```
 
-This error occurs because the `native-image` tool's static analysis did not determine that your application uses the `StringReverser` class, and did not include it in the native executable.
+2. Run:
 
-## Native Image Using `-H:Preserve`
+```bash
+./target/example-default \
+  org.graalvm.example.action.StringReverser reverse "hello"
+```
 
-GraalVM for JDK 25 introduces the `-H:Preserve` option.
+You should see a `ClassNotFoundException` similar to:
 
-This option lets you instruct the `native-image` tool to keep entire packages, modules, or all classes on the classpath.
+```
+Exception in thread "main" java.lang.ClassNotFoundException: org.graalvm.example.action.StringReverser
+  at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.ClassForNameSupport.forName(ClassForNameSupport.java:339)
+  ...
+  at org.graalvm.example.ReflectionExample.main(ReflectionExample.java:56)
+```
 
-<!-- This can result in larger application size. -->
+This happens because static analysis did not discover that `StringReverser` (and
+`StringCapitalizer`) are used via reflection, so they were not included.
 
-In this example, both classes used via reflection are in the `org.graalvm.example.action` package.
-You can use `-H:Preserve=package` to keep all of the classes in that package in the native executable, even if static analysis cannot discover them.
+## Identify Dynamic Access With the Build Report
 
-Native Image command line arguments can be specified as `<buildArgs>` in the `native-maven-plugin` configuration.
-Since the `-H:Preserve` option is experimental, you must also enable its use with `-H:+UnlockExperimentalVMOptions`.
-For the complete plugin configuration, see the [_pom.xml_](pom.xml) file:
+GraalVM 25 adds an experimental reporting option to help you find dynamic access
+before it breaks at runtime. With `-H:+ReportDynamicAccess`, in conjunction with
+`--emit=build-report`, the Native Image [build
+report](https://www.graalvm.org/latest/reference-manual/native-image/overview/build-report/)
+highlights reflective usage present in the image.
+
+The `native-default` profile already enables this feature:
 
 ```xml
-    <configuration>
-    ...
-        <buildArgs>
-            <buildArg>-H:+UnlockExperimentalVMOptions</buildArg>
-            <buildArg>-H:Preserve=package=org.graalvm.example.action</buildArg>
-        </buildArgs>
-    </configuration>
+<buildArgs>
+  <buildArg>-H:+UnlockExperimentalVMOptions</buildArg>
+  <buildArg>-H:+ReportDynamicAccess</buildArg>
+  <buildArg>--emit=build-report</buildArg>
+</buildArgs>
 ```
 
-1. Build a native executable using the `native-preserve` profile, which adds `-H:Preserve=package=org.graalvm.example.action` when running the `native-image` tool:
+After building, open the report, `target/example-default-build-report.html`, and navigate to the “Dynamic Access” tab to review reflection usage in `ReflectionExample#main`.
+
+
+The report highlights code that needs to be reviewed to ensure successful
+runtime execution of the application. In this application, the classes loaded
+via `Class.forName(...)` need to be included in the executable.
+
+![Native Image Build Report - Dynamic Access](build-report.jpeg)
 
-    ```shell
-    ./mvnw package -Pnative-preserve
-    ```
+## Fix It With ‘-H:Preserve’ (Experimental)
+
+GraalVM 25 introduces the experimental `-H:Preserve` option to keep entire
+packages, modules, or all classes on the classpath.
+
+In this project, both action classes are in the `org.graalvm.example.action`
+package so `package=org.graalvm.example.action` can be added to the
+`-H:Preserve` option.  The Maven `native-preserve` profile adds the necessary
+`native-image` command line args:
+
+```xml
+<buildArgs>
+  <buildArg>-H:+UnlockExperimentalVMOptions</buildArg>
+  <buildArg>-H:Preserve=package=org.graalvm.example.action</buildArg>
+</buildArgs>
+```
 
-2. Run the new `example-preserve` executable to confirm the previously missing `StringReverser` class and its methods are now included:
+1. Build with preserve:
 
-    ```shell
-    ./target/example-preserve \
-       org.graalvm.example.action.StringReverser reverse "hello"
-    ```
+```bash
+./mvnw package -Pnative-preserve
+```
 
-    Expected output:
+2. Run `StringReverser`:
 
-    ```shell
-    olleh
-    ```
+```bash
+./target/example-preserve \
+  org.graalvm.example.action.StringReverser reverse "hello"
+```
 
-3. Run the executable to confirm the `StringCapitalizer` class works too:
+Expected output:
 
-    ```shell
-    ./target/example-preserve \
-       org.graalvm.example.action.StringCapitalizer capitalize "hello"
-    ```
+```
+olleh
+```
 
-    Expected output:
+3. Run `StringCapitalizer`:
 
-    ```shell
-    HELLO
-    ```
+```bash
+./target/example-preserve \
+  org.graalvm.example.action.StringCapitalizer capitalize "hello"
+```
 
-As demonstrated, `-H:Preserve` provides an easy way to ensure that Native Image includes classes not discovered by static analysis.
+Expected output:
 
-### Related Documentation
+```
+HELLO
+```
 
-* [Reachability Metadata: Reflection](https://www.graalvm.org/latest/reference-manual/native-image/metadata/)
-* [Assisted Configuration with Tracing Agent](https://www.graalvm.org/latest/reference-manual/native-image/metadata/AutomaticMetadataCollection/#tracing-agent)
-* [Java Reflection API](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/reflect/package-summary.html)
+As shown:
+- `-H:+ReportDynamicAccess` helps identify code paths involving reflection.
+- `-H:Preserve` makes it straightforward to include the required classes when
+  static analysis alone cannot find them.
+
+## Tips
+
+- Always include `-H:+UnlockExperimentalVMOptions` when using experimental
+  options like `-H:Preserve` or `-H:+ReportDynamicAccess`.
+- If you maintain larger apps, start with the dynamic access report to scope
+  what needs preserving, then apply `-H:Preserve` to the smallest package(s)
+  that cover your use cases.
+- For fine-grained control or for libraries you don’t own, consider JSON
+  reachability metadata as a complement or alternative.
+
+## Related Documentation
+
+- Reachability Metadata (Reflection):
+  https://www.graalvm.org/latest/reference-manual/native-image/metadata/
+- Assisted Configuration with Tracing Agent:
+  https://www.graalvm.org/latest/reference-manual/native-image/metadata/AutomaticMetadataCollection/#tracing-agent
+- Java Reflection API (JDK 25):
+  https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/reflect/package-summary.html
+  - Native Image Build Report: https://www.graalvm.org/latest/reference-manual/native-image/overview/build-report/

native-image/preserve-package/build-report.jpeg

@@ -37,6 +37,11 @@
             <configuration>
               <mainClass>org.graalvm.example.ReflectionExample</mainClass>
               <imageName>example-default</imageName>
+              <buildArgs>
+                <buildArg>-H:+UnlockExperimentalVMOptions</buildArg>
+                <buildArg>-H:+ReportDynamicAccess</buildArg>
+                <buildArg>--emit=build-report</buildArg>
+              </buildArgs>
             </configuration>
           </plugin>
         </plugins>
@@ -66,6 +71,8 @@
               <buildArgs>
                 <buildArg>-H:+UnlockExperimentalVMOptions</buildArg>
                 <buildArg>-H:Preserve=package=org.graalvm.example.action</buildArg>
+                <buildArg>-H:+ReportDynamicAccess</buildArg>
+                <buildArg>--emit=build-report</buildArg>
               </buildArgs>
             </configuration>
           </plugin>