1. Overview

Persistence context and persistence unit are two important concepts in JPA that we use to manage the lifecycle of entities in an application.

In this tutorial, we’ll take a look at a brief introduction to entity manager and entity manager factory. Next, we’ll see why persistence context is important and its use cases. Finally, we’ll see the role of the persistence unit and its use cases.

2. EntityManager and EntityManagerFactory

Before diving into the details, it’s essential to have a basic understanding of the EntityManager and EntityManagerFactory interfaces. As we’ll see, they have important roles in managing persistence, entities, and database interactions.

2.1. EntityManager

EntityManager is an interface that interacts with the persistence context. It performs CRUD operations on the entities, tracks changes, and ensures synchronization with databases upon transaction commitment. An EntityManager represents a persistence context and operates within the scope of a transaction.

2.2. EntityManagerFactory

EntityManagerFactory is an interface that creates an EntityManager, effectively functioning as a factory. Upon creation, an EntityManagerFactory is associated with a specific persistence unit, enabling the creation of instances of EntityManager.

3. PersistenceContext

The PersistenceContext is a short-lived, transaction-scoped context for managing the lifecycle of entities. It represents a set of managed entities stored in memory as a first-level cache of the entity manager. If a transaction begins, the persistence context is created and eventually is closed or cleared when the transaction commits or rolls back.

Persistence context automatically detects changes made to managed entities and ensures synchronization of all entity changes with the persistence storage.

We can define the type of the persistence context using the @PersistenceContext annotation:

@PersistenceContext
private EntityManager entityManager;

There are two types of persistence context in JPA: TRANSACTION and EXTENDED.

Let’s start by creating the entity corresponding to the PRODUCT table using the @Entity annotation:

@Entity
@Table(name = "PRODUCT")
public class Product {
    
    @Id
    private Long id;

    private String name;

    private double price;

    // standard constructor, getters, setters
}

Now, let’s create our service class PersistenceContextProductService:

@Service
public class PersistenceContextProductService {

    @PersistenceContext(type = PersistenceContextType.TRANSACTION)
    private EntityManager entityManagerTransactionType;

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

    @Transactional
    void insertProductWithTransactionTypePersistenceContext(Product product) {
        entityManagerTransactionType.persist(product);
    }

    Product findWithTransactionTypePersistenceContext(long id) {
        return entityManagerTransactionType.find(Product.class, id);
    }

    void insertProductWithExtendedTypePersistenceContext(Product product) {
        entityManagerExtendedType.persist(product);
    }

    Product findWithExtendedTypePersistenceContext(long id) {
        return entityManagerExtendedType.find(Product.class, id);
    }
}

3.1. Transaction Scoped PersistenceContext

The TRANSACTION PersistenceContext type is the default persistence context in JPA. In this type, the PersistenceContext is bound to the transaction. This means that each transaction creates and destroys the PersistenceContext.

Let’s persist the product with the TRANSACTION type persistence context. We’ll save the Product entity and the changes will automatically persist when the transaction is committed:

@Test
void whenProductPersistWithTransactionPersistenceContext_thenShouldPersist() {
    Product p = new Product(1L, "Product 1", 100.0);
    persistenceContextProductService.insertProductWithTransactionTypePersistenceContext(p);

    Product productFromTransactionScoped = persistenceContextProductService.findWithTransactionTypePersistenceContext(1L);
    Assertions.assertNotNull(productFromTransactionScoped);

    Product productFromExtendedScoped = persistenceContextProductService.findWithExtendedTypePersistenceContext(1L);
    Assertions.assertNotNull(productFromExtendedScoped);
}

3.2. Extended PersistenceContext

The EXTENDED PersistenceContext type extends the scope of the PersistenceContext beyond the transaction boundaries. We can create it via the @PersistenceContext annotation with the EXTENDED type.

Now, let’s persist the product with an EXTENDED type persistence context and without a transaction. The Product will be saved only in the persistence context:

@Test
void whenProductPersistWithExtendedPersistence_thenShouldPersist() {
    Product product = new Product(2L, "Product 1", 100.0);
    persistenceContextProductService.insertProductWithExtendedTypePersistenceContext(product);

    Product productFromExtendedScoped = persistenceContextProductService.findWithExtendedTypePersistenceContext(2L);
    Assertions.assertNotNull(productFromExtendedScoped);

    Product productFromTransactionScoped = persistenceContextProductService.findWithTransactionTypePersistenceContext(2L);
    Assertions.assertNull(productFromTransactionScoped);
}

The application commits the changes when removing the bean or deliberately closing the extended persistence context.

4. PersistenceUnit

The PersistenceUnit defines the set of entity classes along with their configuration, and it represents a logical grouping of these entities that the entity manager manages. We can create a persistence unit by creating a persistence.xml file or extending the PersistenceUnitInfo interface.

The @PersistenceUnit JPA annotation injects an entity manager factory into a bean:

@PersistenceUnit(name = "persistence-unit-name")
private EntityManagerFactory entityManagerFactory;

The persistence unit supports two types: RESOURCE_LOCAL and JTA.

A big advantage of the persistence unit is that we can define multiple persistence units within the same application, each adapted for different parts of the system or even separate databases.

4.1. Resource Local PersistenceUnit

By default, Spring applications use the resource local persistence unit. In a resource local PersistenceUnit, we are responsible for managing the transactions. It does not rely on an external transaction manager.

Let’s declare a persistence.xml file, located at META-INF/persistence.xml on the classpath:

<persistence-unit name="com.baeldung.contextvsunit.h2_persistence_unit" transaction-type="RESOURCE_LOCAL">
    <description>EntityManager serializable persistence unit</description>
    <class>com.baeldung.contextvsunit.entity.Product</class>
    <exclude-unlisted-classes>true</exclude-unlisted-classes>
    <properties>
        <property name="hibernate.hbm2ddl.auto" value="update"/>
        <property name="hibernate.show_sql" value="true"/>
        <property name="hibernate.generate_statistics" value="false"/>
        <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
        <property name="jakarta.persistence.jdbc.driver" value="org.h2.Driver"/>
        <property name="jakarta.persistence.jdbc.url" value="jdbc:h2:mem:db2;DB_CLOSE_DELAY=-1"/>
        <property name="jakarta.persistence.jdbc.user" value="sa"/>
        <property name="jakarta.persistence.jdbc.password" value=""/>
    </properties>
</persistence-unit>

As we can see, we define the persistence unit with database connection properties. Additionally, we configure Hibernate properties including the dialect, transaction settings, and other properties for persistence operations. Every time an application interacts with the database, it operates within the context of a persistence unit. We define mappings between Java entities and database tables within the persistence unit.

Now, let’s use this persistence unit in our PersistenceUnitProductService class:

@Service
public class PersistenceUnitProductService {

    @PersistenceUnit(name = "com.baeldung.contextvsunit.h2_persistence_unit")
    private EntityManagerFactory emf;

    @Transactional
    void insertProduct(Product product) {
        EntityManager entityManager = emf.createEntityManager();
        entityManager.persist(product);
    }

    Product find(long id) {
        EntityManager entityManager = emf.createEntityManager();
        return entityManager.find(Product.class, id);
    }
}

Let’s persist a Product entity to verify if everything is working as we expect:

@Test
void whenProductPersistWithEntityManagerFactory_thenShouldPersist() {
    Product p = new Product(1L, "Product 1", 100.0);
    persistenceUnitProductService.insertProduct(p);

    Product createdProduct = persistenceUnitProductService.find(1L);
    assertNotNull(createdProduct);
}

4.2. JTA PersistenceUnit

Using JTA means that we delegate the work to the container. Consequently, we cannot obtain an EntityManager through the EntityManagerFactory. Instead, we must use an EntityManager that the container supplies and injects via the @PersistenceContext annotation.

Enterprise applications commonly use JTA persistence units when deploying in Java EE containers such as TomEE and WildFly.

5. Conclusion

In this article, we learned the difference between the persistence unit and the persistence context.

We started with a brief introduction of EntityManager and EntityManagerFactory to understand their roles. Next, we examined the persistence context, delving into its scope and available types.

Finally, we turned our attention to the persistence unit, which acts as a central configuration unit for entities and facilitates efficient data management.

As always, the full implementation of these examples can be found over on GitHub.

Persistence

REST

Security

1. Overview

2. EntityManager and EntityManagerFactory