JPA/Hibernate Persistence Context

1. Overview

Persistence providers like Hibernate make use of persistence context to manage the entity lifecycle in an application.

In this tutorial, we’ll start with the introduction of the persistence context, then we’ll see why it’s important. Finally, we’ll see the difference between transaction-scoped persistence context and extended-scoped persistence context with examples.

2. Persistence Context

Let’s take a look at the official definition of the Persistence Context:

An EntityManager instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle are managed. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.

The above statement may seem a bit complex right now, but it will make complete sense as we proceed. The persistence context is the first-level cache where all the entities are fetched from the database or saved to the database. It sits between our application and persistent storage.

Persistence context keeps track of any changes made into a managed entity. If anything changes during a transaction, then the entity is marked as dirty. When the transaction completes, these changes are flushed into persistent storage.

The EntityManager is the interface that lets us interact with the persistence context. Whenever we use the EntityManager, we are actually interacting with the persistence context.

If every change made in the entity makes a call to persistent storage, we can imagine how many calls will be made. This will lead to a performance impact because persistent storage calls are expensive.

3. Persistence Context Type

Persistence contexts are available in two types:

• Transaction-scoped persistence context
• Extended-scoped persistence context

Let’s take a look at each.

3.1. Transaction-Scoped Persistence Context

The transaction persistence context is bound to the transaction. As soon as the transaction finishes, the entities present in the persistence context will be flushed into persistent storage.

When we perform any operation inside the transaction, the EntityManager checks for a persistence context. If one exists, then it will be used. Otherwise, it will create a persistence context.

The default persistence context type is PersistenceContextType.TRANSACTION. To tell the EntityManager to use the transaction persistence context, we simply annotate it with @PersistenceContext:

@PersistenceContext
private EntityManager entityManager;

3.2. Extended-Scoped Persistence Context

An extended persistence context can span across multiple transactions. We can persist the entity without the transaction but cannot flush it without a transaction.

To tell EntityManager to use extended-scoped persistence context, we need to apply the type attribute of @PersistenceContext:

@PersistenceContext(type = PersistenceContextType.EXTENDED)
private EntityManager entityManager;

In the stateless session bean, the extended persistence context in one component is completely unaware of any persistence context of another component. This is true even if both are in same the same transaction.

Let’s say we persist some entity in a method of Component A, which is running in a transaction. We then call some method of Component B. In Component B’s method persistence context, we will not find the entity we persisted previously in the method of Component A.

4. Persistence Context Example

Now that we know enough about persistence context, it’s time to dive into an example. We’ll make different use cases with transaction persistence context and extended persistence context.

First, let’s create our service class, TransctionPersistenceContextUserService:

@Component
public class TransctionPersistenceContextUserService {

    @PersistenceContext
    private EntityManager entityManager;
    
    @Transactional
    public User insertWithTransaction(User user) {
        entityManager.persist(user);
        return user;
    }
    
    public User insertWithoutTransaction(User user) {
        entityManager.persist(user);
        return user;
    }
    
    public User find(long id) {
        return entityManager.find(User.class, id);
    }
}

The next class, ExtendedPersistenceContextUserService, is very similar to the above, except for the @PersistenceContext annotation. This time we pass PersistenceContextType.EXTENDED into the type parameter of its @PersistenceContext annotation:

@Component
public class ExtendedPersistenceContextUserService {

    @PersistenceContext(type = PersistenceContextType.EXTENDED)
    private EntityManager entityManager;

    // Remaining code same as above
}

5. Test Cases

Now that we have our service classes set up, it’s time to make different use cases with transaction persistence context and extended persistence context.

5.1. Testing Transaction Persistence Context

Let’s persist a User entity using transaction-scoped persistence context. The entity will be saved in persistent storage. We then verify by making a find call using our extended persistence context’s EntityManager:

User user = new User(121L, "Devender", "admin");
transctionPersistenceContext.insertWithTransaction(user);

User userFromTransctionPersistenceContext = transctionPersistenceContext
  .find(user.getId());
assertNotNull(userFromTransctionPersistenceContext);

User userFromExtendedPersistenceContext = extendedPersistenceContext
  .find(user.getId());
assertNotNull(userFromExtendedPersistenceContext);

When we try to insert a User entity without a transaction, then TransactionRequiredException will be thrown:

@Test(expected = TransactionRequiredException.class)
public void testThatUserSaveWithoutTransactionThrowException() {
    User user = new User(122L, "Devender", "admin");
    transctionPersistenceContext.insertWithoutTransaction(user);
}

5.2. Testing Extended Persistence Context

Next, let’s persist the user with an extended persistence context and without a transaction. The User entity will be saved in the persistence context (cache) but not in persistent storage:

User user = new User(123L, "Devender", "admin");
extendedPersistenceContext.insertWithoutTransaction(user);

User userFromExtendedPersistenceContext = extendedPersistenceContext
  .find(user.getId());
assertNotNull(userFromExtendedPersistenceContext);

User userFromTransctionPersistenceContext = transctionPersistenceContext
  .find(user.getId());
assertNull(userFromTransctionPersistenceContext);

In the persistence context for any persistent entity identity, there will be a unique entity instance. If we try to persist another entity with the same identifier:

@Test(expected = EntityExistsException.class)
public void testThatPersistUserWithSameIdentifierThrowException() {
    User user1 = new User(126L, "Devender", "admin");
    User user2 = new User(126L, "Devender", "admin");
    extendedPersistenceContext.insertWithoutTransaction(user1);
    extendedPersistenceContext.insertWithoutTransaction(user2);
}

We’ll see EntityExistsException:

jakarta.persistence.EntityExistsException: 
A different object with the same identifier value
was already associated with the session

Extended persistence context within a transaction saves the entity in persistent storage at the end of the transaction:

User user = new User(127L, "Devender", "admin");
extendedPersistenceContext.insertWithTransaction(user);

User userFromDB = transctionPersistenceContext.find(user.getId());
assertNotNull(userFromDB);

The extended persistence context flushes the cached entities into persistent storage when used within the transaction. First, we persist the entity without a transaction. Next, we persist another entity in the transaction:

User user1 = new User(124L, "Devender", "admin");
extendedPersistenceContext.insertWithoutTransaction(user1);

User user2 = new User(125L, "Devender", "admin");
extendedPersistenceContext.insertWithTransaction(user2);

User user1FromTransctionPersistenceContext = transctionPersistenceContext
  .find(user1.getId());
assertNotNull(user1FromTransctionPersistenceContext);

User user2FromTransctionPersistenceContext = transctionPersistenceContext
  .find(user2.getId());
assertNotNull(user2FromTransctionPersistenceContext);

6. Conclusion

In this tutorial, we gained a good understanding of the persistence context.

First, we looked at the transaction persistence context, which exists throughout the life of the transaction. Then, we looked at the extended persistence context, which can span across multiple transactions.