6. 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.

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 JPA defines only two flushing strategies (AUTO and 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.

6.1. 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

6.1.1. AUTO flush on commit

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

Example 372. Automatic flushing on commit

  1. entityManager = entityManagerFactory().createEntityManager();
  2. txn = entityManager.getTransaction();
  3. txn.begin();
  5. Person person = new Person( "John Doe" );
  6. entityManager.persist( person );
  7. log.info( "Entity is in persisted state" );
  9. txn.commit();
  1. --INFO: Entity is in persisted state
  2. INSERT INTO Person (name, id) VALUES ('John Doe', 1)

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

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.

6.1.2. AUTO flush on JPQL/HQL query

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

Example 373. Automatic flushing on JPQL/HQL

  1. Person person = new Person( "John Doe" );
  2. entityManager.persist( person );
  3. entityManager.createQuery( "select p from Advertisement p" ).getResultList();
  4. entityManager.createQuery( "select p from Person p" ).getResultList();
  1. SELECT a.id AS id1_0_ ,
  2.        a.title AS title2_0_
  3. FROM   Advertisement a
  5. INSERT INTO Person (name, id) VALUES ('John Doe', 1)
  7. SELECT p.id AS id1_1_ ,
  8.        p.name AS name2_1_
  9. FROM   Person p

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 374. Automatic flushing on JPQL/HQL entities

  1. @Entity(name = "Person")
  2. public static class Person {
  4.     @Id
  5.     @GeneratedValue
  6.     private Long id;
  8.     private String name;
  10.     //Getters and setters are omitted for brevity
  12. }
  14. @Entity(name = "Advertisement")
  15. public static class Advertisement {
  17.     @Id
  18.     @GeneratedValue
  19.     private Long id;
  21.     private String title;
  23.     //Getters and setters are omitted for brevity
  25. }

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

Example 375. Automatic flushing on JPQL/HQL

  1. Person person = new Person( "John Doe" );
  2. entityManager.persist( person );
  3. entityManager.createQuery( "select p from Person p" ).getResultList();
  1. INSERT INTO Person (name, id) VALUES ('John Doe', 1)
  3. SELECT p.id AS id1_1_ ,
  4.        p.name AS name2_1_
  5. FROM   Person p

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

6.1.3. AUTO flush on native SQL query

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

Example 376. Automatic flushing on native SQL using EntityManager

  1. assertTrue(((Number) entityManager
  2.         .createNativeQuery( "select count(*) from Person")
  3.         .getSingleResult()).intValue() == 0 );
  5. Person person = new Person( "John Doe" );
  6. entityManager.persist( person );
  8. assertTrue(((Number) entityManager
  9.         .createNativeQuery( "select count(*) from Person")
  10.         .getSingleResult()).intValue() == 1 );

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

Example 377. Automatic flushing on native SQL using Session

  1. assertTrue(((Number) session
  2.         .createNativeQuery( "select count(*) from Person")
  3.         .getSingleResult()).intValue() == 0 );
  5. Person person = new Person( "John Doe" );
  6. session.persist( person );
  8. assertTrue(((Number) session
  9.         .createNativeQuery( "select count(*) from Person")
  10.         .uniqueResult()).intValue() == 0 );

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

Example 378. Automatic flushing on native SQL with Session synchronization

  1. assertTrue(((Number) entityManager
  2.         .createNativeQuery( "select count(*) from Person")
  3.         .getSingleResult()).intValue() == 0 );
  5. Person person = new Person( "John Doe" );
  6. entityManager.persist( person );
  7. Session session = entityManager.unwrap( Session.class );
  9. assertTrue(((Number) session
  10.         .createNativeQuery( "select count(*) from Person")
  11.         .addSynchronizedEntityClass( Person.class )
  12.         .uniqueResult()).intValue() == 1 );

6.2. COMMIT flush

JPA 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 JPA 2.1 Specification

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

Example 379. COMMIT flushing on JPQL

  1. Person person = new Person("John Doe");
  2. entityManager.persist(person);
  4. entityManager.createQuery("select p from Advertisement p")
  5.     .setFlushMode( FlushModeType.COMMIT)
  6.     .getResultList();
  8. entityManager.createQuery("select p from Person p")
  9.     .setFlushMode( FlushModeType.COMMIT)
  10.     .getResultList();
  1. SELECT a.id AS id1_0_ ,
  2.        a.title AS title2_0_
  3. FROM   Advertisement a
  5. SELECT p.id AS id1_1_ ,
  6.        p.name AS name2_1_
  7. FROM   Person p
  9. INSERT INTO Person (name, id) VALUES ('John Doe', 1)

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

Example 380. COMMIT flushing on native SQL

  1. Person person = new Person("John Doe");
  2. entityManager.persist(person);
  4. assertTrue(((Number) entityManager
  5.     .createNativeQuery("select count(*) from Person")
  6.     .getSingleResult()).intValue() == 1);
  1. INSERT INTO Person (name, id) VALUES ('John Doe', 1)
  3. SELECT COUNT(*) FROM Person

6.3. ALWAYS flush

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 381. COMMIT flushing on native SQL

  1. Person person = new Person("John Doe");
  2. entityManager.persist(person);
  4. Session session = entityManager.unwrap( Session.class);
  5. assertTrue(((Number) session
  6.         .createNativeQuery("select count(*) from Person")
  7.         .setFlushMode( FlushMode.ALWAYS)
  8.         .uniqueResult()).intValue() == 1);
  1. INSERT INTO Person (name, id) VALUES ('John Doe', 1)
  3. SELECT COUNT(*) FROM Person

6.4. 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 382. MANUAL flushing

  1. Person person = new Person("John Doe");
  2. entityManager.persist(person);
  4. Session session = entityManager.unwrap( Session.class);
  5. session.setHibernateFlushMode( FlushMode.MANUAL );
  7. assertTrue(((Number) entityManager
  8.     .createQuery("select count(id) from Person")
  9.     .getSingleResult()).intValue() == 0);
  11. assertTrue(((Number) session
  12.     .createNativeQuery("select count(*) from Person")
  13.     .uniqueResult()).intValue() == 0);
  1. SELECT COUNT(p.id) AS col_0_0_
  2. FROM   Person p
  4. SELECT COUNT(*)
  5. FROM   Person

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

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

6.5. 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 383. Flush operation order

  1. Person person = entityManager.find( Person.class, 1L);
  2. entityManager.remove(person);
  4. Person newPerson = new Person( );
  5. newPerson.setId( 2L );
  6. newPerson.setName( "John Doe" );
  7. entityManager.persist( newPerson );
  1. INSERT INTO Person (name, id)
  2. VALUES ('John Doe', 2L)
  4. DELETE FROM Person WHERE id = 1

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

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