HHH-19612 allow EntityGraph names in the JPA standard hints

and fix a mistake in the Javadoc fot SharedSessionContract

Author: gavinking

hibernate-core/src/main/java/org/hibernate/SharedSessionContract.java

@@ -375,23 +375,26 @@ public interface SharedSessionContract extends QueryProducer, AutoCloseable, Ser
 	 * @throws IllegalArgumentException if the graph with the given
 	 *         name does not have the given entity type as its root
 	 *
+	 * @see jakarta.persistence.EntityManager#createEntityGraph(String)
+	 *
 	 * @since 6.3
 	 */
 	<T> RootGraph<T> createEntityGraph(Class<T> rootType, String graphName);
 
 	/**
 	 * Obtain an immutable reference to a predefined
-	 * {@linkplain jakarta.persistence.NamedEntityGraph named entity graph}
-	 * or return {@code null} if there is no predefined graph with the given
-	 * name.
+	 * {@linkplain jakarta.persistence.NamedEntityGraph named entity graph}.
 	 *
 	 * @param graphName the name of the predefined named entity graph
+	 * @throws IllegalArgumentException if there is no predefined graph
+	 *         with the given name
 	 *
 	 * @apiNote This method returns {@code RootGraph<?>}, requiring an
 	 * unchecked typecast before use. It's cleaner to obtain a graph using
 	 * the static metamodel for the class which defines the graph, or by
 	 * calling {@link SessionFactory#getNamedEntityGraphs(Class)} instead.
 	 *
+	 * @see jakarta.persistence.EntityManager#getEntityGraph(String)
 	 * @see SessionFactory#getNamedEntityGraphs(Class)
 	 * @see jakarta.persistence.EntityManagerFactory#addNamedEntityGraph(String, EntityGraph)
 	 *

hibernate-core/src/main/java/org/hibernate/engine/spi/SessionImplementor.java

@@ -10,7 +10,6 @@
 import org.hibernate.Session;
 import org.hibernate.engine.jdbc.LobCreationContext;
 import org.hibernate.engine.jdbc.spi.JdbcCoordinator;
-import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.persister.entity.EntityPersister;
 import org.hibernate.query.spi.QueryImplementor;
 import org.hibernate.resource.jdbc.spi.JdbcSessionOwner;
@@ -66,15 +65,6 @@ default SessionImplementor getSession() {
 	@Override
 	SessionFactoryImplementor getSessionFactory();
 
-	@Override
-	<T> RootGraphImplementor<T> createEntityGraph(Class<T> rootType);
-
-	@Override
-	RootGraphImplementor<?> createEntityGraph(String graphName);
-
-	@Override
-	RootGraphImplementor<?> getEntityGraph(String graphName);
-
 	@Override
 	<T> QueryImplementor<T> createQuery(CriteriaSelect<T> selectQuery);
 

hibernate-core/src/main/java/org/hibernate/engine/spi/SharedSessionContractImplementor.java

@@ -20,6 +20,7 @@
 import org.hibernate.bytecode.enhance.spi.interceptor.SessionAssociationMarkers;
 import org.hibernate.dialect.Dialect;
 import org.hibernate.event.spi.EventSource;
+import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.query.Query;
 import org.hibernate.SharedSessionContract;
 import org.hibernate.Transaction;
@@ -584,4 +585,13 @@ default boolean isStatelessSession() {
 	 */
 	@Incubating
 	SessionAssociationMarkers getSessionAssociationMarkers();
+
+	@Override
+	<T> RootGraphImplementor<T> createEntityGraph(Class<T> rootType);
+
+	@Override
+	RootGraphImplementor<?> createEntityGraph(String graphName);
+
+	@Override
+	RootGraphImplementor<?> getEntityGraph(String graphName);
 }

hibernate-core/src/main/java/org/hibernate/engine/spi/SharedSessionDelegatorBaseImpl.java

@@ -29,6 +29,7 @@
 import org.hibernate.engine.jdbc.spi.JdbcServices;
 import org.hibernate.event.monitor.spi.EventMonitor;
 import org.hibernate.graph.RootGraph;
+import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.jdbc.ReturningWork;
 import org.hibernate.jdbc.Work;
 import org.hibernate.persister.entity.EntityPersister;
@@ -632,12 +633,12 @@ public TimeZone getJdbcTimeZone() {
 	}
 
 	@Override
-	public <T> RootGraph<T> createEntityGraph(Class<T> rootType) {
+	public <T> RootGraphImplementor<T> createEntityGraph(Class<T> rootType) {
 		return delegate.createEntityGraph( rootType );
 	}
 
 	@Override
-	public RootGraph<?> createEntityGraph(String graphName) {
+	public RootGraphImplementor<?> createEntityGraph(String graphName) {
 		return delegate.createEntityGraph( graphName );
 	}
 
@@ -647,7 +648,7 @@ public <T> RootGraph<T> createEntityGraph(Class<T> rootType, String graphName) {
 	}
 
 	@Override
-	public RootGraph<?> getEntityGraph(String graphName) {
+	public RootGraphImplementor<?> getEntityGraph(String graphName) {
 		return delegate.getEntityGraph( graphName );
 	}
 

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

@@ -354,13 +354,13 @@ protected final boolean applySelectionHint(String hintName, Object value) {
 					DEPRECATION_LOGGER.deprecatedSetting( HINT_JAVAEE_FETCH_GRAPH, HINT_SPEC_FETCH_GRAPH );
 					//fall through to:
 				case HINT_SPEC_FETCH_GRAPH:
-					applyEntityGraphHint( hintName, value );
+					applyEntityGraphHint( GraphSemantic.FETCH, value, hintName );
 					return true;
 				case HINT_JAVAEE_LOAD_GRAPH:
 					DEPRECATION_LOGGER.deprecatedSetting( HINT_JAVAEE_LOAD_GRAPH, HINT_SPEC_LOAD_GRAPH );
 					//fall through to:
 				case HINT_SPEC_LOAD_GRAPH:
-					applyEntityGraphHint( hintName, value );
+					applyEntityGraphHint( GraphSemantic.LOAD, value, hintName );
 					return true;
 				case HINT_FETCH_PROFILE:
 					queryOptions.enableFetchProfile( (String) value );
@@ -371,17 +371,39 @@ protected final boolean applySelectionHint(String hintName, Object value) {
 		}
 	}
 
-	protected void applyEntityGraphHint(String hintName, Object value) {
-		final GraphSemantic graphSemantic = GraphSemantic.fromHintName( hintName );
+	protected void applyEntityGraphHint(GraphSemantic graphSemantic, Object value, String hintName) {
 		if ( value instanceof RootGraphImplementor<?> rootGraphImplementor ) {
 			applyGraph( rootGraphImplementor, graphSemantic );
 		}
 		else if ( value instanceof String string ) {
-			applyGraph( string, graphSemantic );
+			// try and interpret it as the name of a @NamedEntityGraph
+			final var entityGraph = getEntityGraph( string );
+			if ( entityGraph == null ) {
+				try {
+					// try and parse it in the entity graph language
+					applyGraph( string, graphSemantic );
+				}
+				catch ( IllegalArgumentException e ) {
+					throw new IllegalArgumentException( "The string value of the hint '" + hintName
+							+ "' must be the name of a named EntityGraph, or a representation understood by GraphParser" );
+				}
+			}
+			else {
+				applyGraph( entityGraph, graphSemantic );
+			}
 		}
 		else {
 			throw new IllegalArgumentException( "The value of the hint '" + hintName
-					+ "' must be an instance of EntityGraph or the string name of a named EntityGraph" );
+					+ "' must be an instance of EntityGraph, the string name of a named EntityGraph, or a string representation understood by GraphParser" );
+		}
+	}
+
+	private RootGraphImplementor<?> getEntityGraph(String string) {
+		try {
+			return getSession().getEntityGraph( string );
+		}
+		catch ( IllegalArgumentException e ) {
+			return null;
 		}
 	}
 
@@ -392,7 +414,7 @@ protected void applyGraph(String graphString, GraphSemantic graphSemantic) {
 			throw new IllegalArgumentException(
 					String.format(
 							ROOT,
-							"Invalid entity-graph definition `%s`; expected form `${EntityName}( ${property1} ... )",
+							"Invalid entity-graph definition '%s'; expected form '${EntityName}( ${property1} ... )'",
 							graphString
 					)
 			);

hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java

@@ -673,8 +673,8 @@ public Query<R> applyGraph(@SuppressWarnings("rawtypes") RootGraph graph, GraphS
 	}
 
 	@Override
-	protected void applyEntityGraphHint(String hintName, Object value) {
-		super.applyEntityGraphHint( hintName, value );
+	protected void applyEntityGraphHint(GraphSemantic graphSemantic, Object value, String hintName) {
+		super.applyEntityGraphHint( graphSemantic, value, hintName );
 	}
 
 	@Override