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,25 @@
+package org.hibernate;
+
+/**
+ * Enumerates the possible flush modes for execution of a
+ * {@link org.hibernate.query.Query}.
+ *
+ * @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/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(),

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

@@ -13,6 +13,7 @@
 import java.util.Map;
 
 import org.hibernate.FlushMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.Session;
 
 import jakarta.persistence.FlushModeType;
@@ -30,36 +31,66 @@
  */
 public interface CommonQueryContract {
 
+	/**
+	 * The {@link ForcedFlushMode} in effect for this query.
+	 * <p>
+	 * By default, this is {@link ForcedFlushMode#NO_FORCING}, and the
+	 * {@link FlushMode} of the owning {@link Session} determines whether
+	 * it is flushed.
+	 *
+	 * @see Session#getHibernateFlushMode()
+	 */
+	ForcedFlushMode getForcedFlushMode();
+
+	/**
+	 * Set the {@link ForcedFlushMode} in to use for this query.
+	 *
+	 * @see Session#getHibernateFlushMode()
+	 */
+	CommonQueryContract setForcedFlushMode(ForcedFlushMode forcedFlushMode);
+
 	/**
 	 * The JPA {@link FlushModeType} in effect for this query.  By default, the
 	 * query inherits the {@link FlushMode} of the {@link Session} from which
 	 * it originates.
 	 *
-	 * @see #getHibernateFlushMode
-	 * @see Session#getHibernateFlushMode
+	 * @see #getForcedFlushMode()
+	 * @see #getHibernateFlushMode()
+	 * @see Session#getHibernateFlushMode()
+	 *
+	 * @deprecated use {@link #getForcedFlushMode()}
 	 */
+	@Deprecated(since = "6")
 	FlushModeType getFlushMode();
 
 	/**
 	 * Set the {@link FlushMode} in to use for this query.
+	 * <p>
+	 * Setting this to {@code null} ultimately indicates to use the
+	 * {@link FlushMode} of the Session. Use {@link #setHibernateFlushMode}
+	 * passing {@link FlushMode#MANUAL} instead to indicate that no automatic
+	 * flushing should occur.
 	 *
-	 * @implNote Setting to {@code null} ultimately indicates to use the
-	 * FlushMode of the Session.  Use {@link #setHibernateFlushMode} passing
-	 * {@link FlushMode#MANUAL} instead to indicate that no automatic flushing
-	 * should occur
-	 *
+	 * @see #getForcedFlushMode()
 	 * @see #getHibernateFlushMode()
 	 * @see Session#getHibernateFlushMode()
+	 *
+	 * @deprecated use {@link #setForcedFlushMode(ForcedFlushMode)}
 	 */
+	@Deprecated(since = "6")
 	CommonQueryContract setFlushMode(FlushModeType flushMode);
 
 	/**
-	 * The {@link FlushMode} in effect for this query.  By default, the query
+	 * The {@link FlushMode} in effect for this query. By default, the query
 	 * inherits the {@code FlushMode} of the {@link Session} from which it
 	 * originates.
 	 *
-	 * @see Session#getHibernateFlushMode
+	 * @see #getForcedFlushMode()
+	 * @see Session#getHibernateFlushMode()
+	 *
+	 * @deprecated use {@link #getForcedFlushMode()}
 	 */
+	@Deprecated(since = "6")
 	FlushMode getHibernateFlushMode();
 
 	/**
@@ -69,9 +100,13 @@ public interface CommonQueryContract {
 	 * {@link FlushMode} of the Session.  Use {@link FlushMode#MANUAL}
 	 * instead to indicate that no automatic flushing should occur.
 	 *
+	 * @see #getForcedFlushMode()
 	 * @see #getHibernateFlushMode()
 	 * @see Session#getHibernateFlushMode()
+	 *
+	 * @deprecated use {@link #setForcedFlushMode(ForcedFlushMode)}
 	 */
+	@Deprecated(since = "6")
 	CommonQueryContract setHibernateFlushMode(FlushMode flushMode);
 
 	/**

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

@@ -13,6 +13,7 @@
 import java.util.Map;
 
 import org.hibernate.FlushMode;
+import org.hibernate.ForcedFlushMode;
 import org.hibernate.Incubating;
 
 import jakarta.persistence.Parameter;
@@ -195,4 +196,7 @@ public interface MutationQuery extends CommonQueryContract {
 
 	@Override
 	MutationQuery setHibernateFlushMode(FlushMode flushMode);
+
+	@Override
+	MutationQuery setForcedFlushMode(ForcedFlushMode forcedFlushMode);
 }