HHH-18767 add BatchSize for use with findMultiple()

Signed-off-by: Gavin King <gavin@hibernate.org>

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

@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate;
+
+import jakarta.persistence.FindOption;
+
+import java.util.List;
+
+/**
+ * Specify a batch size, that is, how many entities should be
+ * fetched in each request to the database, for an invocation of
+ * {@link Session#findMultiple(Class, List, FindOption...)}.
+ * <ul>
+ * <li>By default, the batch sizing strategy is determined by the
+ *     {@linkplain org.hibernate.dialect.Dialect#getBatchLoadSizingStrategy
+ *    SQL dialect}, but
+ * <li>if some {@code batchSize>1} is specified as an
+ *     argument to this method, then that batch size will be used.
+ * </ul>
+ * <p>
+ * If an explicit batch size is set manually, care should be taken
+ * to not exceed the capabilities of the underlying database.
+ * <p>
+ * A batch size is considered a hint. This option has no effect
+ * on {@link Session#find(Class, Object, FindOption...)}.
+ *
+ * @param batchSize The batch size
+ *
+ * @see Session#findMultiple
+ * @see MultiIdentifierLoadAccess#withBatchSize
+ *
+ * @since 7.0
+ *
+ * @author Gavin King
+ */
+public record BatchSize(int batchSize) implements FindOption {
+}

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

@@ -561,6 +561,9 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * 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.
+	 * <p>
 	 * For more advanced cases, use {@link #byMultipleIds(Class)}, which returns an instance of
 	 * {@link MultiIdentifierLoadAccess}.
 	 *

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

@@ -24,6 +24,7 @@ import java.util.TimeZone;
 
 import jakarta.persistence.PessimisticLockScope;
 import jakarta.persistence.Timeout;
+import org.hibernate.BatchSize;
 import org.hibernate.CacheMode;
 import org.hibernate.ConnectionAcquisitionMode;
 import org.hibernate.EntityFilterException;
@@ -950,6 +951,7 @@ public class SessionImpl
 		CacheStoreMode storeMode = getCacheStoreMode();
 		CacheRetrieveMode retrieveMode = getCacheRetrieveMode();
 		LockOptions lockOptions = copySessionLockOptions();
+		int batchSize = -1;
 		for ( FindOption option : options ) {
 			if ( option instanceof CacheStoreMode cacheStoreMode ) {
 				storeMode = cacheStoreMode;
@@ -982,8 +984,13 @@ public class SessionImpl
 			else if ( option instanceof ReadOnlyMode ) {
 				loadAccess.withReadOnly( option == ReadOnlyMode.READ_ONLY );
 			}
+			else if ( option instanceof BatchSize batchSizeOption ) {
+				batchSize = batchSizeOption.batchSize();
+			}
 		}
-		loadAccess.with( lockOptions ).with( interpretCacheMode( storeMode, retrieveMode ) );
+		loadAccess.with( lockOptions )
+				.with( interpretCacheMode( storeMode, retrieveMode ) )
+				.withBatchSize( batchSize );
 		return loadAccess;
 	}