Show TOC

Entity ManagerLocate this document in the navigation structure

Use

Java EE 5 provides the Entity Manager API, which is the main API for application developers to interact with the database.

The “entity manager” (EM) interface provides a set of methods for managing the lifecycle and state of entities. It carries out all the operations necessary to synchronize the entities' state with the database. It supports CREATE, READ, UPDATE, and DELETE (CRUD) operations, query execution, and so on.

The Java Persistence API also supports a detach and merge mechanism. Entities are detached from the EM at the end of the persistence context or when they get serialized. Detached entities can be manipulated in persistence-unaware environments like plain Java objects. They can also be merged into a different persistence context by the entity manager.

The user interaction with the entity manager is provided by the Java interface javax.persistence.EntityManager .

The Persistence Context

The set of entity instances that are under the control of the EM is called “persistence context” . Only the entities within the persistence context are managed by the EM, that is, changes to them are eventually reflected in the database. Entities outside the persistence context are just regular Java objects without special characteristics.

The EM updates or consults the persistence context whenever a method of the EntityManager interface is called. For example, when you call the persist method, the entity that you pass as an argument is added to the persistence context (if it is not already present there). Similarly, when you call the find method, the EM checks if the requested entity is already present in the persistence context. If so, the entity found in the persistence context is returned. Otherwise, the EM reads the entity from the database and adds it to the persistence context.

Note

The persistence context contains at most one entity instance per primary key.

From the persistence context perspective, there are four possible states of an entity instance:

  • New - the entity instance does not have a persistent identity and is not yet associated with a persistence context.

  • Managed - the entity instance has a persistent identity and is associated with a persistence context.

  • Detached - the entity instance has a persistent identity and is not associated with a persistence context.

  • Removed - the entity instance has a persistent identity and is associated with a persistence context, but is scheduled for removal from the data store upon the end of the transaction.

Managed entities can become unmanaged again, either by means of an explicit entity manager call that clears the persistence context or automatically, when the persistence context is closed. Since you do not have direct access to the persistence context, the latter is driven by the container rather than the application.

JPA defines two types of persistence contexts that have different life cycles:

  • Transaction-scoped persistence context

    A transaction-scoped persistence context exists as long as the underlying transaction. The EM automatically creates a new persistence context upon the first operation performed within a transaction. Subsequently, the EM reuses the same persistence context for multiple operations within the same transaction. Finally, after the transaction has ended, the EM closes the persistence context (usually with commit). At the next transaction, the EM initiates a new empty persistence context.

    Transaction-scoped persistence contexts are appropriate for most cases and are frequently used within business applications.

    An entity within a transaction-scoped persistence context becomes detached after a transaction ends.

  • Extended persistence context

    An extended persistence context exists as long as the EM that uses it, and may therefore cover multiple transactions. If an entity is added to the persistence context, it remains managed until the EM is closed or until the persistence context is cleared explicitly. Any change applied to the entity, even outside of a transaction, eventually reflects in the database - the EM keeps track of such changes and uses a later transaction for the synchronization with the database.

    Extended persistence contexts are appropriate if you want the EM to control your entities beyond the end of a transaction.

Lifecycle of the Entity Manager

There are two types of EM instances:

  • Container-managed entity manager

    When using JPA in the context of a Java EE application, you obtain an EM instance via dependency injection using the @PersistenceContext annotation or via a JNDI lookup. In both cases, the EM is instantiated and closed by the underlying container automatically.

    Container-managed EM instances can be combined with transaction-scoped persistence contexts (typical configuration for Java EE applications) and with extended persistence contexts.

    This is how you obtain a container-managed entity manager instance in your application code:

                         @PersistenceContext
    public EntityManager em;
                      
  • Application-managed entity manager

    If you want to control the lifecycle of the EM, you create it using an EntityManagerFactory , and you must close it explicitly by calling the close method on the EM instance.

    Application-managed entity managers are suitable for particular use cases and particularly important for Java SE applications as the container-managed type is not available in the standard environment.

    Application-managed EM instances are always related with extended persistence contexts.

    This is how you create an application-managed entity manager instance via an EntityManagerFactory in your application code:

                         @PersistenceUnit
    EntityManagerFactory emf;
    EntityManager em = emf.CreateEntityManager();