HHH-16659 add Query.setEntityGraph()

and turn a log message into an IllegalArgumentException

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java

@@ -17,6 +17,7 @@
 
 import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
+import jakarta.persistence.EntityGraph;
 import org.hibernate.CacheMode;
 import org.hibernate.FlushMode;
 import org.hibernate.Incubating;
@@ -34,6 +35,7 @@
 import jakarta.persistence.LockModeType;
 import jakarta.persistence.Parameter;
 import jakarta.persistence.TemporalType;
+import org.hibernate.graph.GraphSemantic;
 
 /**
  * Within the context of an active {@linkplain org.hibernate.Session session},
@@ -186,6 +188,14 @@ default Stream<R> stream() {
 
 	SelectionQuery<R> setHint(String hintName, Object value);
 
+	/**
+	 * Apply an {@link EntityGraph} to the query.
+	 * <p>
+	 * This is an alternative way to specify the associations which
+	 * should be fetched as part of the initial query.
+	 */
+	SelectionQuery<R> setEntityGraph(EntityGraph<R> graph, GraphSemantic semantic);
+
 	@Override
 	SelectionQuery<R> setFlushMode(FlushModeType flushMode);
 

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractCommonQueryContract.java

@@ -368,7 +368,8 @@ else if ( value instanceof String ) {
 			applyGraph( (String) value, graphSemantic );
 		}
 		else {
-			QueryLogging.QUERY_LOGGER.debugf( "The %s hint was set, but the value was neither an EntityGraph nor String", hintName );
+			throw new IllegalArgumentException( "The value of the hint '" + hintName
+					+ "' must be an instance of EntityGraph or the string name of a named EntityGraph" );
 		}
 	}
 

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java

@@ -22,6 +22,7 @@
 
 import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
+import jakarta.persistence.EntityGraph;
 import jakarta.persistence.FlushModeType;
 import jakarta.persistence.LockModeType;
 import jakarta.persistence.NoResultException;
@@ -41,7 +42,9 @@
 import org.hibernate.TypeMismatchException;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
+import org.hibernate.graph.GraphSemantic;
 import org.hibernate.graph.spi.AppliedGraph;
+import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.jpa.internal.util.LockModeTypeHelper;
 import org.hibernate.metamodel.model.domain.BasicDomainType;
 import org.hibernate.metamodel.model.domain.DomainType;
@@ -576,6 +579,11 @@ public SelectionQuery<R> setHint(String hintName, Object value) {
 		return this;
 	}
 
+	@Override
+	public SelectionQuery<R> setEntityGraph(EntityGraph<R> graph, GraphSemantic semantic) {
+		applyGraph( (RootGraphImplementor<R>) graph, semantic );
+		return this;
+	}
 
 	@Override
 	public LockOptions getLockOptions() {