add ours typed-ids-index-java-classes-processor module

fprochazka · fprochazka · commit 1365a8783607 · 2025-04-13T19:12:26.000+02:00
diff --git a/README.md b/README.md
@@ -141,16 +141,69 @@ data class User(id: Id) {
 }
 ```
 
-## Usage: Enabling automatic type registration with Hibernate ORM
+## Typed IDs indexing at compile time
 
-Install the [newest version](https://central.sonatype.com/artifact/org.atteo.classindex/classindex) of [org.atteo.classindex:classindex](https://github.com/atteo/classindex), and register it as an annotation processor.
-The classes of this library are annotated with `@IndexSubclasses`, so once the classindex library is correctly installed,
-you should see `META-INF/services/org.framefork.typedIds.uuid.ObjectUuid` being populated somewhere in your build output directory.
-The `ObjectUuidTypesContributor` should then read it, and register the types automatically when Hibernate ORM is initialized.
+This library provides a mechanism to index your ID classes at compile time, which is useful for pleasant integrations with various frameworks.
 
-When used with a Kotlin project, you might want to explicitly add also a `kapt("org.atteo.classindex:classindex")` dependency.
+### Setting up subtype indexing in a Java project
 
-Without the automatic registration, the field has to be annotated like this
+Set up the `org.framefork:typed-ids-index-java-classes-processor` as an annotation processor.
+
+It's based on [org.atteo.classindex:classindex](https://github.com/atteo/classindex), and when executed,
+it writes (somewhere in your build output directory) to `META-INF/services/org.framefork.typedIds.uuid.ObjectUuid` or `META-INF/services/org.framefork.typedIds.bigint.ObjectBigIntId`,
+which can be later read by the standard `java.util.ServiceLoader` mechanism.
+
+With Gradle, register the processor like this:
+
+```kotlin
+dependencies {
+    annotationProcessor("org.framefork:typed-ids-index-java-classes-processor")
+    testAnnotationProcessor("org.framefork:typed-ids-index-java-classes-processor")
+}
+```
+
+With Maven, you can register it as an optional dependency if annotation processors discovery works in your project
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.framefork</groupId>
+        <artifactId>typed-ids-index-java-classes-processor</artifactId>
+        <optional>true</optional>
+    </dependency>
+</dependencies>
+```
+
+Or if you want to be safe, you can register the processor explicitly
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <annotationProcessorPaths>
+            <path>
+                <groupId>org.framefork</groupId>
+                <artifactId>typed-ids-index-java-classes-processor</artifactId>
+            </path>
+        </annotationProcessorPaths>
+    </configuration>
+</plugin>
+```
+
+### Setting up subtype indexing in a Kotlin project
+
+With Kotlin, you have to register the indexer as KAPT processor:
+
+```kotlin
+dependencies {
+    kapt("org.framefork:typed-ids-index-java-classes-processor") // instead of annotationProcessor(...)
+}
+```
+
+## Usage: Automatic type registration with Hibernate ORM
+
+Without the Typed IDs indexing at compile time, the field has to be annotated like this (the `@Type(...)` is the important part):
 
 ```java
 @Entity
@@ -169,7 +222,9 @@ public class User
         // ...
 ```
 
-But with the class indexer installed, The system will know that the `User.Id` should be handled by `ObjectUuidType` and the `@Type(...)` can be dropped.
+But with the index, the `ObjectUuidTypesContributor` reads it, and registers the types automatically when Hibernate ORM is initialized.
+
+With the classes indexed, the system will know that the `User.Id` should be handled by `ObjectUuidType` and the `@Type(...)` can be dropped.
 This also simplifies usage on every other place, where Hibernate might need to resolve a type for the `Id` instance, like queries.
 
 ## More examples
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,8 +1,6 @@
 [versions]
-kotlin = "2.0.20"
 googleAutoService = "1.1.1"
 errorProne = "2.35.1"
-ateoClassindex = "3.13"
 junit-jupiter = "5.10.3"
 jackson = "2.18.1"
 testcontainers = "1.20.3"
@@ -15,7 +13,7 @@ jackson-annotations = { group = "com.fasterxml.jackson.core", name = "jackson-an
 autoService-processor = { group = "com.google.auto.service", name = "auto-service", version.ref = "googleAutoService" }
 autoService-annotations = { group = "com.google.auto.service", name = "auto-service-annotations", version.ref = "googleAutoService" }
 errorprone-annotations = { group = "com.google.errorprone", name = "error_prone_annotations", version.ref = "errorProne" }
-ateoClassindex = { group = "org.atteo.classindex", name = "classindex", version.ref = "ateoClassindex" }
+ateoClassindex = { group = "org.atteo.classindex", name = "classindex", version = "3.13" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }
 assertj = { module = "org.assertj:assertj-core", version = "3.11.1" }
 testcontainers-bom = { module = "org.testcontainers:testcontainers-bom", version.ref = "testcontainers" }
diff --git a/modules/typed-ids-hibernate-62/build.gradle.kts b/modules/typed-ids-hibernate-62/build.gradle.kts
@@ -6,7 +6,6 @@ dependencies {
     api(project(":typed-ids"))
     api(libs.hibernate.orm.v62)
     api(libs.hypersistence.utils.hibernate62)
-    api(libs.ateoClassindex)
 
     compileOnly(libs.jetbrains.annotations)
 
diff --git a/modules/typed-ids-hibernate-62/src/main/java/org/framefork/typedIds/bigint/hibernate/ObjectBigIntIdTypesContributor.java b/modules/typed-ids-hibernate-62/src/main/java/org/framefork/typedIds/bigint/hibernate/ObjectBigIntIdTypesContributor.java
@@ -2,7 +2,6 @@
 
 import com.google.auto.service.AutoService;
 import org.framefork.typedIds.TypedIdsRegistry;
-import org.framefork.typedIds.common.ReflectionHacks;
 import org.hibernate.boot.model.TypeContributions;
 import org.hibernate.boot.model.TypeContributor;
 import org.hibernate.service.ServiceRegistry;
@@ -15,8 +14,6 @@
 public class ObjectBigIntIdTypesContributor implements TypeContributor
 {
 
-    private static final boolean CLASS_INDEX_PRESENT = ReflectionHacks.classExists("org.atteo.classindex.ClassIndex");
-
     @Override
     public void contribute(
         final TypeContributions typeContributions,
@@ -28,10 +25,6 @@ public void contribute(
 
     private void contributeIndexedTypes(final TypeContributions typeContributions)
     {
-        if (!CLASS_INDEX_PRESENT) {
-            return;
-        }
-
         TypeConfiguration typeConfiguration = typeContributions.getTypeConfiguration();
         JdbcType bigintJdbcType = typeConfiguration.getJdbcTypeRegistry().getDescriptor(SqlTypes.BIGINT);
 
diff --git a/modules/typed-ids-hibernate-62/src/main/java/org/framefork/typedIds/uuid/hibernate/ObjectUuidTypesContributor.java b/modules/typed-ids-hibernate-62/src/main/java/org/framefork/typedIds/uuid/hibernate/ObjectUuidTypesContributor.java
@@ -2,7 +2,6 @@
 
 import com.google.auto.service.AutoService;
 import org.framefork.typedIds.TypedIdsRegistry;
-import org.framefork.typedIds.common.ReflectionHacks;
 import org.framefork.typedIds.uuid.hibernate.jdbc.BinaryUuidJdbcType;
 import org.framefork.typedIds.uuid.hibernate.jdbc.NativeUuidJdbcType;
 import org.hibernate.boot.model.TypeContributions;
@@ -30,8 +29,6 @@ public class ObjectUuidTypesContributor implements TypeContributor
      */
     private static final DatabaseVersion MARIADB_NATIVE_UUID_SINCE = DatabaseVersion.make(10, 7);
 
-    private static final boolean CLASS_INDEX_PRESENT = ReflectionHacks.classExists("org.atteo.classindex.ClassIndex");
-
     @Override
     public void contribute(
         final TypeContributions typeContributions,
@@ -65,10 +62,6 @@ private void remapUuidType(final TypeContributions typeContributions, final Serv
 
     private void contributeIndexedTypes(final TypeContributions typeContributions)
     {
-        if (!CLASS_INDEX_PRESENT) {
-            return;
-        }
-
         TypeConfiguration typeConfiguration = typeContributions.getTypeConfiguration();
         JdbcType uuidJdbcType = typeConfiguration.getJdbcTypeRegistry().getDescriptor(SqlTypes.UUID);
 
diff --git a/modules/typed-ids-hibernate-63/build.gradle.kts b/modules/typed-ids-hibernate-63/build.gradle.kts
@@ -6,7 +6,6 @@ dependencies {
     api(project(":typed-ids"))
     api(libs.hibernate.orm.v63)
     api(libs.hypersistence.utils.hibernate63)
-    api(libs.ateoClassindex)
 
     compileOnly(libs.jetbrains.annotations)
 
diff --git a/modules/typed-ids-hibernate-63/src/main/java/org/framefork/typedIds/bigint/hibernate/ObjectBigIntIdTypesContributor.java b/modules/typed-ids-hibernate-63/src/main/java/org/framefork/typedIds/bigint/hibernate/ObjectBigIntIdTypesContributor.java
@@ -2,7 +2,6 @@
 
 import com.google.auto.service.AutoService;
 import org.framefork.typedIds.TypedIdsRegistry;
-import org.framefork.typedIds.common.ReflectionHacks;
 import org.hibernate.boot.model.TypeContributions;
 import org.hibernate.boot.model.TypeContributor;
 import org.hibernate.service.ServiceRegistry;
@@ -15,8 +14,6 @@
 public class ObjectBigIntIdTypesContributor implements TypeContributor
 {
 
-    private static final boolean CLASS_INDEX_PRESENT = ReflectionHacks.classExists("org.atteo.classindex.ClassIndex");
-
     @Override
     public void contribute(
         final TypeContributions typeContributions,
@@ -28,10 +25,6 @@ public void contribute(
 
     private void contributeIndexedTypes(final TypeContributions typeContributions)
     {
-        if (!CLASS_INDEX_PRESENT) {
-            return;
-        }
-
         TypeConfiguration typeConfiguration = typeContributions.getTypeConfiguration();
         JdbcType bigintJdbcType = typeConfiguration.getJdbcTypeRegistry().getDescriptor(SqlTypes.BIGINT);
 
diff --git a/modules/typed-ids-hibernate-63/src/main/java/org/framefork/typedIds/uuid/hibernate/ObjectUuidTypesContributor.java b/modules/typed-ids-hibernate-63/src/main/java/org/framefork/typedIds/uuid/hibernate/ObjectUuidTypesContributor.java
@@ -2,7 +2,6 @@
 
 import com.google.auto.service.AutoService;
 import org.framefork.typedIds.TypedIdsRegistry;
-import org.framefork.typedIds.common.ReflectionHacks;
 import org.framefork.typedIds.uuid.hibernate.jdbc.BinaryUuidJdbcType;
 import org.framefork.typedIds.uuid.hibernate.jdbc.NativeUuidJdbcType;
 import org.hibernate.boot.model.TypeContributions;
@@ -30,8 +29,6 @@ public class ObjectUuidTypesContributor implements TypeContributor
      */
     private static final DatabaseVersion MARIADB_NATIVE_UUID_SINCE = DatabaseVersion.make(10, 7);
 
-    private static final boolean CLASS_INDEX_PRESENT = ReflectionHacks.classExists("org.atteo.classindex.ClassIndex");
-
     @Override
     public void contribute(
         final TypeContributions typeContributions,
@@ -65,10 +62,6 @@ private void remapUuidType(final TypeContributions typeContributions, final Serv
 
     private void contributeIndexedTypes(final TypeContributions typeContributions)
     {
-        if (!CLASS_INDEX_PRESENT) {
-            return;
-        }
-
         TypeConfiguration typeConfiguration = typeContributions.getTypeConfiguration();
         JdbcType uuidJdbcType = typeConfiguration.getJdbcTypeRegistry().getDescriptor(SqlTypes.UUID);
 
diff --git a/modules/typed-ids-index-java-classes-processor/build.gradle.kts b/modules/typed-ids-index-java-classes-processor/build.gradle.kts
@@ -0,0 +1,17 @@
+plugins {
+    id("framefork.java-public")
+}
+
+dependencies {
+    api(project(":typed-ids"))
+
+    api(libs.errorprone.annotations)
+    api(libs.ateoClassindex)
+
+    compileOnly(libs.jetbrains.annotations)
+
+    compileOnly(libs.autoService.annotations)
+    annotationProcessor(libs.autoService.processor)
+}
+
+project.description = "TypeIds for safer code - Java Compiler Annotation Processor for indexing your TypedId classes"
diff --git a/modules/typed-ids-index-java-classes-processor/src/main/java/org/framefork/typedIds/TypedIdsClassIndexProcessor.java b/modules/typed-ids-index-java-classes-processor/src/main/java/org/framefork/typedIds/TypedIdsClassIndexProcessor.java
@@ -0,0 +1,21 @@
+package org.framefork.typedIds;
+
+import com.google.auto.service.AutoService;
+import org.atteo.classindex.processor.ClassIndexProcessor;
+import org.framefork.typedIds.bigint.ObjectBigIntId;
+import org.framefork.typedIds.uuid.ObjectUuid;
+
+import javax.annotation.processing.Processor;
+
+@AutoService(Processor.class)
+public class TypedIdsClassIndexProcessor extends ClassIndexProcessor
+{
+
+    @SuppressWarnings("rawtypes")
+    public TypedIdsClassIndexProcessor()
+    {
+        indexSubclasses(ObjectUuid.class);
+        indexSubclasses(ObjectBigIntId.class);
+    }
+
+}
diff --git a/modules/typed-ids/build.gradle.kts b/modules/typed-ids/build.gradle.kts
@@ -8,7 +8,6 @@ dependencies {
     compileOnly(libs.uuidGenerator)
     compileOnly(libs.hypersistence.tsid)
 
-    compileOnly(libs.ateoClassindex)
     compileOnly(libs.jetbrains.annotations)
 
     compileOnly(libs.autoService.annotations)
diff --git a/modules/typed-ids/src/main/java/org/framefork/typedIds/TypedIdsRegistry.java b/modules/typed-ids/src/main/java/org/framefork/typedIds/TypedIdsRegistry.java
@@ -7,6 +7,11 @@
 
 import java.util.List;
 
+/**
+ * This only works when the subtypes of the TypedIds are indexed in compile time.
+ * <p>
+ * Investigate the <code>typed-ids-index-java-classes-processor</code> module of this library.
+ */
 @SuppressWarnings("rawtypes")
 public final class TypedIdsRegistry
 {
diff --git a/modules/typed-ids/src/main/java/org/framefork/typedIds/bigint/ObjectBigIntId.java b/modules/typed-ids/src/main/java/org/framefork/typedIds/bigint/ObjectBigIntId.java
@@ -1,7 +1,6 @@
 package org.framefork.typedIds.bigint;
 
 import com.google.errorprone.annotations.Immutable;
-import org.atteo.classindex.IndexSubclasses;
 import org.framefork.typedIds.TypedId;
 import org.framefork.typedIds.common.LazyValue;
 import org.jspecify.annotations.NonNull;
@@ -15,7 +14,6 @@
 /**
  * Wraps long
  */
-@IndexSubclasses
 @Immutable
 public abstract class ObjectBigIntId<SelfType extends ObjectBigIntId<SelfType>> implements TypedId<SelfType>
 {
diff --git a/modules/typed-ids/src/main/java/org/framefork/typedIds/common/ReflectionHacks.java b/modules/typed-ids/src/main/java/org/framefork/typedIds/common/ReflectionHacks.java
@@ -2,6 +2,7 @@
 
 import org.intellij.lang.annotations.Language;
 import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
 
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodHandles;
@@ -17,18 +18,26 @@ private ReflectionHacks()
     {
     }
 
-    public static boolean classExists(
+    @Nullable
+    @SuppressWarnings("unchecked")
+    public static <T> Class<T> classForName(
         @Language("jvm-class-name") final String className
     )
     {
         try {
-            Class.forName(className, false, ReflectionHacks.class.getClassLoader());
-            return true;
-        } catch (ClassNotFoundException e) {
-            return false;
+            return (Class<T>) Class.forName(className, false, ReflectionHacks.class.getClassLoader());
+        } catch (ClassNotFoundException | NoClassDefFoundError ignored) {
+            return null;
         }
     }
 
+    public static boolean classExists(
+        @Language("jvm-class-name") final String className
+    )
+    {
+        return classForName(className) != null;
+    }
+
     public static Class<?> getFieldType(
         @Language("jvm-class-name") final String className,
         final String propertyName
diff --git a/modules/typed-ids/src/main/java/org/framefork/typedIds/common/ServiceLoaderUtils.java b/modules/typed-ids/src/main/java/org/framefork/typedIds/common/ServiceLoaderUtils.java
diff --git a/modules/typed-ids/src/main/java/org/framefork/typedIds/uuid/ObjectUuid.java b/modules/typed-ids/src/main/java/org/framefork/typedIds/uuid/ObjectUuid.java
diff --git a/testing/testing-typed-ids-hibernate-62-indexed/build.gradle.kts b/testing/testing-typed-ids-hibernate-62-indexed/build.gradle.kts
diff --git a/testing/testing-typed-ids-hibernate-63-indexed/build.gradle.kts b/testing/testing-typed-ids-hibernate-63-indexed/build.gradle.kts
diff --git a/testing/testing-typed-ids-hibernate-64-indexed/build.gradle.kts b/testing/testing-typed-ids-hibernate-64-indexed/build.gradle.kts
diff --git a/testing/testing-typed-ids-hibernate-65-indexed/build.gradle.kts b/testing/testing-typed-ids-hibernate-65-indexed/build.gradle.kts
diff --git a/testing/testing-typed-ids-hibernate-66-indexed/build.gradle.kts b/testing/testing-typed-ids-hibernate-66-indexed/build.gradle.kts
