HHH-19378 findMultiple() and getMultiple() with EntityGraph

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

@@ -6,8 +6,9 @@
 
 import java.util.Optional;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 
 /**
  * Loads an entity by its primary identifier.
@@ -76,7 +77,7 @@ public interface IdentifierLoadAccess<T> {
 	 *
 	 * @since 6.3
 	 */
-	default IdentifierLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
+	default IdentifierLoadAccess<T> withFetchGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.FETCH );
 	}
 
@@ -87,15 +88,15 @@ default IdentifierLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	default IdentifierLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
+	default IdentifierLoadAccess<T> withLoadGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
 	/**
 	 * @deprecated use {@link #withLoadGraph}
 	 */
 	@Deprecated(since = "6.3")
-	default IdentifierLoadAccess<T> with(RootGraph<T> graph) {
+	default IdentifierLoadAccess<T> with(EntityGraph<T> graph) {
 		return withLoadGraph( graph );
 	}
 
@@ -104,7 +105,7 @@ default IdentifierLoadAccess<T> with(RootGraph<T> graph) {
 	 * {@linkplain jakarta.persistence.EntityGraph entity graph},
 	 * and how it should be {@linkplain GraphSemantic interpreted}.
 	 */
-	IdentifierLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
+	IdentifierLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic);
 
 	/**
 	 * Customize the associations fetched by specifying a

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

@@ -6,8 +6,9 @@
 
 import java.util.List;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 
 /**
  * Loads multiple instances of a given entity type at once, by
@@ -65,7 +66,7 @@ public interface MultiIdentifierLoadAccess<T> {
 	 *
 	 * @since 6.3
 	 */
-	default MultiIdentifierLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
+	default MultiIdentifierLoadAccess<T> withFetchGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.FETCH );
 	}
 
@@ -76,15 +77,15 @@ default MultiIdentifierLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	default MultiIdentifierLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
+	default MultiIdentifierLoadAccess<T> withLoadGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
 	/**
 	 * @deprecated use {@link #withLoadGraph}
 	 */
 	@Deprecated(since = "6.3")
-	default MultiIdentifierLoadAccess<T> with(RootGraph<T> graph) {
+	default MultiIdentifierLoadAccess<T> with(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
@@ -93,7 +94,7 @@ default MultiIdentifierLoadAccess<T> with(RootGraph<T> graph) {
 	 * {@linkplain jakarta.persistence.EntityGraph entity graph},
 	 * and how it should be {@linkplain GraphSemantic interpreted}.
 	 */
-	MultiIdentifierLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
+	MultiIdentifierLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic);
 
 	/**
 	 * Customize the associations fetched by specifying a

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

@@ -4,9 +4,10 @@
  */
 package org.hibernate;
 
+import jakarta.persistence.EntityGraph;
+
 import jakarta.persistence.metamodel.SingularAttribute;
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 
 import java.util.Map;
 import java.util.Optional;
@@ -51,7 +52,7 @@ public interface NaturalIdLoadAccess<T> {
 	 *
 	 * @since 6.3
 	 */
-	default NaturalIdLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
+	default NaturalIdLoadAccess<T> withFetchGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.FETCH );
 	}
 
@@ -62,7 +63,7 @@ default NaturalIdLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	default NaturalIdLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
+	default NaturalIdLoadAccess<T> withLoadGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
@@ -73,7 +74,7 @@ default NaturalIdLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	NaturalIdLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
+	NaturalIdLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic);
 
 	/**
 	 * Customize the associations fetched by specifying a

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

@@ -4,8 +4,9 @@
  */
 package org.hibernate;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 
 import java.util.List;
 
@@ -61,7 +62,7 @@ public interface NaturalIdMultiLoadAccess<T> {
 	 *
 	 * @since 6.3
 	 */
-	default NaturalIdMultiLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
+	default NaturalIdMultiLoadAccess<T> withFetchGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.FETCH );
 	}
 
@@ -72,15 +73,15 @@ default NaturalIdMultiLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	default NaturalIdMultiLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
+	default NaturalIdMultiLoadAccess<T> withLoadGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
 	/**
 	 * @deprecated use {@link #withLoadGraph}
 	 */
 	@Deprecated(since = "6.3")
-	default NaturalIdMultiLoadAccess<T> with(RootGraph<T> graph) {
+	default NaturalIdMultiLoadAccess<T> with(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
@@ -89,7 +90,7 @@ default NaturalIdMultiLoadAccess<T> with(RootGraph<T> graph) {
 	 * {@linkplain jakarta.persistence.EntityGraph entity graph},
 	 * and how it should be {@linkplain GraphSemantic interpreted}.
 	 */
-	NaturalIdMultiLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
+	NaturalIdMultiLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic);
 
 	/**
 	 * Specify a batch size, that is, how many entities should be

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

@@ -597,6 +597,46 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 */
 	<E> List<E> findMultiple(Class<E> entityType, List<?> ids, FindOption... options);
 
+	/**
+	 * Return the persistent instances of the root entity of the given {@link EntityGraph}
+	 * with the given identifiers as a list, fetching the associations specified by the
+	 * graph, which is interpreted as a {@linkplain org.hibernate.graph.GraphSemantic#LOAD
+	 * load graph}. The position of an instance in the returned list matches the position of
+	 * its identifier in the given list of identifiers, and the returned list contains a null
+	 * value if there is no persistent instance matching a given identifier. If an instance
+	 * is already associated with the session, that instance is returned. This method never
+	 * returns an uninitialized instance.
+	 * <p>
+	 * Every object returned by {@code findMultiple()} is either an unproxied instance of the
+	 * given entity class, or a fully-fetched proxy object.
+	 * <p>
+	 * This method accepts {@link BatchSize} as an option, allowing control over the number of
+	 * records retrieved in a single database request. The performance impact of setting a batch
+	 * size depends on whether a SQL array may be used to pass the list of identifiers to the
+	 * database:
+	 * <ul>
+	 * <li>for databases which {@linkplain org.hibernate.dialect.Dialect#supportsStandardArrays
+	 *     support standard SQL arrays}, a smaller batch size might be extremely inefficient
+	 *     compared to a very large batch size or no batching at all, but
+	 * <li>on the other hand, for databases with no SQL array type, a large batch size results
+	 *     in long SQL statements with many JDBC parameters.
+	 * </ul>
+	 * <p>
+	 * For more advanced cases, use {@link #byMultipleIds(Class)}, which returns an instance of
+	 * {@link MultiIdentifierLoadAccess}.
+	 *
+	 * @param entityGraph the entity graph interpreted as a load graph
+	 * @param ids the list of identifiers
+	 * @param options options, if any
+	 *
+	 * @return an ordered list of persistent instances, with null elements representing missing
+	 *         entities, whose positions in the list match the positions of their ids in the
+	 *         given list of identifiers
+	 * @see #byMultipleIds(Class)
+	 * @since 7.0
+	 */
+	<E> List<E> findMultiple(EntityGraph<E> entityGraph, List<?> ids, FindOption... options);
+
 	/**
 	 * Read the persistent state associated with the given identifier into the given
 	 * transient instance.

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

@@ -4,8 +4,9 @@
  */
 package org.hibernate;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 
 import java.util.Optional;
 
@@ -45,7 +46,7 @@ public interface SimpleNaturalIdLoadAccess<T> {
 	 *
 	 * @since 6.3
 	 */
-	default SimpleNaturalIdLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
+	default SimpleNaturalIdLoadAccess<T> withFetchGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.FETCH );
 	}
 
@@ -56,7 +57,7 @@ default SimpleNaturalIdLoadAccess<T> withFetchGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	default SimpleNaturalIdLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
+	default SimpleNaturalIdLoadAccess<T> withLoadGraph(EntityGraph<T> graph) {
 		return with( graph, GraphSemantic.LOAD );
 	}
 
@@ -67,7 +68,7 @@ default SimpleNaturalIdLoadAccess<T> withLoadGraph(RootGraph<T> graph) {
 	 *
 	 * @since 6.3
 	 */
-	SimpleNaturalIdLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic);
+	SimpleNaturalIdLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic);
 
 	/**
 	 * Customize the associations fetched by specifying a

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

@@ -372,6 +372,45 @@ public interface StatelessSession extends SharedSessionContract {
 	 */
 	<T> List<T> getMultiple(Class<T> entityClass, List<?> ids, LockMode lockMode);
 
+	/**
+	 * Retrieve multiple rows, returning instances of the root
+	 * entity of the given {@link EntityGraph} with the fetched
+	 * associations specified by the graph, in a list where the
+	 * position of an instance in the list matches the position
+	 * of its identifier in the given array, and the list
+	 * contains a null value if there is no persistent instance
+	 * matching a given identifier.
+	 *
+	 * @param entityGraph The {@link EntityGraph}, interpreted as a
+	 * {@linkplain org.hibernate.graph.GraphSemantic#LOAD load graph}
+	 * @param graphSemantic a {@link GraphSemantic} specifying
+	 *                      how the graph should be interpreted
+	 * @param ids The ids of the entities to retrieve
+	 * @return an ordered list of detached entity instances, with
+	 *         null elements representing missing entities
+	 * @since 7.0
+	 */
+	<T> List<T> getMultiple(EntityGraph<T> entityGraph, List<?> ids);
+
+	/**
+	 * Retrieve multiple rows, returning instances of the root
+	 * entity of the given {@link EntityGraph} with the fetched
+	 * associations specified by the graph, in a list where the
+	 * position of an instance in the list matches the position
+	 * of its identifier in the given array, and the list
+	 * contains a null value if there is no persistent instance
+	 * matching a given identifier.
+	 *
+	 * @param entityGraph The {@link EntityGraph}
+	 * @param graphSemantic a {@link GraphSemantic} specifying
+	 *                      how the graph should be interpreted
+	 * @param ids The ids of the entities to retrieve
+	 * @return an ordered list of detached entity instances, with
+	 *         null elements representing missing entities
+	 * @since 7.0
+	 */
+	<T> List<T> getMultiple(EntityGraph<T> entityGraph, GraphSemantic graphSemantic, List<?> ids);
+
 	/**
 	 * Refresh the entity instance state from the database.
 	 *

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

@@ -967,6 +967,11 @@ public <E> List<E> findMultiple(Class<E> entityType, List<?> ids, FindOption...
 		return delegate.findMultiple( entityType, ids, options );
 	}
 
+	@Override
+	public <E> List<E> findMultiple(EntityGraph<E> entityGraph, List<?> ids, FindOption... options) {
+		return  delegate.findMultiple( entityGraph, ids, options );
+	}
+
 	@Override
 	public <T> T get(Class<T> theClass, Object id) {
 		return delegate.get( theClass, id );

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

@@ -271,6 +271,11 @@ public <E> List<E> findMultiple(Class<E> entityType, List<?> ids, FindOption...
 		return this.lazySession.get().findMultiple( entityType, ids, options );
 	}
 
+	@Override
+	public <E> List<E> findMultiple(EntityGraph<E> entityGraph, List<?> ids, FindOption... options) {
+		return this.lazySession.get().findMultiple( entityGraph, ids, options );
+	}
+
 	@Override
 	public <T> T get(Class<T> entityType, Object id) {
 		return this.lazySession.get().get( entityType, id );

hibernate-core/src/main/java/org/hibernate/internal/MultiIdentifierLoadAccessImpl.java

@@ -9,6 +9,8 @@
 import java.util.Set;
 import java.util.function.Supplier;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.CacheMode;
 import org.hibernate.LockOptions;
 import org.hibernate.MultiIdentifierLoadAccess;
@@ -18,7 +20,6 @@
 import org.hibernate.engine.spi.SessionImplementor;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.persister.entity.EntityPersister;
 import org.hibernate.loader.ast.spi.MultiIdLoadOptions;
@@ -76,7 +77,7 @@ public MultiIdentifierLoadAccess<T> withReadOnly(boolean readOnly) {
 	}
 
 	@Override
-	public MultiIdentifierLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic) {
+	public MultiIdentifierLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic) {
 		this.rootGraph = (RootGraphImplementor<T>) graph;
 		this.graphSemantic = semantic;
 		return this;

hibernate-core/src/main/java/org/hibernate/internal/NaturalIdMultiLoadAccessStandard.java

@@ -6,14 +6,15 @@
 
 import java.util.List;
 
+import jakarta.persistence.EntityGraph;
+
 import org.hibernate.CacheMode;
 import org.hibernate.LockOptions;
 import org.hibernate.NaturalIdMultiLoadAccess;
 import org.hibernate.engine.spi.EffectiveEntityGraph;
 import org.hibernate.engine.spi.LoadQueryInfluencers;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.graph.GraphSemantic;
-import org.hibernate.graph.RootGraph;
 import org.hibernate.graph.spi.RootGraphImplementor;
 import org.hibernate.loader.ast.spi.MultiNaturalIdLoadOptions;
 import org.hibernate.persister.entity.EntityPersister;
@@ -55,7 +56,7 @@ public NaturalIdMultiLoadAccess<T> with(CacheMode cacheMode) {
 	}
 
 	@Override
-	public NaturalIdMultiLoadAccess<T> with(RootGraph<T> graph, GraphSemantic semantic) {
+	public NaturalIdMultiLoadAccess<T> with(EntityGraph<T> graph, GraphSemantic semantic) {
 		this.rootGraph = (RootGraphImplementor<T>) graph;
 		this.graphSemantic = semantic;
 		return this;