HHH-19993 Introduce AnnotationBasedUserType

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

Author: quaff

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

@@ -12,10 +12,12 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+import org.hibernate.AnnotationException;
 import org.hibernate.Incubating;
 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 +68,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;
@@ -1110,6 +1114,36 @@ 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<?, ?> ) {
+			if ( typeAnnotation == null ) {
+				throw new AnnotationException( 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() ) );
+			}
+			AnnotationBasedUserType<Annotation, ?> annotationBased = (AnnotationBasedUserType<Annotation, ?>) typeInstance;
+			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;
+				}
+
+				@Override
+				public Properties getParameters() {
+					return properties;
+				}
+			} );
+		}
+
 		if ( typeInstance instanceof TypeConfigurationAware configurationAware ) {
 			configurationAware.setTypeConfiguration( getTypeConfiguration() );
 		}

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

@@ -16,6 +16,7 @@
 import org.hibernate.resource.beans.internal.FallbackBeanInstanceProducer;
 import org.hibernate.resource.beans.spi.ManagedBean;
 import org.hibernate.resource.beans.spi.ProvidedInstanceManagedBeanImpl;
+import org.hibernate.usertype.AnnotationBasedUserType;
 import org.hibernate.usertype.ParameterizedType;
 import org.hibernate.usertype.UserCollectionType;
 
@@ -75,9 +76,9 @@ public static void injectParameters(Object type, Properties parameters) {
 		if ( type instanceof ParameterizedType parameterizedType ) {
 			parameterizedType.setParameterValues( parameters == null ? EMPTY_PROPERTIES : parameters );
 		}
-		else if ( parameters != null && !parameters.isEmpty() ) {
+		else if ( parameters != null && !parameters.isEmpty() && !( type instanceof AnnotationBasedUserType<?,?> ) ) {
 			throw new MappingException( "'UserType' implementation '" + type.getClass().getName()
-					+ "' does not implement 'ParameterizedType' but parameters were provided" );
+					+ "' does not implement 'ParameterizedType' or 'AnnotationBasedUserType' but parameters were provided" );
 		}
 	}
 

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,47 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.usertype;
+
+import org.hibernate.Incubating;
+import org.hibernate.annotations.Type;
+import org.hibernate.boot.spi.MetadataBuildingContext;
+import org.hibernate.models.spi.MemberDetails;
+import org.hibernate.service.ServiceRegistry;
+
+import java.util.Properties;
+
+/**
+ * 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();
+
+	/**
+	 * Access to the parameters.
+	 *
+	 * @see Type#parameters()
+	 */
+	Properties getParameters();
+
+}

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

@@ -8,12 +8,15 @@
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
+import org.hibernate.annotations.Parameter;
 import org.hibernate.annotations.Type;
 import org.hibernate.models.spi.MemberDetails;
 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 +39,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 +78,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 +133,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 +172,13 @@ public class MetaUserTypeTest {
 		boolean days() default false;
 	}
 
+	@Type(value = FourthPeriodType.class, parameters = @Parameter(name="foo", value ="bar"))
+	@Target({METHOD, FIELD})
+	@Retention(RUNTIME)
+	public @interface FourthTimePeriod {
+		boolean days() default false;
+	}
+
 	static class PeriodType extends AbstractPeriodType {
 
 		PeriodType(TimePeriod timePeriod) {
@@ -175,8 +206,25 @@ 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);
+			}
+			assertEquals( "bar", context.getParameters().get("foo") );
+		}
+	}
+
 	static abstract class AbstractPeriodType implements UserType<Period> {
-		private final boolean days;
+		boolean days;
 
 		AbstractPeriodType(boolean days) {
 			this.days = days;