document the differnce in semantics of FlushMode.AUTO between JPA bootstrap and native Hibernate

Author: gavinking

hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryOptions.java

@@ -92,8 +92,8 @@ public interface SessionFactoryOptions extends QueryEngineOptions {
 	JpaCompliance getJpaCompliance();
 
 	/**
-	 * Was building of the SessionFactory initiated through JPA bootstrapping, or
-	 * through Hibernate's native bootstrapping?
+	 * Was building of the {@link org.hibernate.SessionFactory} initiated through JPA
+	 * bootstrapping, or through Hibernate-native bootstrapping?
 	 *
 	 * @return {@code true} indicates the SessionFactory was built through JPA
 	 * bootstrapping; {@code false} indicates it was built through native bootstrapping.

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

@@ -82,6 +82,18 @@
  *     {@link #addSynchronizedEntityName}, or
  *     {@link #addSynchronizedQuerySpace}.
  * </ul>
+ * <p>
+ * When the affected tables are not known to Hibernate, the behavior depends
+ * on whether Hibernate is operating in fully JPA-compliant mode.
+ * <ul>
+ * <li>In JPA-compliant mode, {@link FlushModeType#AUTO} specifies that the
+ *     session should be flushed before execution of a native query when the
+ *     affected tables are not known.
+ * <li>Otherwise, when Hibernate is not operating in JPA-compliant mode,
+ *     {@code AUTO} specifies that the session is <em>not</em> flushed before
+ *     execution of a native query, unless the affected tables are known and
+ *     Hibernate determines that a flush is required.
+ * </ul>
  *
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -643,31 +643,27 @@ private boolean startsWithSelect() {
 
 	@Override
 	protected void prepareForExecution() {
-		if ( getSynchronizedQuerySpaces() != null && !getSynchronizedQuerySpaces().isEmpty() ) {
-			// The application defined query spaces on the Hibernate NativeQuery
-			// which means the query will already perform a partial flush
-			// according to the defined query spaces, no need to do a full flush.
-			return;
-		}
-
-		// otherwise we need to flush.  the query itself is not required to execute
-		// in a transaction; if there is no transaction, the flush would throw a
-		// TransactionRequiredException which would potentially break existing
-		// apps, so we only do the flush if a transaction is in progress.
-		//
-		// NOTE : this was added for JPA initially.  Perhaps we want to only do
-		// this from JPA usage?
-		if ( shouldFlush() ) {
-			getSession().flush();
+		if ( getSynchronizedQuerySpaces() == null || getSynchronizedQuerySpaces().isEmpty() ) {
+			// We need to flush. The query itself is not required to execute in a
+			// transaction; if there is no transaction, the flush would throw a
+			// TransactionRequiredException which would potentially break existing
+			// apps, so we only do the flush if a transaction is in progress.
+			if ( shouldFlush() ) {
+				getSession().flush();
+			}
+			// Reset the callback before every execution
+			callback = null;
 		}
-		// Reset the callback before every execution
-		callback = null;
+		// Otherwise, the application specified query spaces via the Hibernate
+		// SynchronizeableQuery and so the query will already perform a partial
+		// flush according to the defined query spaces - no need for a full flush.
 	}
 
 	private boolean shouldFlush() {
 		if ( getSession().isTransactionInProgress() ) {
 			final FlushMode flushMode = getQueryOptions().getFlushMode();
 			return switch ( flushMode == null ? getSession().getHibernateFlushMode() : flushMode ) {
+				// The JPA spec requires that we auto-flush before native queries
 				case AUTO -> getSession().getFactory().getSessionFactoryOptions().isJpaBootstrap();
 				case ALWAYS -> true;
 				default -> false;