ISSUE-32936 | Allow plugging in Hibernate ORM's TypeContributor and FunctionContributor

docs/src/main/asciidoc/hibernate-orm.adoc

@@ -559,6 +559,10 @@ See <<json_xml_serialization_deserialization>>.
 See <<multitenancy>>.
 `io.quarkus.hibernate.orm.runtime.tenant.TenantConnectionResolver`::
 See <<programmatically-resolving-tenants-connections>>.
+`org.hibernate.boot.model.FunctionContributor`::
+See <<custom-functions-and-types>>.
+`org.hibernate.boot.model.TypeContributor`::
+See <<custom-functions-and-types>>.
 
 [[persistence-unit-active]]
 === Activate/deactivate persistence units
@@ -1574,6 +1578,149 @@ public class ExampleTenantConnectionResolver implements TenantConnectionResolver
 }
 ----
 
+[[custom-functions-and-types]]
+=== Custom functions, types and mappings
+
+To register custom SQL functions or types, in Hibernate ORM, you can implement the standard Hibernate interfaces:
+
+* `org.hibernate.boot.model.FunctionContributor`
+* `org.hibernate.boot.model.TypeContributor`
+
+Creating an application-scoped bean that implements one of these interfaces and annotating it with `@PersistenceUnitExtension`
+(or `@PersistenceUnitExtension("nameOfYourPU")` for a <<multiple-persistence-units,named persistence unit>>)
+will automatically register it with the corresponding persistence unit.
+
+Here is an example of a custom function contributor:
+
+[source,java]
+----
+import java.util.List;
+import org.hibernate.boot.model.FunctionContributions;
+import org.hibernate.boot.model.FunctionContributor;
+import org.hibernate.query.sqm.function.AbstractSqmSelfRenderingFunctionDescriptor;
+import org.hibernate.query.sqm.produce.function.StandardArgumentsValidators;
+import org.hibernate.query.sqm.produce.function.StandardFunctionArgumentTypeResolvers;
+import org.hibernate.query.sqm.produce.function.StandardFunctionReturnTypeResolvers;
+import org.hibernate.sql.ast.SqlAstTranslator;
+import org.hibernate.sql.ast.spi.SqlAppender;
+import org.hibernate.sql.ast.tree.SqlAstNode;
+import org.hibernate.sql.ast.tree.expression.ReturnableType;
+import org.hibernate.sql.ast.tree.expression.SqlAstNodeRenderingMode;
+import org.hibernate.type.StandardBasicTypes;
+import org.hibernate.type.spi.TypeConfiguration;
+import io.quarkus.hibernate.orm.PersistenceUnitExtension;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+@PersistenceUnitExtension
+public class CustomFunctionContributor implements FunctionContributor {
+
+    @Override
+    public void contributeFunctions(FunctionContributions functionContributions) {
+        functionContributions.getFunctionRegistry().register(
+                "addHardcodedSuffix",
+                new HardcodedSuffixFunction(
+                        functionContributions.getTypeConfiguration(), "_some_suffix"));
+    }
+
+    private static final class HardcodedSuffixFunction extends AbstractSqmSelfRenderingFunctionDescriptor {
+        private final String suffix;
+
+        private HardcodedSuffixFunction(TypeConfiguration typeConfiguration, String suffix) {
+            super("addHardcodedSuffix",
+                    StandardArgumentsValidators.exactly(1),
+                    StandardFunctionReturnTypeResolvers.invariant(
+                            typeConfiguration.getBasicTypeRegistry().resolve(StandardBasicTypes.STRING)),
+                    StandardFunctionArgumentTypeResolvers.impliedOrInvariant(typeConfiguration, StandardBasicTypes.STRING)
+            );
+            this.suffix = suffix;
+        }
+
+        @Override
+        public void render(SqlAppender sqlAppender, List<? extends SqlAstNode> sqlAstArguments, ReturnableType<?> returnType,
+                           SqlAstTranslator<?> walker) {
+            sqlAppender.appendSql('(');
+            walker.render(sqlAstArguments.get(0), SqlAstNodeRenderingMode.DEFAULT);
+            sqlAppender.appendSql(" || '" + suffix + "')");
+        }
+    }
+}
+
+----
+
+And here is an example of a custom type contributor that registers a custom `UserType` (e.g. mapping a Boolean to "Y"/"N"):
+
+[source,java]
+----
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import org.hibernate.boot.model.TypeContributions;
+import org.hibernate.boot.model.TypeContributor;
+import org.hibernate.engine.spi.SharedSessionContractImplementor;
+import org.hibernate.service.ServiceRegistry;
+import org.hibernate.type.SqlTypes;
+import org.hibernate.type.descriptor.WrapperOptions;
+import org.hibernate.usertype.UserType;
+import io.quarkus.hibernate.orm.PersistenceUnitExtension;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+@PersistenceUnitExtension
+public class CustomTypeContributor implements TypeContributor {
+
+    @Override
+    public void contribute(TypeContributions typeContributions, ServiceRegistry serviceRegistry) {
+        // Registers the custom type so it can be used via @Type(value = BooleanYesNoType.class) on your entity property
+        typeContributions.getTypeConfiguration()
+                .getBasicTypeRegistry()
+                .register(new BooleanYesNoType(), "boolean_yes_no");
+    }
+
+    public static final class BooleanYesNoType implements UserType<Boolean> {
+        @Override
+        public int getSqlType() {
+            return SqlTypes.VARCHAR;
+        }
+
+        @Override
+        public Class<Boolean> returnedClass() {
+            return Boolean.class;
+        }
+
+        @Override
+        public Boolean nullSafeGet(ResultSet rs, int position, WrapperOptions options) throws SQLException {
+            String value = rs.getString(position);
+
+            if (value == null) {
+                return null;
+            }
+
+            return "Y".equalsIgnoreCase(value) || "true".equalsIgnoreCase(value);
+        }
+
+        @Override
+        public void nullSafeSet(PreparedStatement st, Boolean value, int position, WrapperOptions options) throws SQLException {
+            if (value == null) {
+                st.setNull(position, SqlTypes.VARCHAR);
+            } else {
+                st.setString(position, value ? "Y" : "N");
+            }
+        }
+
+        @Override
+        public Boolean deepCopy(Boolean value) {
+            return value;
+        }
+
+        @Override
+        public boolean isMutable() {
+            return false;
+        }
+    }
+}
+----
+
 [[interceptors]]
 == Interceptors
 

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/ClassNames.java

@@ -71,6 +71,8 @@ private static DotName createConstant(String fqcn) {
     public static final DotName FORMAT_MAPPER = createConstant("org.hibernate.type.format.FormatMapper");
     public static final DotName JSON_FORMAT = createConstant("io.quarkus.hibernate.orm.JsonFormat");
     public static final DotName XML_FORMAT = createConstant("io.quarkus.hibernate.orm.XmlFormat");
+    public static final DotName FUNCTION_CONTRIBUTOR = createConstant("org.hibernate.boot.model.FunctionContributor");
+    public static final DotName TYPE_CONTRIBUTOR = createConstant("org.hibernate.boot.model.TypeContributor");
 
     public static final List<DotName> GENERATORS = List.of(
             createConstant("org.hibernate.generator.Assigned"),

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmCdiProcessor.java

@@ -92,7 +92,9 @@ public class HibernateOrmCdiProcessor {
             ClassNames.TENANT_CONNECTION_RESOLVER,
             ClassNames.INTERCEPTOR,
             ClassNames.STATEMENT_INSPECTOR,
-            ClassNames.FORMAT_MAPPER);
+            ClassNames.FORMAT_MAPPER,
+            ClassNames.FUNCTION_CONTRIBUTOR,
+            ClassNames.TYPE_CONTRIBUTOR);
 
     @BuildStep
     AnnotationsTransformerBuildItem convertJpaResourceAnnotationsToQualifier(

extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfigPersistenceUnit.java

@@ -135,9 +135,11 @@ public interface HibernateOrmConfigPersistenceUnit {
      *
      * This setting is exposed mainly to allow registration of types, converters and SQL functions.
      * ====
+     * * @deprecated Use TypeContributor, FunctionContributor or AdditionalMappingContributor instead.
      *
      * @asciidoclet
      */
+    @Deprecated
     Optional<@WithConverter(TrimmedStringConverter.class) String> metadataBuilderContributor();
 
     /**

extensions/hibernate-orm/deployment/src/test/java/io/quarkus/hibernate/orm/functioncontributors/CustomFunctionContributor.java

@@ -0,0 +1,60 @@
+package io.quarkus.hibernate.orm.functioncontributors;
+
+import static org.hibernate.query.sqm.produce.function.FunctionParameterType.STRING;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import org.hibernate.boot.model.FunctionContributions;
+import org.hibernate.boot.model.FunctionContributor;
+import org.hibernate.metamodel.model.domain.ReturnableType;
+import org.hibernate.query.sqm.function.AbstractSqmSelfRenderingFunctionDescriptor;
+import org.hibernate.query.sqm.produce.function.StandardArgumentsValidators;
+import org.hibernate.query.sqm.produce.function.StandardFunctionArgumentTypeResolvers;
+import org.hibernate.query.sqm.produce.function.StandardFunctionReturnTypeResolvers;
+import org.hibernate.sql.ast.SqlAstNodeRenderingMode;
+import org.hibernate.sql.ast.SqlAstTranslator;
+import org.hibernate.sql.ast.spi.SqlAppender;
+import org.hibernate.sql.ast.tree.SqlAstNode;
+import org.hibernate.type.StandardBasicTypes;
+import org.hibernate.type.spi.TypeConfiguration;
+
+import io.quarkus.hibernate.orm.PersistenceUnitExtension;
+
+@ApplicationScoped
+@PersistenceUnitExtension
+public class CustomFunctionContributor implements FunctionContributor {
+    @Override
+    public void contributeFunctions(FunctionContributions functionContributions) {
+        functionContributions.getFunctionRegistry().register(
+                "addHardcodedSuffix",
+                new HardcodedSuffixFunction(
+                        functionContributions.getTypeConfiguration(), "_some_suffix"));
+    }
+
+    private static final class HardcodedSuffixFunction extends AbstractSqmSelfRenderingFunctionDescriptor {
+        private final String suffix;
+
+        private HardcodedSuffixFunction(TypeConfiguration typeConfiguration, String suffix) {
+            super("addHardcodedSuffix",
+                    StandardArgumentsValidators.exactly(1),
+                    StandardFunctionReturnTypeResolvers.invariant(
+                            typeConfiguration.getBasicTypeRegistry().resolve(StandardBasicTypes.STRING)),
+                    StandardFunctionArgumentTypeResolvers.impliedOrInvariant(typeConfiguration, STRING));
+
+            this.suffix = suffix;
+        }
+
+        @Override
+        public void render(
+                SqlAppender sqlAppender,
+                List<? extends SqlAstNode> sqlAstArguments,
+                ReturnableType<?> returnType,
+                SqlAstTranslator<?> walker) {
+            sqlAppender.appendSql('(');
+            walker.render(sqlAstArguments.get(0), SqlAstNodeRenderingMode.DEFAULT);
+            sqlAppender.appendSql(" || '" + suffix + "')");
+        }
+    }
+}

extensions/hibernate-orm/deployment/src/test/java/io/quarkus/hibernate/orm/functioncontributors/FunctionContributorTest.java

@@ -0,0 +1,35 @@
+package io.quarkus.hibernate.orm.functioncontributors;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import jakarta.inject.Inject;
+import jakarta.persistence.EntityManager;
+import jakarta.transaction.Transactional;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.test.QuarkusUnitTest;
+
+public class FunctionContributorTest {
+    @RegisterExtension
+    static QuarkusUnitTest runner = new QuarkusUnitTest()
+            .withApplicationRoot(jar -> jar
+                    .addClass(MyEntity.class)
+                    .addClass(CustomFunctionContributor.class));
+
+    @Inject
+    EntityManager entityManager;
+
+    @Test
+    @Transactional
+    public void test() {
+        MyEntity entity = new MyEntity();
+        entity.setName("some_name");
+        entityManager.persist(entity);
+
+        assertThat(entityManager.createQuery("select addHardcodedSuffix(e.name) from MyEntity e", String.class)
+                .getSingleResult())
+                .isEqualTo("some_name_some_suffix");
+    }
+}

extensions/hibernate-orm/deployment/src/test/java/io/quarkus/hibernate/orm/functioncontributors/MyEntity.java

@@ -0,0 +1,31 @@
+package io.quarkus.hibernate.orm.functioncontributors;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+
+@Entity
+public class MyEntity {
+    @Id
+    private long id;
+
+    private String name;
+
+    public MyEntity() {
+    }
+
+    public long getId() {
+        return id;
+    }
+
+    public void setId(long id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+}

extensions/hibernate-orm/deployment/src/test/java/io/quarkus/hibernate/orm/typecontributors/BooleanYesNoType.java

@@ -0,0 +1,52 @@
+package io.quarkus.hibernate.orm.typecontributors;
+
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+
+import org.hibernate.type.SqlTypes;
+import org.hibernate.type.descriptor.WrapperOptions;
+import org.hibernate.usertype.UserType;
+
+final class BooleanYesNoType implements UserType<Boolean> {
+
+    @Override
+    public int getSqlType() {
+        return SqlTypes.VARCHAR;
+    }
+
+    @Override
+    public Class<Boolean> returnedClass() {
+        return Boolean.class;
+    }
+
+    @Override
+    public Boolean nullSafeGet(ResultSet rs, int position, WrapperOptions options) throws SQLException {
+        String value = rs.getString(position);
+
+        if (value == null) {
+            return null;
+        }
+
+        return "Y".equalsIgnoreCase(value) || "true".equalsIgnoreCase(value);
+    }
+
+    @Override
+    public void nullSafeSet(PreparedStatement st, Boolean value, int position, WrapperOptions options) throws SQLException {
+        if (value == null) {
+            st.setNull(position, SqlTypes.VARCHAR);
+        } else {
+            st.setString(position, value ? "Y" : "N");
+        }
+    }
+
+    @Override
+    public Boolean deepCopy(Boolean value) {
+        return value;
+    }
+
+    @Override
+    public boolean isMutable() {
+        return false;
+    }
+}

extensions/hibernate-orm/deployment/src/test/java/io/quarkus/hibernate/orm/typecontributors/CustomTypeContributor.java

@@ -0,0 +1,20 @@
+package io.quarkus.hibernate.orm.typecontributors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import org.hibernate.boot.model.TypeContributions;
+import org.hibernate.boot.model.TypeContributor;
+import org.hibernate.service.ServiceRegistry;
+
+import io.quarkus.hibernate.orm.PersistenceUnitExtension;
+
+@ApplicationScoped
+@PersistenceUnitExtension
+public class CustomTypeContributor implements TypeContributor {
+    @Override
+    public void contribute(TypeContributions typeContributions, ServiceRegistry serviceRegistry) {
+        typeContributions.getTypeConfiguration()
+                .getBasicTypeRegistry()
+                .register(new BooleanYesNoType(), "boolean_yes_no");
+    }
+}