HHH-15942 introduce ForcedFlushMode for specifying whether a query flushes or not

- replaces FlushModeType in the annotation package
- much less confusing when applied to a Query
  * what do MANUAL and COMMIT mean for a Query?
  * how is AUTO useful for a Query?

- also make Query.getHibernateFlushMode() obey its
  documented semantics by returning the session
  flush mode instead of null when unset

Author: gavinking

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

@@ -0,0 +1,33 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate;
+
+/**
+ * Enumerates the possible flush modes for execution of a
+ * {@link org.hibernate.query.Query}. A "forced" flush mode
+ * overrides the {@linkplain Session#getHibernateFlushMode()
+ * flush mode of the session}.
+ *
+ * @author Gavin King
+ *
+ * @since 6.2
+ */
+public enum ForcedFlushMode {
+	/**
+	 * Flush before executing the query.
+	 */
+	FORCE_FLUSH,
+	/**
+	 * Do not flush before executing the query.
+	 */
+	FORCE_NO_FLUSH,
+	/**
+	 * Let the owning {@link Session session} decide whether
+	 * to flush, depending on its {@link FlushMode}.
+	 */
+	NO_FORCING
+}

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

@@ -148,7 +148,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void flush();
 
 	/**
-	 * Set the current {@link FlushModeType JPA flush mode} for this session.
+	 * Set the current {@linkplain FlushModeType JPA flush mode} for this session.
 	 * <p>
 	 * <em>Flushing</em> is the process of synchronizing the underlying persistent
 	 * store with persistable state held in memory. The current flush mode determines
@@ -162,7 +162,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setFlushMode(FlushModeType flushMode);
 
 	/**
-	 * Set the current {@link FlushMode flush mode} for this session.
+	 * Set the current {@linkplain FlushMode flush mode} for this session.
 	 * <p>
 	 * <em>Flushing</em> is the process of synchronizing the underlying persistent
 	 * store with persistable state held in memory. The current flush mode determines
@@ -180,22 +180,22 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setHibernateFlushMode(FlushMode flushMode);
 
 	/**
-	 * Get the current {@link FlushModeType JPA flush mode} for this session.
+	 * Get the current {@linkplain FlushModeType JPA flush mode} for this session.
 	 *
 	 * @return the {@link FlushModeType} currently in effect
 	 */
 	@Override
 	FlushModeType getFlushMode();
 
 	/**
-	 * Get the current {@link FlushMode flush mode} for this session.
+	 * Get the current {@linkplain FlushMode flush mode} for this session.
 	 *
 	 * @return the {@link FlushMode} currently in effect
 	 */
 	FlushMode getHibernateFlushMode();
 
 	/**
-	 * Set the current {@link CacheMode cache mode} for this session.
+	 * Set the current {@linkplain CacheMode cache mode} for this session.
 	 * <p>
 	 * The cache mode determines the manner in which this session can interact with
 	 * the second level cache.
@@ -205,7 +205,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setCacheMode(CacheMode cacheMode);
 
 	/**
-	 * Get the current {@link CacheMode cache mode} for this session.
+	 * Get the current {@linkplain CacheMode cache mode} for this session.
 	 *
 	 * @return the current cache mode
 	 */

hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java

@@ -16,7 +16,10 @@
  *
  * @see NamedQuery
  * @see NamedNativeQuery
+ *
+ * @deprecated use {@link org.hibernate.ForcedFlushMode}
  */
+@Deprecated(since="6")
 public enum FlushModeType {
 	/**
 	 * Corresponds to {@link org.hibernate.FlushMode#ALWAYS}.

hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java

@@ -13,6 +13,7 @@
 import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
 import org.hibernate.CacheMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.Remove;
 
 import static java.lang.annotation.ElementType.PACKAGE;
@@ -64,12 +65,23 @@
 	 */
 	String resultSetMapping() default "";
 
+	/**
+	 * Determines whether the session should be flushed before
+	 * executing the query.
+	 *
+	 * @see org.hibernate.query.CommonQueryContract#setForcedFlushMode(ForcedFlushMode)
+	 */
+	ForcedFlushMode flush() default ForcedFlushMode.NO_FORCING;
+
 	/**
 	 * The flush mode for the query.
 	 *
 	 * @see org.hibernate.query.CommonQueryContract#setFlushMode(jakarta.persistence.FlushModeType)
 	 * @see org.hibernate.jpa.HibernateHints#HINT_FLUSH_MODE
+	 *
+	 * @deprecated use {@link #flush()}
 	 */
+	@Deprecated(since = "6")
 	FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT;
 
 	/**

hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java

@@ -12,6 +12,7 @@
 
 import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.Remove;
 
 import static java.lang.annotation.ElementType.PACKAGE;
@@ -47,12 +48,23 @@
 	 */
 	String query();
 
+	/**
+	 * Determines whether the session should be flushed before
+	 * executing the query.
+	 *
+	 * @see org.hibernate.query.CommonQueryContract#setForcedFlushMode(ForcedFlushMode)
+	 */
+	ForcedFlushMode flush() default ForcedFlushMode.NO_FORCING;
+
 	/**
 	 * The flush mode for this query.
 	 *
 	 * @see org.hibernate.query.CommonQueryContract#setFlushMode(jakarta.persistence.FlushModeType)
 	 * @see org.hibernate.jpa.HibernateHints#HINT_FLUSH_MODE
+	 *
+	 * @deprecated use {@link #flush()}
 	 */
+	@Deprecated(since = "6")
 	FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT;
 
 	/**

hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java

@@ -14,6 +14,7 @@
 import org.hibernate.AssertionFailure;
 import org.hibernate.CacheMode;
 import org.hibernate.FlushMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.Remove;
 import org.hibernate.annotations.CacheModeType;
 import org.hibernate.annotations.FlushModeType;
@@ -29,6 +30,7 @@
 import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.internal.log.DeprecationLogger;
 import org.hibernate.jpa.HibernateHints;
+import org.hibernate.jpa.internal.util.FlushModeTypeHelper;
 import org.hibernate.query.sql.internal.ParameterParser;
 import org.hibernate.query.sql.spi.ParameterRecognizer;
 import org.hibernate.type.BasicType;
@@ -184,7 +186,7 @@ public static void bindNativeQuery(
 				.setCacheMode(  getCacheMode( namedNativeQuery )  )
 				.setTimeout( namedNativeQuery.timeout() < 0 ? null : namedNativeQuery.timeout() )
 				.setFetchSize( namedNativeQuery.fetchSize() < 0 ? null : namedNativeQuery.fetchSize() )
-				.setFlushMode( getFlushMode( namedNativeQuery.flushMode() ) )
+				.setFlushMode( getFlushMode( namedNativeQuery.flush(), namedNativeQuery.flushMode() ) )
 				.setReadOnly( namedNativeQuery.readOnly() )
 				.setQuerySpaces( setOf( namedNativeQuery.querySpaces() ) )
 				.setComment(nullIfEmpty(namedNativeQuery.comment()));
@@ -341,7 +343,7 @@ public static void bindQuery(
 				.setCacheMode( getCacheMode( namedQuery ) )
 				.setTimeout( namedQuery.timeout() < 0 ? null : namedQuery.timeout() )
 				.setFetchSize( namedQuery.fetchSize() < 0 ? null : namedQuery.fetchSize() )
-				.setFlushMode( getFlushMode( namedQuery.flushMode() ) )
+				.setFlushMode( getFlushMode( namedQuery.flush(), namedQuery.flushMode() ) )
 				.setReadOnly( namedQuery.readOnly() )
 				.setComment( nullIfEmpty( namedQuery.comment() ) );
 
@@ -364,6 +366,12 @@ private static CacheMode getCacheMode(org.hibernate.annotations.NamedNativeQuery
 		return cacheMode == null || cacheMode == CacheMode.NORMAL ? getCacheMode( namedNativeQuery.cacheMode() ) : cacheMode;
 	}
 
+	private static FlushMode getFlushMode(ForcedFlushMode forcedFlushMode, FlushModeType flushModeType) {
+		return forcedFlushMode == ForcedFlushMode.NO_FORCING
+				? getFlushMode( flushModeType )
+				: FlushModeTypeHelper.getFlushMode( forcedFlushMode );
+	}
+
 	private static FlushMode getFlushMode(FlushModeType flushModeType) {
 		switch ( flushModeType ) {
 			case ALWAYS:

hibernate-core/src/main/java/org/hibernate/graph/internal/parse/GraphParser.java

@@ -18,8 +18,6 @@
 import org.hibernate.internal.util.collections.Stack;
 import org.hibernate.internal.util.collections.StandardStack;
 
-import org.jboss.logging.Logger;
-
 import org.antlr.v4.runtime.CharStreams;
 import org.antlr.v4.runtime.CommonTokenStream;
 

hibernate-core/src/main/java/org/hibernate/jpa/internal/util/FlushModeTypeHelper.java

@@ -12,6 +12,7 @@
 
 import org.hibernate.AssertionFailure;
 import org.hibernate.FlushMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.MappingException;
 
 import org.jboss.logging.Logger;
@@ -28,33 +29,69 @@ private FlushModeTypeHelper() {
 	}
 
 	public static FlushModeType getFlushModeType(FlushMode flushMode) {
-		if ( flushMode == FlushMode.ALWAYS ) {
-			log.debug( "Interpreting Hibernate FlushMode#ALWAYS to JPA FlushModeType#AUTO; may cause problems if relying on FlushMode#ALWAYS-specific behavior" );
-			return FlushModeType.AUTO;
+		if ( flushMode == null ) {
+			return null;
 		}
-		else if ( flushMode == FlushMode.MANUAL ) {
-			log.debug( "Interpreting Hibernate FlushMode#MANUAL to JPA FlushModeType#COMMIT; may cause problems if relying on FlushMode#MANUAL-specific behavior" );
-			return FlushModeType.COMMIT;
+		switch ( flushMode ) {
+			case ALWAYS:
+				log.debug( "Interpreting Hibernate FlushMode#ALWAYS to JPA FlushModeType#AUTO; may cause problems if relying on FlushMode#ALWAYS-specific behavior" );
+				return FlushModeType.AUTO;
+			case MANUAL:
+				log.debug( "Interpreting Hibernate FlushMode#MANUAL to JPA FlushModeType#COMMIT; may cause problems if relying on FlushMode#MANUAL-specific behavior" );
+				return FlushModeType.COMMIT;
+			case COMMIT:
+				return FlushModeType.COMMIT;
+			case AUTO:
+				return FlushModeType.AUTO;
+			default:
+				throw new AssertionFailure( "unhandled FlushMode " + flushMode );
 		}
-		else if ( flushMode == FlushMode.COMMIT ) {
-			return FlushModeType.COMMIT;
+	}
+
+	public static ForcedFlushMode getForcedFlushMode(FlushMode flushMode) {
+		if ( flushMode == null ) {
+			return ForcedFlushMode.NO_FORCING;
 		}
-		else if ( flushMode == FlushMode.AUTO ) {
-			return FlushModeType.AUTO;
+		switch ( flushMode ) {
+			case ALWAYS:
+				return ForcedFlushMode.FORCE_FLUSH;
+			case COMMIT:
+			case MANUAL:
+				return ForcedFlushMode.FORCE_NO_FLUSH;
+			case AUTO:
+				// this is not precisely correctly correct, but good enough
+				return ForcedFlushMode.NO_FORCING;
+			default:
+				throw new AssertionFailure( "unhandled FlushMode " + flushMode );
 		}
-
-		throw new AssertionFailure( "unhandled FlushMode " + flushMode );
 	}
 
 	public static FlushMode getFlushMode(FlushModeType flushModeType) {
-		if ( flushModeType == FlushModeType.AUTO ) {
-			return FlushMode.AUTO;
+		if ( flushModeType == null ) {
+			return null;
 		}
-		else if ( flushModeType == FlushModeType.COMMIT ) {
-			return FlushMode.COMMIT;
+		switch ( flushModeType ) {
+			case AUTO:
+				return FlushMode.AUTO;
+			case COMMIT:
+				return FlushMode.COMMIT;
+			default:
+				throw new AssertionFailure( "unhandled FlushModeType " + flushModeType );
 		}
+	}
 
-		throw new AssertionFailure( "unhandled FlushModeType " + flushModeType );
+	public static FlushMode getFlushMode(ForcedFlushMode forcedFlushMode) {
+		if ( forcedFlushMode == null ) {
+			return null;
+		}
+		switch ( forcedFlushMode ) {
+			case FORCE_FLUSH:
+				return FlushMode.ALWAYS;
+			case FORCE_NO_FLUSH:
+				return FlushMode.MANUAL;
+			default:
+				return null;
+		}
 	}
 
 	public static FlushMode interpretFlushMode(Object value) {

hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java

@@ -784,7 +784,7 @@ public NamedCallableQueryMemento toMemento(String name) {
 				isCacheable(),
 				getCacheRegion(),
 				getCacheMode(),
-				getHibernateFlushMode(),
+				getQueryOptions().getFlushMode(),
 				isReadOnly(),
 				getTimeout(),
 				getFetchSize(),