Update GraalVM processor docs for Java 17 and record support

Document the Java 17 requirement for graalvm-annotations-processor 1.6.0, show updated Gradle usage, and describe automatic declared-constructor reflection metadata for Java records.

Author: mfriesen

README.md

@@ -1,21 +1,105 @@
-# Gradle Graalvm Annotations Processor
+# GraalVM Annotations Processor
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Gradle Annotations Processor for [FormKiQ's Graalvm Annotations](https://github.com/formkiq/graalvm-annotations). The annotations are used to generate a [Graalvm Reflection File](https://github.com/oracle/graal/blob/master/substratevm/Reflection.md).
+Annotation processor for [FormKiQ's GraalVM Annotations](https://github.com/formkiq/graalvm-annotations). The processor scans supported annotations at compile time and generates a GraalVM native-image reflection configuration file.
 
-The generated file can be found in ```$buildDir/classes/java/main/META-INF/graal/reflect.json```.
+The generated file is written to:
 
-## Gradle Installation
+```text
+$buildDir/classes/java/main/META-INF/native-image/<package>/reflect-config.json
+```
+
+## Requirements
+
+Version 1.6.0 and later requires Java 17 or newer to run the annotation processor.
+
+Use version 1.5.x if your build must run the annotation processor on Java 11.
+
+## Installation
 
-Add the following to your build.gradle to enable processing [FormKiQ's Graalvm Annotations](https://github.com/formkiq/graalvm-annotations).
+Add the annotations library and annotation processor to your Gradle build:
 
+```gradle
+dependencies {
+    implementation 'com.formkiq:graalvm-annotations:1.2.0'
+    annotationProcessor 'com.formkiq:graalvm-annotations-processor:1.6.0'
+}
 ```
+
+For Gradle Kotlin DSL:
+
+```kotlin
 dependencies {
-    annotationProcessor 'com.formkiq:graalvm-annotations-processor:1.1.1'
-    <!-- Replace 1.1.1 with the version you want to use -->
+    implementation("com.formkiq:graalvm-annotations:1.2.0")
+    annotationProcessor("com.formkiq:graalvm-annotations-processor:1.6.0")
 }
 ```
 
+## Usage
+
+Annotate a class or record with `@Reflectable`:
+
+```java
+import com.formkiq.graalvm.annotations.Reflectable;
+
+@Reflectable
+public record Event(String name) {
+}
+```
+
+The processor generates a `reflect-config.json` entry similar to:
+
+```json
+[
+  {
+    "name": "sample.Event",
+    "allDeclaredConstructors": true,
+    "allPublicConstructors": true,
+    "allDeclaredMethods": true,
+    "allDeclaredFields": true,
+    "allPublicFields": true,
+    "allPublicMethods": true
+  }
+]
+```
+
+You can override the generated reflection flags:
+
+```java
+@Reflectable(
+    allDeclaredConstructors = true,
+    allPublicConstructors = false,
+    allDeclaredMethods = true,
+    allDeclaredFields = true)
+public final class Event {
+}
+```
+
+## Java Records
+
+Version 1.6.0 and later automatically sets `allDeclaredConstructors` to `true` for Java records annotated with `@Reflectable` or referenced through `@ReflectableClass`.
+
+This is required by libraries such as Gson 2.13, which use the canonical record constructor through `Class.getDeclaredConstructor(...)` when deserializing records in GraalVM native images.
+
+## Build and Test
+
+Run the test suite with Java 17 or newer:
+
+```bash
+./gradlew test
+```
+
+Publish locally for testing with downstream projects:
+
+```bash
+./gradlew publishToMavenLocal
+```
+
 ## Samples
-See [Samples](https://github.com/formkiq/graalvm-annotations-processor/tree/master/samples) for examples on how to use the Graalvm Annotations and Processor.
+
+See [Samples](https://github.com/formkiq/graalvm-annotations-processor/tree/master/samples) for examples on how to use the GraalVM annotations and processor.
+
+## License
+
+This project is licensed under the Apache License 2.0.

build.gradle

@@ -10,7 +10,7 @@ plugins {
 }
 
 group 'com.formkiq'
-version '1.5.2'
+version '1.6.0'
 
 dependencies {
 	annotationProcessor group: 'com.google.auto.service', name: 'auto-service', version: '1.1.1'

src/main/java/com/formkiq/graalvm/processors/GraalvmReflectAnnontationProcessor.java

@@ -66,7 +66,7 @@
     "com.formkiq.graalvm.annotations.ReflectableClasses",
     "com.formkiq.graalvm.annotations.ReflectableClass",
     "com.formkiq.graalvm.annotations.ReflectableClass.ReflectableClasses"})
-@SupportedSourceVersion(SourceVersion.RELEASE_11)
+@SupportedSourceVersion(SourceVersion.RELEASE_17)
 public class GraalvmReflectAnnontationProcessor extends AbstractProcessor {
 
   /** The inner class separator character: '$'. */
@@ -280,6 +280,17 @@ private Reflect processClass(final Reflect reflect, final Reflectable reflectabl
     return reflect;
   }
 
+  /**
+   * Process Record Class.
+   *
+   * @param reflect {@link Reflect}
+   * @param reflectable {@link Reflectable}
+   * @return {@link Reflect}
+   */
+  private Reflect processRecordClass(final Reflect reflect, final Reflectable reflectable) {
+    return processClass(reflect, reflectable).allDeclaredConstructors(Boolean.TRUE);
+  }
+
   /**
    * Process Class.
    *
@@ -300,6 +311,17 @@ private Reflect processClass(final Reflect reflect, final ReflectableClass refle
     return reflect;
   }
 
+  /**
+   * Process Record Class.
+   *
+   * @param reflect {@link Reflect}
+   * @param reflectable {@link ReflectableClass}
+   * @return {@link Reflect}
+   */
+  private Reflect processRecordClass(final Reflect reflect, final ReflectableClass reflectable) {
+    return processClass(reflect, reflectable).allDeclaredConstructors(Boolean.TRUE);
+  }
+
   /**
    * Process Imported Class using {@link Class}.
    *
@@ -313,6 +335,9 @@ private void processImportedClass(final String clazz) {
 
       if (reflectable != null) {
         processClass(reflect, reflectable);
+        if (forName.isRecord()) {
+          reflect.allDeclaredConstructors(Boolean.TRUE);
+        }
       }
 
       for (Field field : forName.getDeclaredFields()) {
@@ -424,7 +449,8 @@ private void processingReflectable(final RoundEnvironment roundEnv) {
             reflect.addMethod(methodName, parameterTypes);
             break;
           default:
-            reflect = processClass(reflect, reflectable);
+            reflect = isRecord(element) ? processRecordClass(reflect, reflectable)
+                : processClass(reflect, reflectable);
             break;
         }
       }
@@ -465,12 +491,14 @@ private String getPackage(final Element element) {
   private void processReflectableClass(final ReflectableClass reflectable) {
 
     String className = null;
+    boolean isRecord = false;
     try {
       reflectable.className();
     } catch (MirroredTypeException e) {
 
       TypeMirror typeMirror = e.getTypeMirror();
       TypeElement asTypeElement = asTypeElement(typeMirror);
+      isRecord = isRecord(asTypeElement);
 
       className = asTypeElement.getQualifiedName().toString();
 
@@ -482,7 +510,8 @@ private void processReflectableClass(final ReflectableClass reflectable) {
     }
 
     Reflect reflect = getReflect(className);
-    reflect = processClass(reflect, reflectable);
+    reflect =
+        isRecord ? processRecordClass(reflect, reflectable) : processClass(reflect, reflectable);
 
     for (ReflectableField field : reflectable.fields()) {
       LOGGER.log(LOGLEVEL, "adding Field " + field.name() + " to " + className);
@@ -542,6 +571,11 @@ private String removePartsContainingDotFollowedByCapital(final String input) {
         .collect(Collectors.joining("."));
   }
 
+  private boolean isRecord(final Element element) {
+    return "RECORD".equals(element.getKind().name()) || element.getEnclosedElements().stream()
+        .anyMatch(e -> "RECORD_COMPONENT".equals(e.getKind().name()));
+  }
+
   /** Write Output File. */
   private void writeOutput() {
 

src/test/java/com/formkiq/graalvm/processors/GraalvmReflectAnnontationProcessorTest.java

@@ -830,7 +830,7 @@ public record TestRecord(String name) {}
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicConstructors"));
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicMethods"));
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicFields"));
-    assertEquals(Boolean.FALSE, map.get(0).get("allDeclaredConstructors"));
+    assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredConstructors"));
     assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredMethods"));
     assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredFields"));
   }
@@ -864,17 +864,17 @@ public record NestedTestRecord(String name) {
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicConstructors"));
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicMethods"));
     assertEquals(Boolean.TRUE, map.get(0).get("allPublicFields"));
-    assertEquals(Boolean.FALSE, map.get(0).get("allDeclaredConstructors"));
+    assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredConstructors"));
     assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredMethods"));
     assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredFields"));
 
     assertEquals("com.example.TestRecord$NestedTestRecord", map.get(1).get("name"));
-    assertEquals(Boolean.TRUE, map.get(0).get("allPublicConstructors"));
-    assertEquals(Boolean.TRUE, map.get(0).get("allPublicMethods"));
-    assertEquals(Boolean.TRUE, map.get(0).get("allPublicFields"));
-    assertEquals(Boolean.FALSE, map.get(0).get("allDeclaredConstructors"));
-    assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredMethods"));
-    assertEquals(Boolean.TRUE, map.get(0).get("allDeclaredFields"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allPublicConstructors"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allPublicMethods"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allPublicFields"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allDeclaredConstructors"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allDeclaredMethods"));
+    assertEquals(Boolean.TRUE, map.get(1).get("allDeclaredFields"));
   }
 
   /**