JPA- Java Persistence API : API

by Anuj Verma · Published 20/01/2015 · Updated 08/01/2018

Entity Manager API
Life Cycle of Entity
Entity Listeners and Callbacks
Packaging a persistence unit
Obtaining an Entity Manager

The EntityManager API is most important part of the Java Persistent API (JPA).
It is an interface specifically used to access entities in the application’s persistent context.
All the entities available in the persistent context must be unique and can be identified by the primary key associated with the entities.
EntityManager API manage the life cycle of entities.
The EntityManager API is the connecting bridge between object oriented data and relational database.
EntityManger deletes the entity from the persistent context, when the request is to delete the entity.
when the request is to update the entity, then the EntityManger looks at the relational database which corrsponds to the entity and updates it.
Similarly, when request is to save an entity in the persistent context, then the EntityManager creates an entity object and maps this object to the relational database and returns the entity object back to the object oriented world.

Entity Manager

EntityManager interface is divided in two different interfaces, known as the container-managed and the application-managed.
Container-managed Entity Manager :- in this, The container runtime provides the EntityManager for an application. The container injects the EntityManager with the @PersistentContext annotation. Otherwise, the lookup() method is used to obtain the EntityManager from the PersitentContext.
Application-managed Entity Manager :- In this, the application itself is responsible to creating the EntityManager for itself.

The Life Cycle of an entity is managed by the EntityManger API. It provides the method for entity like, new(), remove(), find(), persist() etc.

The Entity life cycle consists of four different stages:

New : At this stage , a new entity instance is created that is not associated with any persistent identity or persistent context.
Managed : At this stage , the entity has persistent identity in the database and is associated with persistent context. An entity is said to be in the managed state after the persist() method is called. Changes to the entity are synchronized in the database after the transaction is committed or the flush() method is called.
Detached : At this stage , the entity has its persistent identity but is no longer associated with any persistent context.
Removed : At this stage , the entity is currently associated with the persistent context but it is ready to be removed from the database.

Entity Listeners and Callbacks

It is often useful fro the application to react to certain events which occur inside the persistence mechanism. This allows the implementation of certain kinds of generic functionality, and extension of built-in functionality.

EJB 3 Specification provides two related mechanism

The First mechanism is that the method of the entity may be designed as the callback method to receive the notification of the particular entity life-cycle events. The Callback methods are annotated using callback annotations.
The Second mechanism is to define the entity listener class to be used instead of the callback methods defined directly inside the entity class.

Entity Listeners

An Entity Listener is a stateless class with no argument constructor. An Entity listener is defined by annotating the entity class with @EntityListeners annotations. We can define several entity listeners per entity within different levels of hierarchy but can’t define two listeners for the same event in the same entity.

Can be defined by three ways:

@EntityListeners : The listener specifies the callback listener classes that are to be used for an entity.
@ExcludeSuperclassListeners : This listener specifies the invocation of the super calss listeners, that is to be executed for the entity. Here the listener will also be executed for the sub class.
@ExcludeDefaultListeners : This listener specifies the invocation of the default listeners which is to be executed for the entity class. The listener is to be excluded for both the super class and the subclass.

Callbacks

Callbacks are generally the methdos of entities used to receive notification about a specific entity.

The JPA specification defines the following life-cycle events for an entity:

PrePersist : This is represented by the @PrePersist annotation. It is synchronous with the persist operation and executed before entity manger persist operation is actually executed.
PostPersist: This is represented by the @PostPersist annotation. It is executed after the database persist operation is executed. It is called after the insert operation.
PreRemove : This is represented by the @PreRemove annotation. It is synchronous with the database remove operation and executed before entity manger remove method is actually executed.
PostRemove : This is represented by the @PostRemove annotation. It is executed after entity manger remove operation is actually executed. It is synchronous with the remove operation.
PreUpdate : This is represented by the @PreUpdate annotation. It is executed before the database update operation.
PostUpdate : This is represented by the @PostUpdate annotation. It is executed after the database update operation.
PostLoad : This is represented by the @PostLoad annotation. It is executed after an entity is loaded into the persistent context or the entity is being refreshed.

Packaging a persistence unit

The J2EE application consists of one or more entities. These entities are packaged in a persistence unit. In Simpler words, the entities are not limited to the EJB modules, rather, they are packaged in a web module, EAR module, or the standard jar file.

These entities are packaged in a descriptor called persistence.xml.

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">

<persistence-unit name="persist123" transaction-type="JTA">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>jta4anujcust</jta-data-source>
<mapping-file></mapping-file>
<jar-file></jar-file>
<class>javaskool.Customer</class>
</persistence-unit>
</persistence>

Obtaining an Entity Manager

The Entity Manager in EJB 3.0 acts as a path for the client to acquire the entity manager services offered by EJB3.0 persistence framework. The Client sessions must have an entity manger instance for interacting with the entities. It helps in Querying, updating, removing, and refreshing the entity instances.
Entity Manager maintains a collection of the instances within the transaction context called persistence context.
The client can access or update the entity data as they would be the Plain Old Java Objects.
The EntityManager can be obtained from both within the EJB Container or outside it.
The Client can obtain an Entity Manager instance by using the Container Injection or by using the EntityManagerFactory or by looking up the EntityManger thru JNDI.

Obtaining an Entity Manager thru Session Bean Using the Container Injection

The session bean uses the container injection to obtain an EntityManager instance which is bound to a persistent unit.

@Stateless
Public class Customer
{

	@PersitenceContext("persistence")
	Private EntityManager em;

	Public void createCustomer()
	{
		final Customer cust=new Customer();
		cust.setName("abc");
		em.persist(cust);
	}
}

Obtaining an Entity Manager Using EntityManagerFactory

Sometimes the application desires more control over the life cycle of the Entity Manager. Then the client has a better option for obtaining the instance of an entity manger by an EntityManagerFactory. The javax.persistence.Persistence class acts as a factory to acquire the EntityManagerFactory.

public static void main(String a[])
{
	final EntityManagerFactory emf=Persistence.createEntityManagerFactory("persistence");
	final EntityManger em=emf.createEntityManager();
	final Customer cust=new Customer();
	cust.setName("abc");
	em.persist(cust);
}

Obtaining an Entity Manager by looking up using JNDI

The EntityManagerFactory or the EntityManger, lookup with the help of the java Naming Directory Interface (JNDI).

EntityManger em=(EntityManager)ctx.lookup("xyz");

Different way to create EntityManager Object

There are important differences between the injected EntityManager, and the EntityManager created from an injected EntityManagerFactory. Basically, injected EntityManager is container-managed, meaning all of its lifecycle is controlled by the container (web container or EJB container). Application code cannot close it, or otherwise interfere with its life.
In addition, for a container-managed EntityManager, its associated PersistenceContext is automatically propagated along with the underlying JTA, from servlet A to servlet B, from servlet to EJB, from EJB a to EJB B, and so on. As such, EntityManager of the same configuration injected into various classes can share the same PersistenceContext in a call stack.
On the other hand, EntityManager created from EntityManagerFactory is application-managed EntityManager. Application code is responsible for managing its whole lifecycle. And there is no PersistenceContext propagation for application-managed EntityManager.
Are all EntityManager’s obtained from EntityManagerFactory application-managed EntityManager? Yes.
Is it possible to get a container-managed EntityManager from EntityManagerFactory? No.
You may have read about the method EntityManagerFactory.getEntityManager(), which returns a container-managed EntityManager. This method was considered and included in the early draft version of Java Persistence API, but was eventually removed from its final release.