HHH-18497 Add xmlcomment function

beikov · beikov · commit f9a725e9d9bc · 2024-09-21T04:19:52.000+02:00
diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
@@ -2172,6 +2172,7 @@ it is necessary to enable the `hibernate.query.hql.xml_functions_enabled` config
 | Function | Purpose
 
 | `xmlelement()` | Constructs an XML element from arguments
+| `xmlcomment()` | Constructs an XML comment from the single argument
 |===
 
 
@@ -2209,6 +2210,21 @@ include::{xml-example-dir-hql}/XmlElementTest.java[tags=hql-xmlelement-attribute
 
 WARNING: SAP HANA, MySQL, MariaDB, H2 and HSQLDB do not support this function.
 
+[[hql-xmlcomment-function]]
+===== `xmlcomment()`
+
+Constructs an XML comment from the single string argument.
+
+[[hql-xmlcomment-example]]
+====
+[source, java, indent=0]
+----
+include::{xml-example-dir-hql}/XmlCommentTest.java[tags=hql-xmlcomment-example]
+----
+====
+
+WARNING: SAP HANA, MySQL, MariaDB, H2 and HSQLDB do not support this function.
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/DB2LegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/DB2LegacyDialect.java
@@ -442,6 +442,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 	}
 
 	@Override
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java
@@ -419,6 +419,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			}
 
 			functionFactory.xmlelement_h2();
+			functionFactory.xmlcomment();
 		}
 		else {
 			functionFactory.listagg_groupConcat();
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java
@@ -327,6 +327,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 	}
 
 	@Override
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java
@@ -670,6 +670,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonArrayInsert_postgresql();
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/SQLServerLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/SQLServerLegacyDialect.java
@@ -414,6 +414,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonArrayInsert_sqlserver();
 		}
 		functionFactory.xmlelement_sqlserver();
+		functionFactory.xmlcomment_sqlserver();
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
 			functionFactory.jsonArrayAgg_sqlserver( getVersion().isSameOrAfter( 16 ) );
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/DB2Dialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/DB2Dialect.java
@@ -427,6 +427,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/H2Dialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/H2Dialect.java
@@ -354,6 +354,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 
 		functionFactory.xmlelement_h2();
+		functionFactory.xmlcomment();
 	}
 
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java
@@ -417,6 +417,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonArrayInsert_oracle();
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java
@@ -631,6 +631,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonArrayInsert_postgresql();
 
 		functionFactory.xmlelement();
+		functionFactory.xmlcomment();
 
 		functionFactory.makeDateTimeTimestamp();
 		// Note that PostgreSQL doesn't support the OVER clause for ordered set-aggregate functions
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/SQLServerDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/SQLServerDialect.java
@@ -432,6 +432,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonArrayInsert_sqlserver();
 		}
 		functionFactory.xmlelement_sqlserver();
+		functionFactory.xmlcomment_sqlserver();
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
 			functionFactory.jsonArrayAgg_sqlserver( getVersion().isSameOrAfter( 16 ) );
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java
@@ -4121,4 +4121,26 @@ public void xmlelement_h2() {
 	public void xmlelement_sqlserver() {
 		functionRegistry.register( "xmlelement", new SQLServerXmlElementFunction( typeConfiguration ) );
 	}
+
+	/**
+	 * Standard xmlcomment() function
+	 */
+	public void xmlcomment() {
+		functionRegistry.namedDescriptorBuilder( "xmlcomment" )
+				.setExactArgumentCount( 1 )
+				.setParameterTypes( STRING )
+				.setInvariantType( typeConfiguration.getBasicTypeRegistry().resolve( String.class, SqlTypes.SQLXML ) )
+				.register();
+	}
+
+	/**
+	 * Standard xmlcomment() function
+	 */
+	public void xmlcomment_sqlserver() {
+		functionRegistry.patternDescriptorBuilder( "xmlcomment", "cast(('<!--'+?1+'-->') AS xml)" )
+				.setExactArgumentCount( 1 )
+				.setParameterTypes( STRING )
+				.setInvariantType( typeConfiguration.getBasicTypeRegistry().resolve( String.class, SqlTypes.SQLXML ) )
+				.register();
+	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/query/criteria/HibernateCriteriaBuilder.java b/hibernate-core/src/main/java/org/hibernate/query/criteria/HibernateCriteriaBuilder.java
@@ -4055,6 +4055,14 @@ default <E> JpaPredicate collectionOverlapsNullable(Collection<E> collection1, E
 	@Incubating
 	JpaXmlElementExpression xmlelement(String elementName);
 
+	/**
+	 * Creates an XML comment with the given argument as content.
+	 *
+	 * @since 7.0
+	 */
+	@Incubating
+	JpaExpression<String> xmlcomment(String comment);
+
 	@Override
 	JpaPredicate and(List<Predicate> restrictions);
 
diff --git a/hibernate-core/src/main/java/org/hibernate/query/criteria/spi/HibernateCriteriaBuilderDelegate.java b/hibernate-core/src/main/java/org/hibernate/query/criteria/spi/HibernateCriteriaBuilderDelegate.java
@@ -3638,4 +3638,10 @@ public JpaExpression<String> jsonMergepatch(String document, Expression<?> patch
 	public JpaXmlElementExpression xmlelement(String elementName) {
 		return criteriaBuilder.xmlelement( elementName );
 	}
+
+	@Override
+	@Incubating
+	public JpaExpression<String> xmlcomment(String comment) {
+		return criteriaBuilder.xmlcomment( comment );
+	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/NodeBuilder.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/NodeBuilder.java
@@ -753,6 +753,9 @@ <T> SqmJsonValueExpression<T> jsonValue(
 	@Override
 	SqmXmlElementExpression xmlelement(String elementName);
 
+	@Override
+	SqmExpression<String> xmlcomment(String comment);
+
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	// Covariant overrides
 
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmCriteriaNodeBuilder.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmCriteriaNodeBuilder.java
@@ -5687,4 +5687,13 @@ public SqmXmlElementExpression xmlelement(String elementName) {
 				queryEngine
 		);
 	}
+
+	@Override
+	public SqmExpression<String> xmlcomment(String comment) {
+		return getFunctionDescriptor( "xmlcomment" ).generateSqmExpression(
+				List.of( value( comment ) ),
+				null,
+				queryEngine
+		);
+	}
 }
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/function/xml/XmlCommentTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/function/xml/XmlCommentTest.java
@@ -0,0 +1,36 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.orm.test.function.xml;
+
+import org.hibernate.cfg.QuerySettings;
+
+import org.hibernate.testing.orm.junit.DialectFeatureChecks;
+import org.hibernate.testing.orm.junit.DomainModel;
+import org.hibernate.testing.orm.junit.RequiresDialectFeature;
+import org.hibernate.testing.orm.junit.ServiceRegistry;
+import org.hibernate.testing.orm.junit.SessionFactory;
+import org.hibernate.testing.orm.junit.SessionFactoryScope;
+import org.hibernate.testing.orm.junit.Setting;
+import org.junit.jupiter.api.Test;
+
+/**
+ * @author Christian Beikov
+ */
+@DomainModel
+@SessionFactory
+@ServiceRegistry(settings = @Setting(name = QuerySettings.XML_FUNCTIONS_ENABLED, value = "true"))
+@RequiresDialectFeature( feature = DialectFeatureChecks.SupportsXmlcomment.class)
+public class XmlCommentTest {
+
+	@Test
+	public void testSimple(SessionFactoryScope scope) {
+		scope.inSession( em -> {
+			//tag::hql-xmlcomment-example[]
+			em.createQuery( "select xmlcomment('This is my comment')" ).getResultList();
+			//end::hql-xmlcomment-example[]
+		} );
+	}
+
+}
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/hql/XmlFunctionTests.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/hql/XmlFunctionTests.java
@@ -43,7 +43,6 @@
 import jakarta.persistence.Id;
 import jakarta.persistence.Tuple;
 import org.w3c.dom.Document;
-import org.w3c.dom.Element;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 import org.xml.sax.InputSource;
@@ -137,24 +136,40 @@ public void testXmlelement(SessionFactoryScope scope) {
 		);
 	}
 
-	private void assertXmlEquals(String doc1, String doc2) {
-		final Document d1 = parseXml( xmlNormalize( doc1 ) );
-		final Document d2 = parseXml( xmlNormalize( doc2 ) );
-		normalize( d1 );
-		normalize( d2 );
-		assertEquals( toXml( d1 ), toXml( d2 ) );
+	@Test
+	@RequiresDialectFeature(feature = DialectFeatureChecks.SupportsXmlcomment.class)
+	public void testXmlcomment(SessionFactoryScope scope) {
+		scope.inTransaction(
+				session -> {
+					Tuple tuple = session.createQuery(
+							"select " +
+									"xmlcomment('Abc'), " +
+									"xmlcomment('<>')",
+							Tuple.class
+					).getSingleResult();
+					assertXmlEquals( "<!--Abc--><a/>", tuple.get( 0, String.class ) + "<a/>" );
+					assertXmlEquals( "<!--<>--><a/>", tuple.get( 1 , String.class ) + "<a/>" );
+				}
+		);
+	}
+
+	private void assertXmlEquals(String expected, String actual) {
+		final Document expectedDoc = parseXml( xmlNormalize( expected ) );
+		final Document actualDoc = parseXml( xmlNormalize( actual ) );
+		normalize( expectedDoc );
+		normalize( actualDoc );
+		assertEquals( toXml( expectedDoc ).trim(), toXml( actualDoc ).trim() );
 	}
 
 	private void normalize(Document document) {
-		normalize( document.getDocumentElement() );
+		normalize( document.getChildNodes() );
 	}
 
-	private void normalize(Element element) {
-		final NodeList childNodes = element.getChildNodes();
+	private void normalize(NodeList childNodes) {
 		for ( int i = 0; i < childNodes.getLength(); i++ ) {
 			final Node childNode = childNodes.item( i );
 			if ( childNode.getNodeType() == Node.ELEMENT_NODE ) {
-				normalize( (Element) childNode );
+				normalize( childNode.getChildNodes() );
 			}
 			else if ( childNode.getNodeType() == Node.TEXT_NODE ) {
 				if ( childNode.getNodeValue().isBlank() ) {
@@ -164,6 +179,9 @@ else if ( childNode.getNodeType() == Node.TEXT_NODE ) {
 					childNode.setNodeValue( childNode.getNodeValue().trim() );
 				}
 			}
+			else if ( childNode.getNodeType() == Node.COMMENT_NODE ) {
+				childNode.setNodeValue( childNode.getNodeValue().trim() );
+			}
 		}
 	}
 
diff --git a/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/DialectFeatureChecks.java b/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/DialectFeatureChecks.java
@@ -841,6 +841,12 @@ public boolean apply(Dialect dialect) {
 		}
 	}
 
+	public static class SupportsXmlcomment implements DialectFeatureCheck {
+		public boolean apply(Dialect dialect) {
+			return definesFunction( dialect, "xmlcomment" );
+		}
+	}
+
 	public static class IsJtds implements DialectFeatureCheck {
 		public boolean apply(Dialect dialect) {
 			return dialect instanceof SybaseDialect && ( (SybaseDialect) dialect ).getDriverKind() == SybaseDriverKind.JTDS;

Original file line number	Diff line number	Diff line change
`@@ -442,6 +442,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`442`	`442`	`}`
`443`	`443`
`444`	`444`	`functionFactory.xmlelement();`
	`445`	`+ functionFactory.xmlcomment();`
`445`	`446`	`}`
`446`	`447`
`447`	`448`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -419,6 +419,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`419`	`419`	`}`
`420`	`420`
`421`	`421`	`functionFactory.xmlelement_h2();`
	`422`	`+ functionFactory.xmlcomment();`
`422`	`423`	`}`
`423`	`424`	`else {`
`424`	`425`	`functionFactory.listagg_groupConcat();`
Original file line number	Diff line number	Diff line change
`@@ -327,6 +327,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`327`	`327`	`}`
`328`	`328`
`329`	`329`	`functionFactory.xmlelement();`
	`330`	`+ functionFactory.xmlcomment();`
`330`	`331`	`}`
`331`	`332`
`332`	`333`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -414,6 +414,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`414`	`414`	`functionFactory.jsonArrayInsert_sqlserver();`
`415`	`415`	`}`
`416`	`416`	`functionFactory.xmlelement_sqlserver();`
	`417`	`+ functionFactory.xmlcomment_sqlserver();`
`417`	`418`	`if ( getVersion().isSameOrAfter( 14 ) ) {`
`418`	`419`	`functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );`
`419`	`420`	`functionFactory.jsonArrayAgg_sqlserver( getVersion().isSameOrAfter( 16 ) );`
Original file line number	Diff line number	Diff line change
`@@ -427,6 +427,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`427`	`427`	`}`
`428`	`428`
`429`	`429`	`functionFactory.xmlelement();`
	`430`	`+ functionFactory.xmlcomment();`
`430`	`431`	`}`
`431`	`432`
`432`	`433`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -354,6 +354,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`354`	`354`	`}`
`355`	`355`
`356`	`356`	`functionFactory.xmlelement_h2();`
	`357`	`+ functionFactory.xmlcomment();`
`357`	`358`	`}`
`358`	`359`
`359`	`360`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -417,6 +417,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`417`	`417`	`functionFactory.jsonArrayInsert_oracle();`
`418`	`418`
`419`	`419`	`functionFactory.xmlelement();`
	`420`	`+ functionFactory.xmlcomment();`
`420`	`421`	`}`
`421`	`422`
`422`	`423`	`@Override`