Improve language around queries and FlushModeType.AUTO

api/src/main/java/jakarta/persistence/FlushModeType.java

@@ -19,23 +19,27 @@
 /**
  * Enumerates flush modes recognized by the {@link EntityManager}.
  *
- * <p>When queries are executed within a transaction, if {@link #AUTO}
- * is set on the {@link Query Query} or {@link TypedQuery} object, or
- * if the flush mode setting for the persistence context is {@code AUTO}
- * (the default) and a flush mode setting has not been specified for the
- * {@code Query} or {@code TypedQuery} object, the persistence provider
- * is responsible for ensuring that all updates to the state of all
- * entities in the persistence context which could potentially affect
- * the result of the query are visible to the processing of the query.
- * The persistence provider implementation may achieve this by flushing
- * updates to those entities to the database or by some other means.
+ * <p>When a query is executed within a transaction:
+ * <ul>
+ * <li>If {@link #AUTO} is set via the {@link Query Query} or
+ *     {@link TypedQuery} object, or if the flush mode setting for
+ *     the persistence context is {@code AUTO} (the default) and a
+ *     flush mode setting has not been specified for the {@code Query}
+ *     or {@code TypedQuery} object, the persistence provider must
+ *     ensure that every modification to the state of every entity
+ *     associated with the persistence context which could possibly
+ *     affect the result of the query is visible to the processing
+ *     of the query. The persistence provider implementation might
+ *     guarantee this by flushing pending updates to modified
+ *     entities to the database before executing the query.
+ * <li>On the other hand, if {@link #COMMIT} is set, the effect of
+ *     updates made to entities in the persistence context on query
+ *     results is unspecified.
+ * </ul>
  *
- * <p>On the other hand, if {@link #COMMIT} is set, the effect of updates
- * made to entities in the persistence context on queries is unspecified.
- *
- * <p>If there is no transaction active or the persistence context is
- * not joined to the current transaction, the persistence provider must
- * not flush to the database.
+ * <p>If there is no transaction active or if the persistence context
+ * is not joined to the current transaction, the persistence provider
+ * must not flush to the database, regardless of flush mode.
  *
  * @see EntityManager#setFlushMode(FlushModeType)
  * @see Query#setFlushMode(FlushModeType)

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -2338,7 +2338,7 @@ conversions to the corresponding values in the query result before
 returning them to the application. The use of functions, including
 aggregates, on converted attributes is undefined. If an exception is
 thrown from a conversion method, the persistence provider must wrap the
-exception in a PersistenceException and, if the persistence context is
+exception in a `PersistenceException` and, if the persistence context is
 joined to a transaction, mark the transaction for rollback.
 
 === Second-Level Cache [[a3061]]
@@ -2603,34 +2603,36 @@ public List findWithName(String name) {
 
 ==== Queries and Flush Mode [[a4374]]
 
-The flush mode setting affects the result of
-a query as follows.
-
-When queries are executed within a
-transaction, if `FlushModeType.AUTO` is set on the `Query`,
-`TypedQuery`, or `StoredProcedureQuery` object, or if the flush mode
-setting for the persistence context is `AUTO` (the default) and a flush
-mode setting has not been specified for the query object, the
-persistence provider is responsible for ensuring that all updates to the
-state of all entities in the persistence context which could potentially
-affect the result of the query are visible to the processing of the
-query. The persistence provider implementation may achieve this by
-flushing those entities to the database or by some other means. If
-`FlushModeType.COMMIT` is set, the effect of updates made to entities in
-the persistence context upon queries is unspecified.
-
-If the persistence context has not been
-joined to the current transaction, the persistence provider must not
-flush to the database regardless of the flush mode setting.
+The _flush mode_ setting may affect the result of a query.
+The possible flush modes are enumerated by `FlushModeType`.
+
 
 [source,java]
 ----
 include::../../../../api/src/main/java/jakarta/persistence/FlushModeType.java[lines=18..-1]
 ----
 
+When a query is executed within a transaction:
+
+- If `FlushModeType.AUTO` is set via the `Query`, `TypedQuery`, or
+  `StoredProcedureQuery` object, or if the flush mode  setting for
+  the persistence context is `AUTO` (the default) and a flush
+  mode setting has not been specified for the query object, the
+  persistence provider must ensure that every modification to the
+  state of every entity associated with the persistence context
+  which could possibly affect the result of the query is visible
+  to the processing of the query. The persistence provider
+  implementation might guarantee this by flushing pending updates
+  to modified entities to the database before executing the query.
+
+- On the other hand, if `FlushModeType.COMMIT` is set, the effect
+  of updates made to entities in the persistence context on query
+  results is unspecified.
+
+If there is no transaction active or if the persistence context has
+not been joined to the current transaction, the persistence provider
+must not flush to the database, regardless of the flush mode.
 
-If there is no transaction active, the
-persistence provider must not flush to the database.
 
 ==== Queries and Lock Mode [[a4385]]