In this article we will review Entity Persistence Units and Persistence Contexts as well as looking at the Transaction Management with the Entity Transaction API for those who are looking to do the Component Developer Exam. We will first focus on the Persistence Units and the Persistence Contexts before we dive into the transaction management with the EntityTransaction API. Finally we will update our Tudo List application that we continued building in the previous article, Tutorial: Review of JPA Entity Operations for the Component Developer Exam.

The Issue of Managed and Unmanaged Entities

In the previous article, we looked at the entity lifecycle in relation to the callbacks that can be used by interceptors or listeners to provide pre or post-processing on the particular entity. This processing mostly is focused on crosscutting concerns such as logging, auditing and other such areas. But we will return to the entity lifecycle in order to provide the basis for our discussion of JPA Persistence Units and Persistence Contexts. The key to understanding the entity lifecycle is that the EntityManager will only start treating the POJO like an JPA entity when you tell it to do so. Before that, irrespective of the annotation, it doesnít know that the POJO annotated with JPA specific annotations is an entity. This contrasts with session beans and message driven beans which due to their annotations are immediately managed as such by the EJB container when the application starts. Another key is that the default behavior is for the EntityManager to manage any entity for as short a time as possible.

For an EntityManager, it will only concern itself with entities that are attached or managed. Once it stops managing the entity, the entity is considered detached. If the entity has never been managed, it is considered transient or new. The lifecycle of an entity with all of its different states and callbacks in shown in the diagram below:

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-entitylifecycle.jpg
Figure: The Lifecycle of an Entity

The EntityManager Interface

The EntityManager serves as the bridge between the OO and relational worlds. When the request is made to create a new domain entity, the EntityManager takes the entity and transforms it into a new database record. It then serves as the permanent bridge between the record and entity, ensuring that is will link any update to the entity to the relational data that it is mapped and update the record as well. Similarly a request to delete an entity will cause the EntityManager to find the mapped relational record and delete it as well. Vice versa, a search for an entity will prompt the EntityManager to create the Entity object, populates it with relational data, and ďreturnsĒ the Entity back to the application. This is the same process that takes place when any entity is saved to the database, the EntityManager will take the existing Entity and repopulate it with the updated data.

There is alot more to the EntityManager than just performing basic CRUD operations. The EntityManager is literally a bridge between the relational data and the entity. It will discretely and automatically keep all entities synched with the database as long as the entities are ďmanagedĒ by the EntityManager. We will discuss managed and detached entities in the next section so that you have a better understanding of what it means. Despite being a simple and intuitive interface, the EntityManager is by far the most important interface in JPA and is responsible for most of the ORM power in the Java Persistence API. Below is a table listing the most commonly used methods in the EntityManager interface.

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-entitymanagerinterfacemethods.jpg
Table: EntityManagerís Most Commonly Used Methods

You might notice that in comparison to the EJB3 Container, the EntityManager, which manages entities instead of the container, doesnít have the same range of services available from an EJB3 container. For example, container manages entities cannot directly use container services such as dependency injection, the ability to define method-level transaction and declarative security, remoteability, etc. This is not really an issue because in general, they are not used for persistence (Remember Remote and Home Interfaces for EJB2 Entity Beans!). The reality is that with JPA, there is little functionality of real value that is lost. In fact if you look at persistence frameworks such as Hibernate and TopLink from which JPA is based, JPA is basically a confirmation of the approach taken by these two frameworks.

Managed Entities

A managed entity means that the EntityManager ensure that the entityís data is synchronized with the database. The EntityManager does this through two means. First, when the EntityManager is requested to begin managing an entity, it synchronizes the entity with the database. Second, the EntityManager ensures that any changes to entity data from method invocations are reflected in the database at some point. It will continue doing this until the entity becomes detached. The EntityManager does this by holding an object reference to the managed entity and periodically checking that the entityís data is up to date. When the EntityManager finds that the entityís data has changed, it automatically synchronizes the changes with the database.

Entities become attached to the EntityManagerís context when either the entity is passed as an argument in the persist, merge, or refresh method or when an entity is retrieved using the find method or a query within a transaction. When an entity is first instantiated it is not considered to be attached. It is in the new or transient state as the EntityManager doesnít know of its existence yet. An example of this would be when you create a new Todo:

Java Code: Transient Todo Entity
Todo todo = new Todo();
It will only become managed once the EntityManagerís persist method creates a new record in the database for the entity. This is the common way to attach the Todo entity to the EntityManagerís context:

Java Code: Use of Persist to Transform Todo to a Managed Entity
Another example would be for an entity to become attached when it is retrieved from the database using the EntityManagerís find method or a query while within a transactional context. If there is no transactional context, the retrieved entity will be detached.

Finally to return a detached entity to an attached state, you can use the merge and refresh methods for entities that have been retrieved from the database and are in the detached state. The EntityManager will merge updates to the database with the data held in the entity, and refresh will repopulate the entity with data from the database.

Detached Entities

A detached entity means that an entity is no longer being managed by the EntityManager. When this happens there is no guarantee that the entityís state is synchronized with the database. Detachment happens most often when an entity passes across application tiers from the business tier to the web tier. At this point it may be changed by the user and then sent back to the business tier where the EntityManager can then use a merge operation on a detached entity for it to become attached again. There are a number of other ways that entities can become detached. Entities can become detached through serialization or cloning, when a method call involving the EntityManager has completed or when the EntityManagerís clear or remove method is called, but basically, the essential thing is that the entity is outside of the EntityManagerís context scope. An example of the use of the remove method is shown below:

Java Code: Use of remove to Transform Todo to a Detached Entity
Persistence Context

A set of managed entity object instances is called a persistence context. A persistence context is a key part of the internal functionality of an EntityManager. When we invoke methods of the EntityManager in order to do persistence operations, it is not the EntityManager that directly keeps track of the lifecycle of any individual entity. This task is delegated by the EntityManager to the currently available persistence context. So the persistence context is a self-contained collection of entities that are being managed by the EntityManager for a given period of time. This period of time that this set of entities are managed is known as the persistence scope. Here we use scope as it relates to persistence contexts in a manner similar to how it is used for Java variable scoping. It determines how long a particular persistence context is active. There are two types of persistence scopes:

Transaction-Scoped Persistence Context

A transaction-scoped EntityManager is when there is a transaction-scoped persistence context associated with an EntityManager. During a transaction, if there is a persistence context is under the transaction scope, all attached entities attached are automatically detached when the transaction ends. This is true for all persistence operations that can result in data changes since they are required to be done within a transaction scope. As long as the transaction continues, the persistence context will continue managing the entities. In this sense, transaction-scoped persistence contexts are comparable to method local variables in that they are only in effect within the boundaries of a transaction. Once the transaction has been committed or rolled back, the EntityManager will detach all entities presently attached after ensuring that all data changes have been synchronized with the database. This is shown in the figure below:

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-transactionscopedpersistencecontext.jpg
Figure: Transaction-Scoped Persistence Context

In the listing below, we shown the getTodo() is invoked within the EJB container within the context of a JTA transaction. The Todo and its associated TodoList (with itís associated User entity) are pulled by the EntityManager and the setDescription is used to update the description of the Todo. The Todo instance will be managed by the EntityManager while the transaction is running. When the transaction completes and commits, the changes to the Todo description will be synchronized to the database.

Java Code: Transparent Synchronization of Todo Entity
EntityManager entityManager;
// Assume this method invocation takes place within 
// the context of a running Transaction 
public Todo getNextTodos() {
   //  For brevity rather than create a query
   //  Assume the next todo has key of 25  in the DB
   Todo todo = entityManager.find(Todo.class, 25); 
   trey.setDescription("Pickup Daughter at new school today!"); 
   return todo;
Extended Persistence Context

Just because a transaction has completed doesnít mean that the EntityManager cease to exist. In fact, the EntityManager lifecycle will stretch well beyond numerous transactions. As such the life of the extended EntityManager spans across multiple transactions. Extended EntityManager are only to be used with stateful session beans and through the lifecycle of the session bean. In contrast to transaction-scoped persistence contexts, in extended persistence context, entities remain managed throughout the method-ready state of a stateful session bean with the EntityManage instance active. In this sense persistence contexts with extended scope are similar to instance variables that are active for the lifetime of an object, they remain as long as the EntityManager exists. This is demonstrated in the figure below, where throughout multiple transactions, the attached entities continue in this state unless at some point they are explicitly detached through a remove method to end the life of the stateful bean instance.

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-extendedpersistencescope.jpg
Figure: Extended Persistence Context across Several Transactions

Defining and Creating EntityManager Instances

An EntityManager not only manages a set of entities but also maps those entities to a particular database. This set of entities or classes is called a persistent unit. So as you can see the EntityManager is really key to performing any persistence operation. Therefore the first thing that you would need to do before doing any persistence operation is to obtain an instance of the EntityManager. The way that this is done is by injecting an instance via the container of an EntityManger by using the @PersistenceContext annotation or they can be created outside of a container by using the EntityManagerFactory. As we mentioned in our first article on persistence: Tutorial: In Depth Review of EJB3 Entity Beans (Entities) for the Component Developer Exam, the Java Persistence API can be used outside of an EJB3 container. So this sets the stage for two types of entity managers. There is container-managed EntityManagers and application-managed EntityManagers. for If you are using a container, this is more or less all you will need to know about getting an instance of an

Container-managed EntityManagers

When a EntityManager instance is injected using the @PersistenceContext annotation, then the EntityManager is container managed. The benefit of this approach is that the container handles the tasks related to looking up, opening and closing the EntityManager without you needing to do anything. The default for injected EntityManagers is transaction scope unless you specify otherwise. Below is an example of an EntityManager being injected via the @PersistenceContext annotation.

Java Code: Use of @PersistenceContext
EntityManager entityManager;
In most cases, it is not necessary to specify the persistence unit since most persistence providers will resolve the name of the persistence unit correctly. But if you want to avoid being tied to any particular vendor, it is recommended that you always specify the unitName. Below is the list of elements that you can set when using the @PersistenceContext annotation:
  • name - the JNDI name of the persistence context
  • unitName - the name of the persistence unit
  • type - specifies the EntityManager scope. As noted before there are two scopes: transaction and extended.
  • properties - vendor specific configuration properties.

Remember to never call close() on an injected entity manager as cleanup is handled by the application server. This will cause an IllegalStateException in your application. Also you can only use a extended EntityManagers with StatefulSessionBeans. Otherwise you will get issues with the persistence context not being closed properly and managed entities not being released. An example of the proper use of the type element for an extended persistence context is shown below:

Java Code: Definition of Extended Persistence Context
EntityManager entityManager;
One of the nice side benefits from using an extended scoped EntityManager is that it can be used to cache and maintain the application domain across any number of method calls from a client. Also you can do this while maintaining method-level transaction granularity. The nice thing about container-managed EntityManagers is that you can avoid dealing with alot of the minutiae that is done by the container compared when you are working with application-managed EntityManager.

Container-managed EntityManagers in a Web Container

When you are using an container-managed entity manager in a web container there are a number of things that you must be wary of due to the nature of the container managed entity managers. Web tier components are by their nature meant to be used by multiple concurrent threads. Servlet-based components like JSPs are expressly designed to be used by multiple concurrent threads in order to achieve high throughput through statelessness.

The problem is that the EntityManager is not thread-safe which means that your servlets and JSPs cannot use such a resource as servlet instance variables. The workaround for this problem is to use the SingleThreadModel interface in order to make a servlet thread-safe. Generally using a SingleThreadModel interface in an environment that uses multiple concurrent threads will have a severe impact on performance and is generally frowned upon. A number of container vendors have tried to develop different approaches in order to address this problem. But in the interest of portability I would not recommend the vendor specific approach.

Instead if you want to use a container-managed EntityManager from your servlet, you should look to do a lookup in order to obtain an instance of the EntityManager from within your method. The code to show how this can be done is shown below:

Java Code: Use of Container-managed EntityManager
@PersistenceContext(name="pu/tudoList", unitName="TudoList")
public class TodoServlet extends HttpServlet { 
private UserTransaction ut;
public void service (HttpServletRequest req, HttpServletResponse res) 
					throws ServletException, IOException {
      Context ctx = new InitialContext(); 
      EntityManager em =(EntityManager)
      ctx.lookup( "java:comp/env/pu/tudoList");
Later we will show how this problem can be addressed using an application-managed entityManager with JTA since the EntityManagerFactory is thread-safe.

Application-managed EntityManagers

JPA fully supports creating application-managed EntityManagers that you explicitly create, use, and release, including controlling how the EntityManager handles transactions. This capability is particularly important for using JPA outside the container. This doesnít preclude you from using an application-managed EntityManagers within a Java EE container in order to maintain fine-grained control over the EntityManager lifecycle as well as transaction management. It is with this in mind that the EJB 3 API provides a few features for using application-managed EntityManagers inside a container. Consider the TudoEAOImpl as a stateless bean using an application-managed EntityManager.

Java Code: Use of Application-managed EntityManager
public class TodoEAOImpl implements TodoEAO {
   private EntityManagerFactory entityManagerFactory; 
   private EntityManager entityManager;
   public TodoEAOImpl() {} 

   public void initialize() { 
      entityManager = entityManagerFactory.createEntityManager();

   public Todo updateTodo(Todo todo) {
      return todo;
   public void cleanup() {
         if (entityManager.isOpen()) { 
In this listing we are explicitly doing what the container was doing for us with a container-managed EntityManager. We inject an instance of EntityManagerFactory, and then we create an EntityManager with the injected entity manager factory after the bean is constructed using itís no-arg constructor. The EntityManager is then closed before the bean is destroyed. Note also that we join a container-managed JTA transaction before invoking the EntityManagerís merge method. This is because application-managed EntityManagers do not automatically participate in an enclosing transaction. Instead, they must need to be asked to join an enclosing JTA transaction by calling the joinTransaction method. This method is specifically geared to using application-managed EntityManagers running inside a container, where JTA transactions are normally available.In every sense this replicates what the container is doing automatically.

Using an EntityManagerFactory with an Application-managed EntityManager

In an application-managed EntityManager it is necessary to use a EntityManagerFactory interface in order to get an instance of an EntityManager. This is the equivalent of creating a Connection with a DriverManager factory when using JDBC. This can be seen in the figure below:

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-entitymanagerfactory.jpg
Figure: EntityManagerFactory and Application-Managed EntityManager

In a Java EE environment, we can easily obtain an EntityManagerFactory instance by using the @PersistenceUnit annotation. This was shown in the listing above for the TodoEAOImpl. The parameters of the @PersistenceUnit annotation are provided below:
name element - the JNDI name of the EntityManagerFactory
unitName element - used to specify the name of the underlying persistence unit.

In order to create an application-manage EntityManager, you call the createEntityManager method. This method along with the close method are the most commonly used in the interface. The table below list all the methods of the EntityManager Interface:

Tutorial: Review of the EntityManager Context for the Component Developer Exam-a7-entitymanagerfactorymethods.jpg
Table: EntityManagerFactory Methods

Running an Application-Managed EntityManager outside of the Java EE Container

When youíre running an application-managed EntityManager in a Java SE environments, you must use resource-local transactions in place of JTA because JTA is not a possible. It is specifically for this reason that the EntityTransaction interface was created. Letís redo the TodoEAOImpl code to use the EntityTransaction interface. This is shown below:

Java Code: Use of Application-managed EntityManager Outside of Container
EntityManagerFactory entityManagerFactory = 
EntityManager entityManager = entityManagerFactory.createEntityManager();


   EntityTransaction entityTransaction = entityManager.getTransaction();
Note that this listing has alot more boilerplate code for managing the transaction as well as managing resources than what would be the case with a container-managed EntityManager. First the Persistence objectís createEntityManagerFactory method is used to create an EntityManagerFactory as it was defined in the persistence.xml deployment descriptor. Without the container we need to remember to close the EntityManagerFactory and EntityManager that was created by the EntityManagerFactory when we are finished.

We also now need to create the transaction context for merging the Todo entity to the database, by creating the EntityTransaction by calling the getTransaction method from the EntityManager. This is because the EntityManager is creating the transaction rather than the container. It is because of this that we no longer use joinTransaction(). The EntityTransaction is basically a high-level abstraction over a resource- local JDBC transaction. The last part deals with handling the committing or rolling back of the transaction. After that it ensures the all resources are properly closed and released. All of this must be done because application-managed EntityManagers are never transaction scoped. They keep managing attached entities until they are closed. You also need to remember to set the transaction-type to RESOURCE_LOCAL in the persistence.xml file for using the EntityTransaction interface. Here is what the persistence.xml file will look like:

XML Code: Example of Persistence.xml file
 <?xml version="1.0" encoding="UTF-8"?> 
<persistence xmlns= 
<persistence-unit name="TudoListPU" transaction-type="RESOURCE_LOCAL">
   <property name="toplink.jdbc.driver"
    <property name="toplink.jdbc.url"
    <property name="toplink.jdbc.user" value="appUser"/> 
    <property name="toplink.jdbc.password" value="Tgu123gzx"/>
The first thing to remember is that because this is an application running in a Java SE environment, for transactions we use the transaction type, RESOURCE_LOCAL. Next the <class> element provides the full name of the Todo class which the persistence provider adds to its set of managed classes. This step is unnecessary in a container-managed environment since the container is capable of finding the managed classes by scanning the JAR file containing the persistence.xml.
The <properties> element is used to provide vender specific properties. In the EJB3 reference implementation, Toplink is used as the persistence provider. We have decided to use them as well for this example. Below is the list of properties shown for the persistence.xml file:
  • toplink.jdbc.driver - the name of the JDBC driver. As we are using MySql, it is this driver which is provided
  • toplink.jdbc.url - the JDBC connection URL to the database. We are using MySql database so this value is jdbc:mysql://localhost:3306/tudo_local.
  • toplink.jdbc.user and toplink.jdbc.password are the database user and password respectively.

Running an Application-Managed EntityManager in a Web Container

Some persistence providers recommend that when you are using an application-managed entity manager in a web container such as Tomcat or Jetty that you use the ThreadLocal pattern. This is a pattern is widely known by Hibernate users. It associates a single instance of the EntityManager with a particular request. You need to bind the EntityManager to a thread-local variable and then set the EntityManager instance to the associated thread. An example of this is shown below:

Java Code: Example of Application-managed EntityManager in Web Container
 private static EntityManagerFactory emFact; 
public static final ThreadLocal<EntityManager> _threadLocal = 
	new ThreadLocal<EntityManager>();

public static EntityManagerFactory getEntityManagerFactory() { 
   if (emf == null) {
         emf = Persistence.createEntityManagerFactory("tudoList");
      return emf;

public static EntityManager getEntityManager() { 
   EntityManager entityManager = _threadLocal.get();

   if (entityManager == null) { 
      entityManager = emf.createEntityManager();
   return entityManager;
If you need to use the ThreadLocal pattern, I recommend that you check with the persistence providerís documentation since it is bound to be slightly different than this listing.

The Importance of Persistent Units

In order to properly deploy a set of classes for handling all persistence within your application, you will need to define a persistence unit. A persistence unit simply maps your set of entities to a relational database. The EntityManager will map this set of classes to a relational database, but you will still need to package this persistence unit for use both within Javaís Enterprise Environment as well as itís Standard Environment. The normal way to define the persistence unit is within the persistence.xml file. You use this file to designate that the module contains one or more persistence units. An example of the structure of the JAR file that contains a persistence unit is shown below:

Java Code: Example of JAR file with persistence unit
orm.xml (optional) 
Looking at the structure, we have first, the persistence.xml file that was mentioned previously. This is the deployment descriptor for the a persistence module. Next you have the orm.xml file which defines the object-relational mapping in your application. You can also define additional mapping as we have shown here with the TudoExtORMap.xml file. In any case these are only needed if you go down the route of using XML Mapping. Next we provide all the entity classes that are required for the persistence to work correctly.

Details of the Persistence.xml File

The persistence.xml is the only required file out of all of those that was described in the previous section. This deployment descriptor provides the identities and configuration for each persistence unit contained within it. It is the descriptor that transforms the JAR module into a persistence module. Each persistence unit has a unique identity. This is required because it is used for obtaining an instance of the EntityManger among other things. It is a required deployment descriptor for the Java Persistence specification. It is normally packaged within a JAR file either within a web, enterprise or standard environment. Unfortunately, there are some of the EJB container providers that have added proprietary extensions to persistence modules without using persistence.xml in EJB-JAR modules. It is recommended that you avoid this if at all possible.

Each persistence unit is tied to only one data source. If you are deploying in a Java Standard environment, you must use vendor specific information to define and configure the data sources. If you are deploying in a Java EE environment, the definition and configuration of the datasources can be specified within the specific XML elements. Below is a template of a persistence.xml file.

XML Code: Template of persistence.xml file
 <?xml version="1.0" encoding="UTF-8"?> 
<persistence xmlns=""
    <persistence-unit name="NameOfPU"> 
           <!-- Standard and Provider-specific config may go here -->
           <property name="" value="someValue"/> 
Here is a description of the attributes in the file:
  • name attribute - is the name by which the persistence unit is referenced as well as being used in obtaining an EntityManager instance and. This name is either injected via annotations or specified in the XML deployment descriptor for use by the EntityManager. It is a required attribute.
  • transaction-type attribute - defines whether you use the JTA or resource local (RESOURCE_LOCAL) EntityTransaction API for managing and integrating the persistence unit with the EntityManager. The default is JTA in Java EE environments and RESOURCE_LOCAL in SE environments.
  • <description> element - used for describing the persistence unit.
  • <provider> element - is the fully qualified name of a class that implements the javax.persistence.PersistenceProvider interface. The persistence implementation is pluggable in both SE and EE environments. Your vendor will provide the implementation of this. It is not required and will use the default value.
  • <jtb-data-source> or <non-jta-data-source> element - Either one will specify the vendor specific identity of a data source. This is usually in the form of a global JNDI name for referencing the data source. It is not required and will default to the one provided by the vendor.
  • <properties> element - defines vendor specific attributes that are passed to the persistence provider. This is useful when configuring a data source in Java SE environments where there is no registry or JNDI service.

Class Sets in a Persistence Unit

The fixed set of classes that are part of a persistence unit will be based on the JAR file that has the persistence.xml file. The JAR file will be scanned for the root for any classes annotated with @Entity annotation. These classes will comprise the set of classes for the persistence unit to manage. It is also possible to specify other JARs to be scanned by using the <jar-file> element. Note that this element will be considered relative to the path of the JAR file that contains persistence.xml. An example of this is given below:

XML Code: Persistence file with reference to another entity jar file
   <persistence-unit name="nameOfMyPu">
Note that this solution cannot be used in a Java SE environment since there is no EJB3 Container. It will only work in Java EE environments. In the case of Java SE environments, you may need explicitly list the classes for the persistence unit as there is no way to reliably predict the JAR scan. An example of this is shown below:

XML Code: Example of persistence.xml with explicit class listing
   <persistence-unit name="TudoListPu">
      <class>com.acme.tudo.persistence.TodoList</class> ...
You can also specify elements that you donít want to be scanned. This is done by using the <exclude-unlisted-classes> element. The final set of classes is determined by a combination of all of the following metadata:
  • Classes annotated with @Entity in persistence.xml JAR files (except those specified as <exclude-unlisted-classes>
  • Classes annotated with @Entity contained within any JARs listed with any <jar-file> elements
  • Classes mapped in the META-INF/orm.xml file (when existing)
  • Classes mapped in any XML file being referenced via the <mapping-file> element.
  • Classes listed with any <class> elements

In most cases, a number of these elements such as <class>,<mapping-file> or <jar-file> donít need to be used unless you reusing the same class within two or more persistence units.

Thatís it for the our review of Entity Persistence Units and Persistence Contexts. Next we will look at the Java Persistence Query Language.