17 Persistence Context

Each EntityManager has a persistence context (first-level cache). When a new entity is persisted, a detached entity is merged, or an entity is retrieved from database or 2nd-level cache, it will be managed and put into the persistence context.

EntityManager.find() method will look for the entity in persistence context before 2nd-level cache or database. However, CriteriaQuery or JPQL query will fetch data from database, and put entities in persistence context and 2nd-level cache.

CriteriaUpdate, CriteriaDelete, JPQL update/delete and native queries are not synchronized with persistence context. Affected entities should be refreshed or detached if necessary.

Synchronized Persistence Context

When a persistence context is synchronized with transaction, EntityManager.flush() or transaction.commit() will save new or updated entities in the persistence context to database. By default, a persistence context is synchronized. For example,

                                    Synchronized Persistence Context
    
    HTTP request                    Begin transaction
    ------------------------------- Add a new entity Employee
                                    Commit Transaction
    
    HTTP request                    Begin transaction
    ------------------------------- Add a list of phone numbers to the employee
                                    Commit Transaction
    
    HTTP request                    Begin transaction
    ------------------------------- Upload a list of photos for the employee
                                    Commit Transaction

Unsynchronized Persistence Context

New or updated entities in an unsynchronized persistence context will not be saved to database unless it is explicitly joined to transaction.

    EntityManagerFactory emf = Persistence.createEntityManagerFactory();
    EntityManager em = emf.createEntityManager(SynchronizationType.UNSYNCHRONIZED);
    
    // persist new entities, merge or remove entities
    ...
    
    // join to transaction
    em.joinTransaction();
    
    EntityTransaction transaction = em.getTransaction();
    transaction.commit();

After transaction is completed(committed or rolled back), an unsynchronized persistence context will be detached from transaction, and it needs to be explicitly joined to transaction again if necessary. For example,

                                    Unsynchronized Persistence Context
    HTTP request
    ------------------------------- Add a new entity Employee
    
    HTTP request
    ------------------------------- Add a list of phone numbers to the employee
    
    HTTP request
    ------------------------------- Upload a list of photos for the employee
    
    HTTP request                    Begin Transaction
    ------------------------------- Join to transaction, save the Employee entity and 
                                    associated phone numbers and photos to database.
                                    Commit Transaction

← Entity Listeners→ CacheFrames / No Frames