provide even better documentation of the effect of JDBC batching in SS

note that this feature was most likely introduced in HHH-10431 by accident!

Author: gavinking

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

@@ -265,6 +265,15 @@ public interface SharedSessionContract extends QueryProducer, AutoCloseable, Ser
 	 * factory-level} JDBC batch size controlled by the configuration property
 	 * {@value org.hibernate.cfg.AvailableSettings#STATEMENT_BATCH_SIZE}.
 	 *
+	 * @apiNote Setting a session-level JDBC batch size for a
+	 * {@link StatelessSession} triggers a sort of write-behind behaviour
+	 * where operations are batched and executed asynchronously, undermining
+	 * the semantics of the stateless programming model. We recommend the use
+	 * of explicitly-batching operations like
+	 * {@link StatelessSession#insertMultiple insertMultiple()},
+	 * {@link StatelessSession#updateMultiple updateMultiple()}, and
+	 * {@link StatelessSession#deleteMultiple deleteMultiple()} instead.
+	 *
 	 * @param jdbcBatchSize the new session-level JDBC batch size
 	 *
 	 * @since 5.2

hibernate-core/src/main/java/org/hibernate/cfg/BatchSettings.java

@@ -21,9 +21,11 @@ public interface BatchSettings {
 
 	/**
 	 * Specifies the maximum number of {@linkplain java.sql.PreparedStatement statements}
-	 * to {@linkplain PreparedStatement#addBatch batch} together.
-	 * <p/>
-	 * A nonzero value enables batching
+	 * to {@linkplain PreparedStatement#addBatch batch} together in a stateful session.
+	 * <p>
+	 * Any positive value enables batching.
+	 * <p>
+	 * This setting has no effect on {@linkplain org.hibernate.StatelessSession stateless sessions}.
 	 *
 	 * @see java.sql.PreparedStatement#executeBatch
 	 * @see java.sql.PreparedStatement#addBatch

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

@@ -24,7 +24,6 @@
 import org.hibernate.cache.spi.access.SoftLock;
 import org.hibernate.collection.spi.CollectionSemantics;
 import org.hibernate.collection.spi.PersistentCollection;
-import org.hibernate.engine.internal.PersistenceContexts;
 import org.hibernate.engine.spi.CollectionEntry;
 import org.hibernate.engine.spi.EffectiveEntityGraph;
 import org.hibernate.engine.spi.EntityHolder;
@@ -85,6 +84,7 @@
 
 import static org.hibernate.engine.internal.ManagedTypeHelper.asPersistentAttributeInterceptable;
 import static org.hibernate.engine.internal.ManagedTypeHelper.isPersistentAttributeInterceptable;
+import static org.hibernate.engine.internal.PersistenceContexts.createPersistenceContext;
 import static org.hibernate.engine.internal.Versioning.incrementVersion;
 import static org.hibernate.engine.internal.Versioning.seedVersion;
 import static org.hibernate.engine.internal.Versioning.setVersion;
@@ -134,10 +134,12 @@ public class StatelessSessionImpl extends AbstractSharedSessionContract implemen
 	public StatelessSessionImpl(SessionFactoryImpl factory, SessionCreationOptions options) {
 		super( factory, options );
 		connectionProvided = options.getConnection() != null;
-		temporaryPersistenceContext = PersistenceContexts.createPersistenceContext( this );
+		temporaryPersistenceContext = createPersistenceContext( this );
 		influencers = new LoadQueryInfluencers( getFactory() );
 		eventListenerGroups = factory.getEventListenerGroups();
 		setUpMultitenancy( factory, influencers );
+		// a nonzero batch size forces use of write-behind
+		// therefore ignore the value of hibernate.jdbc.batch_size
 		setJdbcBatchSize( 0 );
 	}