JPA Architecture – Components and Relationships

1. JPA Architecture: The Components of

The diagram illustrates the main components of the Jakarta Persistence API (JPA) architecture and the relationships between them. It describes how persistence units are configured, how entity managers are created, and how persistence contexts are managed.

Component	Description
Persistence	The Persistence class provides static methods that allow an application to create an EntityManagerFactory for a particular persistence unit.
persistence.xml	The persistence.xml file is the standard XML configuration file used to define persistence units. It can specify the entity classes participating in each persistence unit, the persistence provider, database connection information, and mapping files.
Persistence Unit	A persistence unit is a logical group of entity classes and their persistence configuration. It defines which entities are managed and how the persistence provider should handle them. It is used to configure the EntityManagerFactory and defines the entity model used by the persistence contexts created from it.
EntityManagerFactory	An EntityManagerFactory is responsible for creating EntityManager instances. It can be created programmatically through the Persistence bootstrap class or provided by a Jakarta EE container. Its configuration is determined by the associated persistence unit. An EntityManagerFactory is generally an expensive object to create and is designed to be reused by the application. Consequently, it is normally created once and shared by multiple components or threads.
EntityManager	The EntityManager is the primary JPA interface through which an application interacts with the persistence layer. An EntityManager is created by an EntityManagerFactory and is associated with a persistence context.
Persistence Context	A persistence context is a set of managed entity instances associated with a particular persistence unit. Within a persistence context, each persistent entity identity corresponds to a unique managed entity instance. A persistence context tracks changes to managed entities and coordinates their synchronization with the database.

2. JPA Architecture: Associations and Multiplicities

2.1 persistence.xml - Persistence Unit

One persistence.xml file can define one or more persistence units. Each persistence unit is defined within one persistence configuration file.

2.2 Persistence - EntityManagerFactory

The Persistence class provides static factory methods that can be invoked multiple times to create EntityManagerFactory instances. Each invocation of createEntityManagerFactory() returns an entity manager factory associated with the specified persistence unit. (The one-to-many multiplicity in the diagram expresses the possibility of creating multiple factories through the same bootstrap mechanism.)

2.3 Persistence Unit - EntityManagerFactory

One persistence unit can be used to create multiple EntityManagerFactory instances. Each EntityManagerFactory is associated with one persistence unit.

2.4 Persistence Unit - Persistence Context

A persistence unit can serve multiple persistence contexts. Each persistence context uses the entity model defined by one persistence unit.

2.5 EntityManagerFactory - EntityManager

One EntityManagerFactory can create multiple EntityManager instances. Each entity manager is created by one factory.

2.5 EntityManager - Persistence Context

An entity manager interacts with its persistence context to perform persistence operations.

The multiplicity of the association between EntityManager and Persistence Context depends on the application environment and the type of persistence context being used.

2.5.1 Application-managed entity managers

In the typical application-managed scenario, the application explicitly creates an EntityManager using an EntityManagerFactory:

EntityManager em1 = emf.createEntityManager();
EntityManager em2 = emf.createEntityManager();

Each independently created application-managed EntityManager has its own persistence context. Therefore, the relationship is normally one-to-one: one EntityManager is associated with one persistence context and one persistence context belongs to one EntityManager. Creating another entity manager creates another persistence context.

2.5.2 Container-managed entity managers

In a Jakarta EE environment, the container manages entity managers and their persistence contexts.

When using transaction-scoped persistence contexts, multiple EntityManager references associated with the same persistence unit can share the same persistence context if they participate in the same JTA transaction.

For example, two application components can inject an EntityManager for the same persistence unit. If both components participate in the same transaction, their entity managers can share the same persistence context. In this case, multiple EntityManager references interact with one persistence context, which manages the entity instances for that transaction. Therefore, the relationship can be represented as many-to-one: multiple EntityManager references can share one persistence context.

However, this does not mean that all entity managers share the same persistence context. Sharing depends on the persistence unit and the transaction in which they participate.

3. Summary

The architecture can be understood through the following sequence:

1. The persistence.xml file defines one or more persistence units.
2. A persistence unit specifies the entity model and persistence configuration.
3. The Persistence bootstrap mechanism creates an EntityManagerFactory for a persistence unit.
4. The EntityManagerFactory creates one or more EntityManager instances.
5. Each EntityManager manages a persistence context, although container-managed transaction-scoped persistence contexts can be shared by multiple entity manager references.
6. The persistence context maintains the managed entity instances and coordinates their synchronization with the database.

The distinction between the EntityManagerFactory, the EntityManager, and the Persistence Context is fundamental to understanding JPA: the factory creates entity managers, entity managers manage persistence contexts, and persistence contexts maintain the managed entity instances.

---

Sources:

https://eclipse.dev/eclipselink/documentation/2.6/concepts/blocks002.htm