HHH-19116 Implement support for explicit joins in fk() function

Author: mbellade

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

@@ -542,7 +542,7 @@ Hibernate does support a means to refer specifically to the key column (`Person.
 using the special `fk(..)` function.  E.g.
 
 [[associations-not-found-fk-function-example]]
-.Implicit join example
+.FK example
 ====
 [source,java]
 ----

hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java

@@ -125,7 +125,6 @@
 import org.hibernate.query.sqm.tree.domain.SqmCteRoot;
 import org.hibernate.query.sqm.tree.domain.SqmDerivedRoot;
 import org.hibernate.query.sqm.tree.domain.SqmElementAggregateFunction;
-import org.hibernate.query.sqm.tree.domain.SqmEntityValuedSimplePath;
 import org.hibernate.query.sqm.tree.domain.SqmFkExpression;
 import org.hibernate.query.sqm.tree.domain.SqmFunctionRoot;
 import org.hibernate.query.sqm.tree.domain.SqmIndexAggregateFunction;
@@ -3579,7 +3578,7 @@ public SqmFkExpression<?> visitToOneFkReference(HqlParser.ToOneFkReferenceContex
 			);
 
 		}
-		return new SqmFkExpression<>( (SqmEntityValuedSimplePath<?>) sqmPath );
+		return new SqmFkExpression<>( sqmPath );
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmCriteriaNodeBuilder.java

@@ -28,6 +28,7 @@
 import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.ServiceLoader;
 import java.util.Set;
@@ -45,6 +46,7 @@
 import org.hibernate.metamodel.model.domain.JpaMetamodel;
 import org.hibernate.metamodel.model.domain.PersistentAttribute;
 import org.hibernate.metamodel.model.domain.SingularPersistentAttribute;
+import org.hibernate.metamodel.model.domain.internal.EntitySqmPathSource;
 import org.hibernate.metamodel.spi.MappingMetamodelImplementor;
 import org.hibernate.query.BindableType;
 import org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode;
@@ -98,7 +100,6 @@
 import org.hibernate.query.sqm.tree.cte.SqmSearchClauseSpecification;
 import org.hibernate.query.sqm.tree.delete.SqmDeleteStatement;
 import org.hibernate.query.sqm.tree.domain.SqmBagJoin;
-import org.hibernate.query.sqm.tree.domain.SqmEntityValuedSimplePath;
 import org.hibernate.query.sqm.tree.domain.SqmFkExpression;
 import org.hibernate.query.sqm.tree.domain.SqmListJoin;
 import org.hibernate.query.sqm.tree.domain.SqmMapJoin;
@@ -595,12 +596,22 @@ public <T extends HibernateCriteriaBuilder> T unwrap(Class<T> clazz) {
 
 	@Override
 	public <P, F> SqmExpression<F> fk(Path<P> path) {
-		if ( path.getModel().getBindableType() != Bindable.BindableType.SINGULAR_ATTRIBUTE
-				|| ! ( path instanceof SqmEntityValuedSimplePath ) ) {
-			throw new FunctionArgumentException( "Path '" + path + "' does not refer to a single-valued association" );
+		final SqmPath<P> sqmPath = (SqmPath<P>) path;
+		final SqmPathSource<?> toOneReference = sqmPath.getReferencedPathSource();
+		final boolean validToOneRef =
+				toOneReference.getBindableType() == Bindable.BindableType.SINGULAR_ATTRIBUTE
+				&& toOneReference instanceof EntitySqmPathSource;
+		if ( !validToOneRef ) {
+			throw new FunctionArgumentException(
+					String.format(
+							Locale.ROOT,
+							"Argument '%s' of 'fk()' function is not a single-valued association",
+							sqmPath.getNavigablePath()
+					)
+			);
 		}
 
-		return new SqmFkExpression<>( (SqmEntityValuedSimplePath<?>) path );
+		return new SqmFkExpression<>( sqmPath );
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmTreePrinter.java

@@ -745,7 +745,7 @@ public Object visitNonAggregatedCompositeValuedPath(NonAggregatedCompositeSimple
 
 	@Override
 	public Object visitFkExpression(SqmFkExpression<?> fkExpression) {
-		logWithIndentation( "-> [fk-ref] - `%s`", fkExpression.getToOnePath().getNavigablePath() );
+		logWithIndentation( "-> [fk-ref] - `%s`", fkExpression.getLhs().getNavigablePath() );
 
 		return null;
 	}

hibernate-core/src/main/java/org/hibernate/query/sqm/sql/BaseSqmToSqlAstConverter.java

@@ -4567,11 +4567,12 @@ public Expression visitPluralValuedPath(SqmPluralValuedSimplePath<?> sqmPath) {
 
 	@Override
 	public Object visitFkExpression(SqmFkExpression<?> fkExpression) {
-		final SqmPath<?> lhs = fkExpression.getToOnePath().getLhs();
+		final SqmPath<?> toOnePath = fkExpression.getLhs();
+		final SqmPath<?> lhs = toOnePath.getLhs();
 		prepareReusablePath( lhs, () -> null );
 		final TableGroup tableGroup = getFromClauseIndex().findTableGroup( lhs.getNavigablePath() );
 		final ModelPart subPart = tableGroup.getModelPart()
-				.findSubPart( fkExpression.getToOnePath().getModel().getPathName(), null );
+				.findSubPart( toOnePath.getReferencedPathSource().getPathName(), null );
 		assert subPart instanceof ToOneAttributeMapping;
 
 		final ToOneAttributeMapping toOneMapping = (ToOneAttributeMapping) subPart;

hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/SqmFkExpression.java

@@ -5,6 +5,7 @@
 package org.hibernate.query.sqm.tree.domain;
 
 import org.hibernate.metamodel.mapping.ForeignKeyDescriptor;
+import org.hibernate.metamodel.model.domain.DomainType;
 import org.hibernate.metamodel.model.domain.EntityDomainType;
 import org.hibernate.metamodel.model.domain.IdentifiableDomainType;
 import org.hibernate.query.hql.spi.SqmCreationState;
@@ -21,15 +22,14 @@
  * @author Steve Ebersole
  */
 public class SqmFkExpression<T> extends AbstractSqmPath<T> {
-
-	public SqmFkExpression(SqmEntityValuedSimplePath<?> toOnePath) {
+	public SqmFkExpression(SqmPath<?> toOnePath) {
 		this( toOnePath.getNavigablePath().append( ForeignKeyDescriptor.PART_NAME ), toOnePath );
 	}
 
 	@SuppressWarnings("unchecked")
 	private SqmFkExpression(
 			NavigablePath navigablePath,
-			SqmEntityValuedSimplePath<?> toOnePath) {
+			SqmPath<?> toOnePath) {
 		super(
 				navigablePath,
 				(SqmPathSource<T>) pathDomainType( toOnePath ).getIdentifierDescriptor(),
@@ -38,12 +38,14 @@ private SqmFkExpression(
 		);
 	}
 
-	private static IdentifiableDomainType<?> pathDomainType(SqmEntityValuedSimplePath<?> toOnePath) {
-		return (IdentifiableDomainType<?>) toOnePath.getNodeType();
-	}
-
-	public SqmEntityValuedSimplePath<?> getToOnePath() {
-		return (SqmEntityValuedSimplePath<?>) getLhs();
+	private static IdentifiableDomainType<?> pathDomainType(SqmPath<?> toOnePath) {
+		final DomainType<?> domainType = toOnePath.getReferencedPathSource().getSqmPathType();
+		if ( domainType instanceof IdentifiableDomainType<?> identifiableDomainType ) {
+			return identifiableDomainType;
+		}
+		else {
+			throw new IllegalArgumentException( "Invalid path provided to 'fk()' function: " + toOnePath.getNavigablePath() );
+		}
 	}
 
 	@Override

hibernate-core/src/test/java/org/hibernate/orm/test/associations/NotFoundTest.java

@@ -125,7 +125,7 @@ public void queryTestFk(EntityManagerFactoryScope scope) {
 					assertThat( nullResults ).isEmpty();
 
 					final List<String> nonNullResults = entityManager
-							.createQuery( "select p.name from Person p where fk( p.city ) is not null", String.class )
+							.createQuery( "select p.name from Person p left join p.city c where fk( c ) is not null", String.class )
 							.getResultList();
 					assertThat( nonNullResults ).hasSize( 1 );
 					assertThat( nonNullResults.get( 0 ) ).isEqualTo( "John Doe" );