Entity manager

The EntityManager interface is an API that manages the lifecycle 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 lifecycle of entity instances. An EntityManager object manages a set of entities that are 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 that are 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 instances become unmanaged and detached when a transaction scope or extended persistence context ends. An important consequence of this fact is that detached entities can be serialized and sent across the network to a remote client. The client can make changes remotely to these serialized object instances and send them back to the server to be merged back and synchronized with the database.

Note: This behavior is different from the EJB 2.1 entity model, where entities are always managed by the container. Because in EJB 3.0 you are working with entities that are POJOs, this can simplify how you design Java™ EE applications, because you are not forced to use patterns, such as data transfer objects (DTO), between the business logic layer (session beans) and the persistence layer.

Entity manager operations

The main operations that can be performed by an entity manager:

Table 1. Entity manager operations. The table describes 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 that is 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 lifecycle 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 manager requires the use of a JTA transaction, because its persistence context is automatically propagated with the current JTA transaction, and the entity manager references that are mapped to the same persistence unit provides 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 might 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 lifecycle 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 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 lifecycle.