Enum Class QueryFlushMode

java.lang.Object
java.lang.Enum<QueryFlushMode>
jakarta.persistence.QueryFlushMode
All Implemented Interfaces:
Statement.Option, StoredProcedureQuery.Option, TypedQuery.Option, Serializable, Comparable<QueryFlushMode>, Constable
public enum QueryFlushMode extends Enum<QueryFlushMode> implements TypedQuery.Option, Statement.Option, StoredProcedureQuery.Option
Enumerates the possible flush modes for execution of a Query. An explicitly-specified query-level flush mode overrides the current flush mode of the persistence context.

When a Jakarta Persistence or native SQL query is executed within a transaction via an instance of Query obtained from an EntityManager joined to the transaction, the effective flush mode is determined by the current flush mode of the Query object, if any flush mode has been specified by calling Query.setFlushMode(FlushModeType) or Query.setQueryFlushMode(QueryFlushMode), or, otherwise, by the current flush mode of the persistence context.

  • If FLUSH is set, the persistence provider is required to flush modifications to the database before executing the query.
  • If NO_FLUSH is set, the persistence provider is not required to flush modifications to the database before executing the query; if, in addition, the current flush mode of the entity manager is FlushModeType.EXPLICIT, the persistence provider is not permitted to flush modifications to the database.
Otherwise, if DEFAULT is set:
  • If FlushModeType.AUTO is in effect, the 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 provider implementation might guarantee this by flushing pending updates to modified entities to the database before executing the query.
  • If FlushModeType.EXPLICIT is in effect, the provider is not permitted to flush modifications to the database before executing the query. Pending modifications to entities in the persistence context might not be visible to the processing of the query.
  • If FlushModeType.COMMIT is in effect, it is unspecified how pending modifications to entities in the persistence context affect the results of the query.

When there is no transaction active, or if the persistence context has not been joined to the current transaction, the persistence provider must not flush pending modifications to the database, regardless of the flush mode.

An EntityAgent has no associated persistence context, and so flush modes have no effect on an entity agent, nor on Query objects created by an entity agent.

Since:
4.0
See Also:

  • Enum Constant Details

    • FLUSH

      public static final QueryFlushMode FLUSH
      The persistence provider is required to flush pending modifications to the database before executing the query. Pending modifications to entities held in the persistence context are always visible to the processing of the query. The current flush mode of the persistence context is completely overridden.

    • NO_FLUSH

      public static final QueryFlushMode NO_FLUSH
      The persistence provider is not required to flush pending modifications to the database before executing the query. Pending modifications to entities held in the persistence context might not be visible to the processing of the query.
      • If the current flush mode of the persistence context is FlushModeType.EXPLICIT, the persistence provider is not permitted to flush pending modifications before executing the query.
      • Otherwise, this mode is considered a hint to the persistence provider.

    • DEFAULT

      public static final QueryFlushMode DEFAULT
      The persistence provider must determine whether to flush before executing the query by considering the current flush mode of the persistence context.

  • Method Details

    • values

      public static QueryFlushMode[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static QueryFlushMode valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null