HHH-19993 Introduce AnnotationBasedUserType

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

Author: quaff

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

@@ -16,6 +16,7 @@
 import org.hibernate.Internal;
 import org.hibernate.MappingException;
 import org.hibernate.models.spi.MemberDetails;
+import org.hibernate.service.ServiceRegistry;
 import org.hibernate.type.TimeZoneStorageStrategy;
 import org.hibernate.annotations.SoftDelete;
 import org.hibernate.annotations.SoftDeleteType;
@@ -66,13 +67,15 @@
 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;
 
 import com.fasterxml.classmate.ResolvedType;
 import jakarta.persistence.AttributeConverter;
 import jakarta.persistence.EnumType;
 import jakarta.persistence.TemporalType;
+import org.hibernate.usertype.UserTypeCreationContext;
 
 import static java.lang.Boolean.parseBoolean;
 import static org.hibernate.boot.model.convert.spi.ConverterDescriptor.TYPE_NAME_PREFIX;
@@ -1106,10 +1109,35 @@ private Properties getCustomTypeProperties() {
 return properties;
 }
 
+@SuppressWarnings( { "unchecked", "rawtypes" } )
 private UserType<?> getConfiguredUserTypeBean(
 Class<? extends UserType<?>> explicitCustomType, Properties properties, Annotation typeAnnotation, MemberDetails memberDetails) {
 final var typeInstance = instantiateUserType( explicitCustomType, properties, typeAnnotation, memberDetails );
 
+if ( typeInstance instanceof AnnotationBasedUserType annotationBased ) {
+if ( typeAnnotation == null ) {
+throw new MappingException( String.format( "'UserType' implementation '%s' implements '%s' but no custom annotation present,"
++ " please refer to the Javadoc of '%s'.",
+typeInstance.getClass().getName(), AnnotationBasedUserType.class.getName(), UserType.class.getName() ) );
+}
+annotationBased.initialize( typeAnnotation, new UserTypeCreationContext() {
+@Override
+public MetadataBuildingContext getBuildingContext() {
+return BasicValue.this.getBuildingContext();
+}
+
+@Override
+public ServiceRegistry getServiceRegistry() {
+return BasicValue.this.getServiceRegistry();
+}
+
+@Override
+public MemberDetails getMemberDetails() {
+return memberDetails;
+}
+} );
+}
+
 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 org.hibernate.Incubating;
+
+import java.lang.annotation.Annotation;
+
+
+/**
+ * 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
+ */
+@Incubating
+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 context a {@link UserTypeCreationContext}.
+ * @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, UserTypeCreationContext context);
+}

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

@@ -244,6 +244,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/main/java/org/hibernate/usertype/UserTypeCreationContext.java

@@ -0,0 +1,37 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.usertype;
+
+import org.hibernate.Incubating;
+import org.hibernate.boot.spi.MetadataBuildingContext;
+import org.hibernate.models.spi.MemberDetails;
+import org.hibernate.service.ServiceRegistry;
+
+/**
+ * Access to information useful during {@linkplain UserType} creation and initialization.
+ *
+ * @author Yanming Zhou
+ * @see AnnotationBasedUserType
+ *
+ * @since 7.3
+ */
+@Incubating
+public interface UserTypeCreationContext {
+/**
+ * Access to the {@link MetadataBuildingContext}.
+ */
+MetadataBuildingContext getBuildingContext();
+
+/**
+ * Access to available services.
+ */
+ServiceRegistry getServiceRegistry();
+
+/**
+ * Access to the {@link MemberDetails}.
+ */
+MemberDetails getMemberDetails();
+
+}

hibernate-core/src/test/java/org/hibernate/orm/test/inheritance/SingleTableAbstractDiscriminatorTests.java

@@ -40,7 +40,7 @@ void testNonCompliantModel(ServiceRegistryScope registryScope) {
 //
 //	> The DiscriminatorValue annotation can only be specified on a concrete entity class.
 //
- // we do not validate this though
+// we do not validate this though
 var model = new MetadataSources( registryScope.getRegistry() )
 .addAnnotatedClasses( Root.class, Trunk.class, Branch.class )
 .buildMetadata();

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

@@ -13,7 +13,9 @@
 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.hibernate.usertype.UserTypeCreationContext;
 import org.junit.jupiter.api.Test;
 
 import java.io.Serializable;
@@ -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,24 @@ static class ThirdPeriodType extends AbstractPeriodType {
 
 }
 
+static class FourthPeriodType extends AbstractPeriodType implements AnnotationBasedUserType<FourthTimePeriod, Period> {
+
+FourthPeriodType() {
+super(false);
+}
+
+@Override
+public void initialize(FourthTimePeriod timePeriod, UserTypeCreationContext context) {
+days = timePeriod.days();
+if ( !timePeriod.equals( ( (Field) context.getMemberDetails().toJavaMember() ).getAnnotation( FourthTimePeriod.class ) )) {
+// only for validation
+throw new IllegalArgumentException(context.getMemberDetails().toJavaMember() + " should be annotated with " + timePeriod);
+}
+}
+}
+
 static abstract class AbstractPeriodType implements UserType<Period> {
-private final boolean days;
+boolean days;
 
 AbstractPeriodType(boolean days) {
 this.days = days;