JPA EntityManager and Related Concepts Introduction

The JPA EntityManager is the key tool facilitating transactions between JPA annotated Java objects and the configured database (or data storage).

Persistence Unit

A persistence unit is a set of entity classes managed by an entity manager in an application. Typically, a persistence unit is associated with a single datastore.

Persistence units are defined in a persistence.xml file which must be located in the /META-INF directory within the .jar of applications using JPA.

Persistence Context

All transactions are performed within a context called a persistence context. If one wants to update an existing data record, this is not performed 'out of the blue'. The data is first fetched via the entity manager from the database (a context), updated and saved in the database. The persistence context is in between the database and the application. It is managed by the entity manager. It is not the database itself.

Entity Manager Factory

Every entity manager instance is created via an entity manager factory. In a web application (running in a container), a unique instance of an entity manager can be obtained with the persistence context annotation:

@PersistenceContext
EntityManager em;

In a standalone application, an entity manager factory instance can be retrieved from a bootstrapping class called Persistence. Then, entity manager instances can be created from it:

private static final EntityManagerFactory EMF
    = Persistence.createEntityManagerFactory("EMF name");
private static final EntityManager EM
    = EMF.createEntityManager(); Depending 

If implemented, the 2nd level cache may be retrieved from the factory. This is where entity instances are shared between entity managers created from it. A persistence unit utility can also be retrieved from the factory to retrieve ids of entities, or to check whether these are currently loaded. However, it is not common practice to use it directly.

Entity Lifecycle

This is a key concept in JPA. One cannot use the entity manager without understanding the life cycle of entities. Users create, delete, update entities in their applications. One has to handle the fact that such entities may or may not be known by the persistence context. If unknown, their id value (or persistent identity) are also unknown to the persistence context. This happens when the id value is generated automatically by the database for example.

Therefore, JPA defines a set of statuses for entities:

• New - A user creates an instance of a JPA annotated object, but has not saved/persisted it. It is unknown to the persistence context, like its persistent identity.
• Managed - A user creates an instance of a JPA annotated object and has saved it, or it has retrieved it from the database. In all cases, the entity is known by the persistence context.
• Detached - Any entity which used to be known by the persistence context, but which has been explicitly detached from it. Whatever happens to this entity is unknown to the persistence context, unless it is re-associated to it.
• Removed - An entity known by the persistence context, but which is to be removed from the database soon.

REM: the status of an entity is influenced by the success or not of transactions. For example, it can become detached if a transaction fails.

Entity Manager Uses

The main uses of the entity manager are:

• Finding Entities or a Reference to an Entity - Reads an entity from the database. Eventually, the read is delayed until the entity is used (lazy read).
  
• Persisting an Entity - Creates a record in the database for the entity. Fails if it already exists.
• Merging an Entity - Updates the record in the database for the entity. Creates it if it does not exist.
• Refreshing an Entity - Updates the content of the entity from data in the database. Erases any changes made in the application and not persisted.
• Remove an Entity - Deletes the record corresponding to the entity, in the database.
• Detaching an Entity - Modifications to the entity won't be handled by the persistence context anymore.
• Lock Entities - Helps avoiding concurrent modification issues.
• Flushing Entities - Synchronizing the persistence context with the database.
• Accessing the meta-model - To learn about known entities, embeddables and managed types.
• Creating Transactions - This allows grouped operations, with commit and rollback.
• Creating Queries - To create SQL like queries.
• Clear - Detaches all managed entities.

About Updates Made To Entities in the Application

• If an entity is detached or new, any modifications made to it will not be persisted in the database, ever.
• If an entity is managed, any modifications made to it will be persisted if it is persisted, merged or if flush is called on the entity manager.