HHH-19993 Introduce AnnotationBasedUserType

Signed-off-by: Yanming Zhou <zhouyanming@gmail.com>

Author: quaff

documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc

@@ -2563,7 +2563,7 @@ include::{example-dir-basic-mapping}/generated/GeneratedTest.java[tags=mapping-g
 [[mapping-generated-custom]]
 ===== Custom generation strategy
 
-Hibernate also supports value generation via a pluggable API using `@ValueGenerationType` and `AnnotationBasedGenerator`
+Hibernate also supports value generation via a pluggable API using `@ValueGenerationType` and `AnnotationBasedUserType`
 allowing users to define any generation strategy they wish.
 
 Let's look at an example of generating UUID values. First the attribute mapping

hibernate-core/src/main/java/org/hibernate/mapping/BasicValue.java

@@ -66,6 +66,7 @@
 import org.hibernate.type.internal.ConvertedBasicTypeImpl;
 import org.hibernate.type.spi.TypeConfiguration;
 import org.hibernate.type.spi.TypeConfigurationAware;
+import org.hibernate.usertype.AnnotationBasedUserType;
 import org.hibernate.usertype.DynamicParameterizedType;
 import org.hibernate.usertype.UserType;
 
@@ -1106,10 +1107,15 @@ private Properties getCustomTypeProperties() {
 return properties;
 }
 
+@SuppressWarnings( { "unchecked", "rawtypes" } )
 private UserType<?> getConfiguredUserTypeBean(
 Class<? extends UserType<?>> explicitCustomType, Properties properties, Annotation typeAnnotation, Member member) {
 final var typeInstance = instantiateUserType( explicitCustomType, properties, typeAnnotation, member );
 
+if ( typeInstance instanceof AnnotationBasedUserType annotationBased && typeAnnotation != null ) {
+annotationBased.initialize( typeAnnotation, member, properties );
+}
+
 if ( typeInstance instanceof TypeConfigurationAware configurationAware ) {
 configurationAware.setTypeConfiguration( getTypeConfiguration() );
 }

hibernate-core/src/main/java/org/hibernate/usertype/AnnotationBasedUserType.java

@@ -0,0 +1,35 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.usertype;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Member;
+import java.util.Properties;
+
+
+/**
+ * A {@link UserType} which receives parameters from a custom annotation.
+ *
+ * @param <A> The user type annotation type supported by an implementation
+ * @param <J> The java type
+ *
+ * @author Yanming Zhou
+ *
+ * @since 7.3
+ */
+public interface AnnotationBasedUserType<A extends Annotation, J> extends UserType<J> {
+/**
+ * Initializes this generation strategy for the given annotation instance.
+ *
+ * @param annotation an instance of the user type annotation type. Typically,
+ * implementations will retrieve the annotation's attribute
+ * values and store them in fields.
+ * @param member the Java member annotated with the user type annotation.
+ * @param properties user type properties
+ * @throws org.hibernate.HibernateException in case an error occurred during initialization, e.g. if
+ * an implementation can't create a value for the given property type.
+ */
+void initialize(A annotation, Member member, Properties properties);
+}

hibernate-core/src/main/java/org/hibernate/usertype/UserType.java

@@ -243,6 +243,7 @@
  *
  * @see org.hibernate.type.Type
  * @see org.hibernate.type.CustomType
+ * @see org.hibernate.usertype.AnnotationBasedUserType
  *
  * @see org.hibernate.annotations.Type
  * @see org.hibernate.annotations.TypeRegistration

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/basic/bitset/MetaUserTypeTest.java

@@ -12,6 +12,7 @@
 import org.hibernate.testing.orm.junit.EntityManagerFactoryScope;
 import org.hibernate.testing.orm.junit.Jpa;
 import org.hibernate.type.descriptor.WrapperOptions;
+import org.hibernate.usertype.AnnotationBasedUserType;
 import org.hibernate.usertype.UserType;
 import org.junit.jupiter.api.Test;
 
@@ -27,6 +28,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
+import java.util.Properties;
 
 import static java.lang.Integer.parseInt;
 import static java.lang.annotation.ElementType.FIELD;
@@ -36,7 +38,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 @Jpa(annotatedClasses = {MetaUserTypeTest.Thing.class, MetaUserTypeTest.SecondThing.class,
-MetaUserTypeTest.ThirdThing.class, MetaUserTypeTest.Things.class})
+MetaUserTypeTest.ThirdThing.class, MetaUserTypeTest.FourthThing.class, MetaUserTypeTest.Things.class})
 public class MetaUserTypeTest {
 
 @Test void test(EntityManagerFactoryScope scope) {
@@ -75,6 +77,18 @@ public class MetaUserTypeTest {
 assertEquals( Period.of( 1, 2, 3 ), thing.period );
 assertEquals( Period.ofDays( 42 ), thing.days );
 } );
+
+scope.inTransaction( em -> {
+FourthThing thing = new FourthThing();
+thing.period = Period.of( 1, 2, 3 );
+thing.days = Period.ofDays( 42 );
+em.persist( thing );
+} );
+scope.inTransaction( em -> {
+FourthThing thing = em.find( FourthThing.class, 1 );
+assertEquals( Period.of( 1, 2, 3 ), thing.period );
+assertEquals( Period.ofDays( 42 ), thing.days );
+} );
 }
 
 @Test void testCollection(EntityManagerFactoryScope scope) {
@@ -118,6 +132,15 @@ public class MetaUserTypeTest {
 Period days;
 }
 
+@Entity static class FourthThing {
+@Id @GeneratedValue
+long id;
+@FourthTimePeriod
+Period period;
+@FourthTimePeriod(days = true)
+Period days;
+}
+
 @Entity static class Things {
 @Id @GeneratedValue
 long id;
@@ -148,6 +171,13 @@ public class MetaUserTypeTest {
 boolean days() default false;
 }
 
+@Type(FourthPeriodType.class)
+@Target({METHOD, FIELD})
+@Retention(RUNTIME)
+public @interface FourthTimePeriod {
+boolean days() default false;
+}
+
 static class PeriodType extends AbstractPeriodType {
 
 PeriodType(TimePeriod timePeriod) {
@@ -175,8 +205,20 @@ static class ThirdPeriodType extends AbstractPeriodType {
 
 }
 
+static class FourthPeriodType extends AbstractPeriodType implements AnnotationBasedUserType<FourthTimePeriod, Period> {
+
+FourthPeriodType() {
+super(false);
+}
+
+@Override
+public void initialize(FourthTimePeriod annotation, Member member, Properties properties) {
+days = annotation.days();
+}
+}
+
 static abstract class AbstractPeriodType implements UserType<Period> {
-private final boolean days;
+boolean days;
 
 AbstractPeriodType(boolean days) {
 this.days = days;