Entity manager

The EntityManager interface is an API that manages the life cycle of an entity instance.

Entities cannot persist themselves on the relational database; annotations are used only to declare a POJO as an entity or to define its mapping and relationships with the corresponding tables on the relational database.

In JPA, the EntityManager interface is used to allow applications to manage and search for entities in the relational database.

The EntityManager is an API that manages the life cycle of entity instances. An EntityManager object manages a set of entities defined by a persistence unit. Each EntityManager instance is associated with a persistence context. A persistence context defines the scope under which particular entity instances are created, persisted, and removed through the APIs made available by EntityManager. In some ways, a persistence context is conceptually similar to a transaction context.

The entity manager tracks all entity objects within a persistence context for changes and updates made, and flushes these changes to the database. Once a persistence context is closed, all managed entity object instances become detached from the persistence context and its associated entity manager, and are no longer managed. Once an object is detached from a persistence context, it can no longer be managed by an entity manager, and any state changes to this object instance will not be synchronized with the database.

Managed and unmanaged entities

An entity object instance is either managed (attached) by an entity manager or unmanaged (detached).

When an entity is attached to an entity manager, the manager monitors any changes to the entity and synchronizes them with the database whenever the entity manager decides to flush its state.

When an entity is detached, and therefore is no more associated with a persistence context, it is unmanaged, and its state changes are not tracked by the entity manager.

Entity manager operations

The main operations that can be performed by an entity manager:
Table 1. Entity manager operations
Operation Description
persist
  • Insert a new entity instance into the database.
  • Save the persistent state of the entity and any owned relationship references.
  • The entity instance becomes managed.
find Obtain a managed entity instance with a given persistent identity (primary key), return null if not found.
remove Delete a managed entity with the given persistent identity from the database.
merge State of a detached entity gets merged into a managed copy of the detached entity. The managed entity that is returned has a different Java™ identity than the detached entity.
refresh Reload the entity state from the database.
lock Set the lock mode for an entity object contained in the persistence context.
flush Force synchronization with database.
contains Determine if an entity is contained by the current persistence context.
createQuery Create a query instance using dynamic Java Persistent Query Language.
createNamedQuery Create an instance of a predefined query
createNativeQuery Create an instance of an SQL query.

Container-managed entity manager

One way to use an entity manager in a Java EE environment is with a container-managed entity manager. In this mode, the container is responsible for the opening and closing of the entity manager and thus, the life cycle of the persistence context (in a way that is transparent to the application). A container-managed entity manager is also responsible for transaction boundaries.

A container-managed entity manager is obtained in an application through dependency injection or through JNDI lookup, and the container manages interaction with the entity manager factory transparently to the application.

A container-managed entity manger requires the use of a JTA transaction, because its persistence context will automatically be propagated with the current JTA transaction, and the entity manager references that are mapped to the same persistence unit will provide access to this same persistence context within the JTA transaction. This propagation of persistence context by the Java EE container means that the application does not have to pass references to the entity manager instances from one component to another.

Container-managed persistence contexts may be defined to have one of two different scopes:
  • Transaction persistence scope
  • Extended persistence scope

Application-managed entity manager

Using an application-managed entity manager allows you to control the entity manager in application code.

When using such an application-managed entity manager, note the following things:
  • With application-managed entity managers the persistence context is not propagated to application components, and the life cycle of entity manager instances is managed by the application. This means that the persistence context is not propagated with the JTA transaction across entity manager instances in a particular persistence unit.
  • The entity manager, and its associated persistence context, is created and destroyed explicitly by the application.
This type of entity manager is usually used in two different scenarios:
  • In Java SE environments, where you want to access a persistence context that is stand-alone, and not propagated along with the JTA transaction across the entity manager references for the given persistence unit.
  • Inside a Java EE container, when you want to gain very fine-grained control over the entity manager life cycle.

Feedback