Skip to content

Latest commit

 

History

History
287 lines (224 loc) · 9.88 KB

Flushing.adoc

File metadata and controls

287 lines (224 loc) · 9.88 KB

Flushing

Flushing is the process of synchronizing the state of the persistence context with the underlying database. The EntityManager and the Hibernate Session expose a set of methods, through which the application developer can change the persistent state of an entity.

The persistence context acts as a transactional write-behind cache, queuing any entity state change. Like any write-behind cache, changes are first applied in-memory and synchronized with the database during the flush time. The flush operation takes every entity state change and translates it to an INSERT, UPDATE or DELETE statement.

Note

Because DML statements are grouped together, Hibernate can apply batching transparently. See the Batching chapter for more information.

The flushing strategy is given by the flushMode of the current running Hibernate Session. Although Jakarta Persistence defines only two flushing strategies ({jpaJavadocUrlPrefix}FlushModeType.html#AUTO[AUTO] and {jpaJavadocUrlPrefix}FlushModeType.html#COMMIT[COMMIT]), Hibernate has a much broader spectrum of flush types:

ALWAYS

Flushes the Session before every query.

AUTO

This is the default mode, and it flushes the Session only if necessary.

COMMIT

The Session tries to delay the flush until the current Transaction is committed, although it might flush prematurely too.

MANUAL

The Session flushing is delegated to the application, which must call Session.flush() explicitly in order to apply the persistence context changes.

AUTO flush

By default, Hibernate uses the AUTO flush mode which triggers a flush in the following circumstances:

  • prior to committing a Transaction

  • prior to executing a JPQL/HQL query that overlaps with the queued entity actions

  • before executing any native SQL query that has no registered synchronization

AUTO flush on commit

In the following example, an entity is persisted, and then the transaction is committed.

Example 1. Automatic flushing on commit
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]
link:extras/flushing-auto-flush-commit-example.sql[role=include]

Hibernate logs the message prior to inserting the entity because the flush only occurred during transaction commit.

Note

This is valid for the SEQUENCE and TABLE identifier generators. The IDENTITY generator must execute the insert right after calling persist(). For more details, see the discussion of generators in Identifier generators.

AUTO flush on JPQL/HQL query

A flush may also be triggered when executing an entity query.

Example 2. Automatic flushing on JPQL/HQL
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]
link:extras/flushing-auto-flush-jpql-example.sql[role=include]

The reason why the Advertisement entity query didn’t trigger a flush is that there’s no overlapping between the Advertisement and the Person tables:

Example 3. Automatic flushing on JPQL/HQL entities
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]

When querying for a Person entity, the flush is triggered prior to executing the entity query.

Example 4. Automatic flushing on JPQL/HQL
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]
link:extras/flushing-auto-flush-jpql-overlap-example.sql[role=include]

This time, the flush was triggered by a JPQL query because the pending entity persisting action overlaps with the query being executed.

AUTO flush on native SQL query

When executing a native SQL query, a flush is always triggered when using the EntityManager API.

Example 5. Automatic flushing on native SQL using EntityManager
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]

If you bootstrap Hibernate natively, and not through Jakarta Persistence, by default, the Session API will trigger a flush automatically when executing a native query.

Example 6. Automatic flushing on native SQL using Session
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/HibernateAutoFlushTest.java[role=include]

To flush the Session, the query must use a synchronization:

Example 7. Automatic flushing on native SQL with Session synchronization
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AutoFlushTest.java[role=include]

COMMIT flush

Jakarta Persistence also defines a COMMIT flush mode, which is described as follows:

If FlushModeType.COMMIT is set, the effect of updates made to entities in the persistence context upon queries is unspecified.

— Section 3.10.8 of the Java Persistence 2.1 Specification

When executing a JPQL query, the persistence context is only flushed when the current running transaction is committed.

Example 8. COMMIT flushing on JPQL
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/CommitFlushTest.java[role=include]
link:extras/flushing-commit-flush-jpql-example.sql[role=include]

Because the Jakarta Persistence doesn’t impose a strict rule on delaying flushing, when executing a native SQL query, the persistence context is going to be flushed.

Example 9. COMMIT flushing on native SQL
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/CommitFlushTest.java[role=include]
link:extras/flushing-commit-flush-sql-example.sql[role=include]

ALWAYS flush

Note

The ALWAYS is only available with the native Session API.

The ALWAYS flush mode triggers a persistence context flush even when executing a native SQL query against the Session API.

Example 10. COMMIT flushing on native SQL
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/AlwaysFlushTest.java[role=include]
link:extras/flushing-always-flush-sql-example.sql[role=include]

MANUAL flush

Both the EntityManager and the Hibernate Session define a flush() method that, when called, triggers a manual flush. Hibernate also provides a MANUAL flush mode so the persistence context can only be flushed manually.

Example 11. MANUAL flushing
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/ManualFlushTest.java[role=include]
link:extras/flushing-manual-flush-example.sql[role=include]

The INSERT statement was not executed because there was no manual flush() call.

Note

The MANUAL flush mode is useful when using multi-request logical transactions, and only the last request should flush the persistence context.

Flush operation order

From a database perspective, a row state can be altered using either an INSERT, an UPDATE or a DELETE statement. Because entity state changes are automatically converted to SQL statements, it’s important to know which entity actions are associated with a given SQL statement.

INSERT

The INSERT statement is generated either by the EntityInsertAction or EntityIdentityInsertAction. These actions are scheduled by the persist operation, either explicitly or through cascading the PersistEvent from a parent to a child entity.

DELETE

The DELETE statement is generated by the EntityDeleteAction or OrphanRemovalAction.

UPDATE

The UPDATE statement is generated by EntityUpdateAction during flushing if the managed entity has been marked modified. The dirty checking mechanism is responsible for determining if a managed entity has been modified since it was first loaded.

Hibernate does not execute the SQL statements in the order of their associated entity state operations.

To visualize how this works, consider the following example:

Example 12. Flush operation order
link:../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/flush/FlushOrderTest.java[role=include]
link:extras/flushing-order-example.sql[role=include]

Even if we removed the first entity and then persist a new one, Hibernate is going to execute the DELETE statement after the INSERT.

Tip

The order in which SQL statements are executed is given by the ActionQueue and not by the order in which entity state operations have been previously defined.

The ActionQueue executes all operations in the following order:

  1. OrphanRemovalAction

  2. EntityInsertAction or EntityIdentityInsertAction

  3. EntityUpdateAction

  4. QueuedOperationCollectionAction

  5. CollectionRemoveAction

  6. CollectionUpdateAction

  7. CollectionRecreateAction

  8. EntityDeleteAction