Introduction

Struts 2.0 is the popular Open Source Presentation Tier framework developed by Apache Group. It is based on MVC Model 2 design pattern. Dispatcher Filter is the front controller for the struts2 based applications. Struts 2.0 has simplified web development for its users by introducing POJO based actions, interceptors, flexible validation and support for many different result types.

Struts can be used to build the user interface tier of the enterprise application. Whereas, any of the popular ORMs like Hibernate, JPA, iBatis can be used for the persistence tier of the application. Struts2 provides easy integration with these persistence tier frameworks.

This article demonstrates the integration of Struts 2.0 applications with the Java Persistence API (JPA). The concept is explained with the help of a sample application. Knowledge of JPA and Struts 2.0 is the prerequisite for this article.

Development Environment

• NetBeans IDE 6.8
• GlassFish V2.x
• Apache Derby Database

Project Structure

The sample application developed in this article is “StrutsJPADemo” where an employee details are persisted to the database with the help of JPA.

Libraries/Jar Files Required

• Struts 2.0 jar files
• JPA jar files
• Jar file for the database driver (derbyclient.jar, in our case) The
  complete application structure is shown below:
• 
• The User Interface (JSP pages) is created in the “Web Pages” directory. The java classes (Actions, Entities, Service classes, Resource Bundles, struts.xml) are created in the “Source Packages” directory. The required jar files are present in the “Libraries” directory. The web application deployment descriptor “web.xml” is created by the IDE in the “WEB-INF” subdirectory of “Web Pages”. This sample application stores the employee details into the Derby database.

Environment Set Up

Once the web application is created and all the required libraries are added to the classpath, we can start working on the different components of the application.

Before we start working on the different application components like JSP pages and Java classes, we must first configure the following resources in the application server:

1. javax.transaction.UserTransaction
   1. In our application, we have created a UserTransaction and bound the same in JNDI with the name “UserTransaction”. The snapshot given below shows the same.
   2. 

2. Connection Pool & DSN
   1. For the database, we have created a connection pool in the application server to connect to ScrambleDatabase in the local machine running at port number 1527. The connection pool is bound to the name
      “scramblePool” as shown in the snapshot below.

   

   1. The next step is to configure the DSN in the application server. Our DSN is bound to the name “jdbc/scramdleDSN” in JNDI. This is shown below in the snapshot. This DSN will use “scramblePool”created in the previous step.

   

I have been developing Java applications for a long time and the major difficulty was the coding part related to database manipulations. Recently I shifted to use Object-Relational Mapping through JPA. I have used TopLink, EclipseLink, and Hibernate. Although I could achieve the functionally I want with ease, the output was slower when compared to normal method of database connection with JDBC. Then I used some Object databases like neoDatis. They were quite faster, yet I was reluctant to proceed as most of them had their own standards and did not comply to JPA. Finally I found the ObjectDB, an Object database for Java which completely supports JPA.

This article demonstrates how to create a simple JAVA Standard application in NetBeans using ObjectDB and JPA. The demonstrated application uses JPA to store and retrieve objects of two entity classes from an Embedded ObjectDB. It will demonstrate the capabilities of ObjectDB and JPA, which include persisting objects, removing saved objects and retrieving persisted objects. For this tutorial, besides the Java JDK and the NetBeans IDE,you only need to download
and extract the ObjectDB distribution zip file.The distribution zip contains everything necessary without any external dependency.

This tutorial consists of the following steps

• Step 1: Create an ObjectDB Enabled Java SE Project
• Step 2: Define a JPA Entity Classes
• Step 3: Add a Main Class
• Step 4: Design a Graphical User Interface
• Step 5: Code user-defined Methods
• Step 6: Code Events of Controls
• Step 7: Run the program

Step 1: Create an ObjectDB Enabled Project

We start by creating a new NetBeans Project.

From the menu, select File > New to get the [New Project] dialog box

Select Java from Categories and
Java Application from Projects and click Next

Choose a Project Name (e.g City

Set the name of the Main class to main.Main – This will create a package named main and a Java Class named Main with the public static void main(String[] args){}

Click Finish to create the project.

Then ObjectDB/JPA support has to be added to the project

Download the ObjectDB installation files from the download page. The downloaded file, objectdb-(version).zip file has to be extracted to a folder like D:\Program Files\ObjectDB.

Find the project in Project window.If project window is not visible, press ctrl + 1 to get the project window. Right click on the project to get the popup menu and select the Properties to get the [Project Properties] window.

Click on Libraries under categories of the Project Properties Window. No libraries are listed at the moment under Compile tab.

Click on Add Jar/Folderand locate the objectdb.jar file inside the bin folder of ObjectDB extracted directory.

This will add the objectdb.jar file to the libraries and now the project is JPA/ObjectDB enabled.

also read:

• Introduction to Java Server Faces
• Request Processing Lifecycle phases in JSF
• Accessing Web Services from JSF applications
• Navigation model in JSF

Problem Statement

In this article, a scenario of generating report on employee details is considered and has been explained with the corresponding code. The module will display the details of the particular employee chosen from a drop down list box. The application starts with a home page (Home.jsp) which has a hyperlink to the report page (EmloyeeHome.jsp). The EmployeeHome.jsp has a drop down with the employee numbers populated dynamically from the database through JPA. Upon selecting a particular employee number the details of the employee will be displayed in the same page.

Raising the application

Step1:

• Create a dynamic web application in a workspace in Eclipse
• For using JPA, add the required project facet.
• Right click on the project and select properties -> Project Facets. Select
  the checkbox for Java Persistence and click on the “further configuration
  available…”
• By clicking the link “further configuration available…” “JPA Facet”
  window will be displayed. Click on “OK” button and come to “Project
  Facet window”. Click on “OK” button in “Project Facet” window. This
  will complete the configuration required in Eclipse IDE

Step2:

• The classes12.jar, hibernate-entitymanager.jar, javaee.jar, jboss-faces.jar,
  jsf-api.jar, jsf-impl.jar, standard.jar, jstl.jar, toplink-essentials.jar,
  toplink-essentials-agen.jar archive files should be added on to the project
  to enable JPA and JSF framework in the application. Copy these jar files
  into the lib folder (Project -> WebContent -> WEB-INF -> lib)

Step3:

• Create a Home.jsp with a hyperlink to EmployeeHome.jsp
• Sample code (Home.jsp)

<%@ page language="java" contentType="text/html;
charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<%@ taglib prefix="f" uri="http://java.sun.com/jsf/core"%>
<%@ taglib prefix="h" uri="http://java.sun.com/jsf/html"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Home page</title>
</head>
  <body>
	<f:view>
		<h3>
		<center>
		<h:outputLabel>Welcome to the Home Page</h:outputLabel>
		</center>
		<h:outputLink value="EmployeeHome.jsp">Employee Details</h:outputLink>
        	</h3>
	</f:view>
</body>
</html>

Sample Screen Shot

Step4:

1. When the Employee Details hyperlink is clicked, Employee Home page is displayed.
2. Create EmployeeHome.jsp
3. Sample Code (EmployeeHome.jsp)

<%@ page language="java"
contentType="text/html; charset=ISO-8859-1"
	pageEncoding="ISO-8859-1"%>
<%@ taglib prefix="f" uri="http://java.sun.com/jsf/core"%>
<%@ taglib prefix="h" uri="http://java.sun.com/jsf/html"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Employee Details</title>
</head>
<body>
	<f:view>
	<h3>
        	<center>Welcome to Employee Home Page</center>
	</h3>
	<br><br>
	<h:form>
	<h3>
		Select an Employee Number from the drop down:
	</h3>
	<br><br>
	<h:selectOneMenu id="selEmpNo"
		alueChangeListener="#{employee.employeeReport}"
		onchange="submit()">
		<f:selectItem itemLabel="select" />
	<f:selectItems value="#{employee.empNoList}" id="emp"/>
	</h:selectOneMenu>
	</h:form>
	<br><br>
	<h3>
	<h:outputText value="Employee Name: "></h:outputText>
	<h:outputText value="#{employee.empName}"/>
	<br><br>
	<h:outputText value="Employee Number: "/>
	<h:outputText value="#{employee.empNo}"/>
	<br><br>
	<h:outputText value="Name of the IBU: "/>
	<h:outputText value="#{employee.ibu}"/>
	<br><br>
	<h:outputText value="Designation: "/>
	<h:outputText value="#{employee.designation}"/>
</h3>
</f:view>
</body>
</html>

1. Sample Screen shot

Note: In EmployeeHome.jsp, <f:selectItems> is used to dynamically populate the
drop down with employee number from the corresponding managed bean. When a particular employee number is selected from the drop down, the corresponding employee details should be displayed. In order to implement this functionality,
implement ValueChangeEventListener in the corresponding managed bean and bound the UI component to it. The employeeReport(ValueChangeEvent event) of the EmployeeBean managed bean is the value change even listener in this
implementation. . Since value change event will not submit the request, some mechanism (E.g., JavaScript function) is required to submit the request after selecting the employee number from the drop down. (In EmployeeHome.jsp,
“submit() is assigned to “onChange” attribute of <h:selectOneMenu> tag. Hence no need to write any explicit java script function to submit the form.)

Step5:

• Create a package “employee” under the project
• Create a bean EmployeeBean which is a managed bean (the configuration of the managed bean is available in faces-congig.xml file which is given latter). The attributes of this bean is bound to various UI Components used in EmployeeHome.jsp
• Sample Code (EmployeeBean.java)

package employee;

	import java.util.ArrayList;
	import java.util.Iterator;
	import java.util.List;
	import javax.faces.event.ValueChangeEvent;
	import javax.faces.model.SelectItem;

	public class EmployeeBean {
		private String empName;
		private String ibu;
		private String designation;
		private int empNo;

		//This is used to dynamically populate the drop down with employee numbers
		List<SelectItem>empNoList;

		public EmployeeBean(){
			this.empNoList = new ArrayList<SelectItem>();
			/*Populating Employee Number in the drop down - Dynamic */
			List<EmployeeEntity>empList = new
				EmployeeService().getEmployeeList();
			Iterator<EmployeeEntity>iterator = empList.iterator();
			while(iterator.hasNext()){
				EmployeeEntity employee = iterator.next();
				SelectItem item = new SelectItem(employee.getEmpNo());
				empNoList.add(item);
			}
		}
		public String getEmpName() {
			return empName;
		}
		public void setEmpName(String empName) {
			this.empName = empName;
		}
		public String getIbu() {
			return ibu;
		}
		public void setIbu(String ibu) {
			this.ibu = ibu;
		}
		public String getDesignation() {
			return designation;
		}
		public void setDesignation(String designation) {
			this.designation = designation;
		}
		public int getEmpNo() {
			return empNo;
		}
		public void setEmpNo(int empNo) {
			this.empNo = empNo;
		}
		public List<SelectItem> getEmpNoList() {
			return empNoList;
		}
		public void setEmpNoList(List<SelectItem> empNoList) {
			this.empNoList = empNoList;
		}
		public List<EmployeeEntity> getEmpList() {
			return empList;
		}
		public void setEmpList(List<EmployeeEntity> empList) {
			this.empList = empList;
		}
		/*Eventlistener - for fetching an employee record based on the selection of employee
			number from the drop down*/
		public void employeeReport(ValueChangeEvent event){
			int empNo = Integer.parseInt((String)event.getNewValue());
			EmployeeEntity employee = new
				EmployeeService().getEmployee(empNo);
			this.empNo = employee.getEmpNo();
			this.empName = employee.getEmpName();
			this.ibu = employee.getIbu();
			this.designation = employee.getDesignation();
		}
	}

Note: After selecting the employee number from the drop down, to fetch the data from the table, a service class called “EmployeeService” (code is given later) is used which makes use of JPA to fetch the required record from the
table.

Step6:

1. Inside the package “employee”, create an entity class called “EmployeeEntity.java” which is mapped to an “employee” table
2. Sample Code (EmployeeEntity.java)

package employe;
	import javax.persistence.Entity;
	import javax.persistence.Id;
	import javax.persistence.Table;

	@Entity
	@Table(name="employee")
	public class EmployeeEntity {
		@Id
		private int empNo;
		private String empName;
		private String ibu;
		private String designation;
		public int getEmpNo() {
			return empNo;
		}
		public void setEmpNo(int empNo) {
			this.empNo = empNo;
		}
		public String getEmpName() {
			return empName;
		}
		public void setEmpName(String empName) {
			this.empName = empName;
		}
		public String getIbu() {
			return ibu;
		}
		public void setIbu(String ibu) {
			this.ibu = ibu;
		}
		public String getDesignation() {
			return designation;
		}
		public void setDesignation(String designation) {
			this.designation = designation;
		}
	}

Step7:

1. Inside the package “employee”, create a class called “EmployeeService.java”. This class will interact with the database to fetch the required details
2. Sample Code (EmployeeService.java)

package employee;
	import java.util.ArrayList;
	import java.util.List;
	import javax.persistence.EntityManager;
	import javax.persistence.EntityManagerFactory;
	import javax.persistence.EntityTransaction;
	import javax.persistence.Persistence;
	import javax.persistence.Query;

	public class EmployeeService {
		public List<EmployeeEntity> getEmployeeList(){
			List<EmployeeEntity> empList = new ArrayList<EmployeeEntity>();
			EntityManager em = null;
			try{
				EntityManagerFactory emf =
						Persistence.createEntityManagerFactory("Employee-
						Details");
				em = emf.createEntityManager();
				EntityTransaction et = em.getTransaction();
				et.begin();
				Query query = em.createQuery("select e from EmployeeEntitye");
				empList = query.getResultList();
			}
			catch(Exception e){
				//log the exception
			}
			return empList;
		}
		public EmployeeEntity getEmployee(int empNo){
			EmployeeEntity employee = new EmployeeEntity();
			EntityManager em = null;
			try{
				EntityManagerFactory emf =
					Persistence.createEntityManagerFactory("Employee-
					Details");
				em = emf.createEntityManager();
				EntityTransaction et = em.getTransaction();
				employee = em.find(myPackage.EmployeeEntity.class, empNo);
			}
			catch(Exception e){
				//log the exception
			}
			finally{
				if( em != null){
					em.clear();
				}
			}
			return employee;
		}
	}

Step8:

1. Create “persistence.xml” file and keep it inside META-INF folder
2. Sample Code (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="Employee-Details">
			<provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provider>
			<class>.EmployeeEntity</class>
			<properties>
				<property name="toplink.jdbc.url" value="
					jdbc:oracle:thin:@localhost:1521:nr"/>
				<property name="toplink.jdbc.user" value="scott"/>
				<property name="toplink.jdbc.driver"
					value="oracle.jdbc.driver.OracleDriver"/>
				<property name="toplink.jdbc.password" value="tiger"/>
				<property name="toplink.ddl-generation" value="update-tables"/>
			</properties>
		</persistence-unit>
</persistence>

Note: Persistence.xml file is configured for Oracle database. You have to
configure according to the database which you want to use and give the
values accordingly.

Step9:

1. Create “faces-congig.xml” file which contains information about
   navigation rule and managed bean. Place the file inside WEB-INF
   folder
2. Sample Code (faces-config.xml)

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

http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"

			version="1.2">
		<navigation-rule>
			<from-view-id>/Home.jsp</from-view-id>
		</navigation-rule>
		<managed-bean>
			<managed-bean-name>employee</managed-bean-name>
			<managed-bean-class>employee.EmployeeBean
			</managed-bean-class>
			<managed-bean-scope>request</managed-bean-scope>
		</managed-bean>
	</faces-config>

Conclusion

This article demonstrates how to integrate JSF and JPA while developing a web application. Apart from this, the article also illustrates how to use drop down (dynamic) in a JSF enabled JSP and how to make use of value change event listener.

Acknowledgement

I would like to thank my manager Mr. Rajagopalan P, Principal, Education and Research Department, Infosys for the guidance and continuous support. I would like to thank Mr. Satheesha B N, Associate Vice-President, Education
and Research Department, Infosys for motivating me to write this article. I would like to thank Mrs. Yuvarani, Lead, Education and Research Department, Infosys for giving valuable suggestions.

CREATE DATABASE jpaDB;

GRANT ALL ON jpaDB.* TO jpaDB@"%" IDENTIFIED BY "jpaDB";
GRANT ALL ON jpaDB.* TO jpaDB@"localhost" IDENTIFIED BY "jpaDB";

USE jpaDB;       

Set up a connection to a MySQL database from NetBeans IDE 6.1

NetBeans IDE 6.1 comes with support for the MySQL database. To set up MySql properly in Netbeans IDE 6.1 follow the steps below.

• 1. In Services window expand Databases node. See the screen shot below.

• 2. Right click on MySQL server node. MySQL Server Properties dialog window opens.

• 3. Already host name, port number and admin user name will be pre populated in the dialog. If not then fill in properties and click on ok.

Note: Before you can connect to a MySQL Database Server, you must first ensure that the MySQL Database Server is running on your machine. The MySQL Server node in the Service indicates whether the MySQL Database Server is connected, as shown in the following image.

• 4. After starting the Database Server on your machine, start the MySQL Database Server in the IDE by right-clicking the MySQL Server node and choosing Start.
• 5. Now expand the MySQL server node. We can see the database which we created using command prompt. (We also can create the database using netbeans itself. Since we have created the database already we don’t cover those steps in this artical).

• 6. Now we will connect the database as shown below in the figure. Enter the password for the user if there is one, then click OK to create the new database connection. Click OK again if no schema is required.

• 7. we can see the database appearing in the services window.

Creating Table in MySql 5.0

Now we will create a table and name it as “USER”.
In the services window expand the database (See the figure below)
we created in the previous section. Right click on the table node.
select create table.

Invoking on create table node will result in create table dialog.
This window will halp us in creating the table with ease as shown in the below diagram.

Create a JavaApplication in NetBeans 6.1

Now create a java application in NetBeans IDE. Let us name the application as MyJPAApplication.

Next step is to generate a Entity class which will map to User table.

Select the database created as shown in the below figure.

You can now see the tables available in the database will be listed in the Available Tables menu.
Select the user table and click on Add to move it to Selected tables menu.

Change the class name in the next wizard as UserGenEntity. Then click on Create Persistence Unit button.

In the create persistant unit wizard, change the Table Generation Strategy option to Create.

Now in the final wizard there will not be any information or warning messages shown. Then click on finish.

Once you clicked on finish. you can see the class named UserGenEntity getting generated in the Projects window of the IDE. You can also see the TopLink libraries getting added to the Libraries node as shown below.

Next step is to implement a Manager Class which handles the JPA persistence-context. That means this class is responsible to provide CRUD functionality for your instances and to communicate with your database.
We will name this manager class as UserManager. UserManager code is given in the below listing.

Sample JPA Application

package com.myJpa;

import java.util.List;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Query;

/**
 *
 * @author Sri hari
 */
public class UserManager {

    private EntityManager em;

    public UserManager(EntityManagerFactory emf) {
        em = emf.createEntityManager();
    }

    public void createUser(UserGenEntity user) {
        em.getTransaction().begin();
        em.persist(user);
        em.getTransaction().commit();
    }

    public UserGenEntity searchById(Integer id) {
        return em.find(UserGenEntity.class, id);
    }

    public void updateUser(UserGenEntity user) {
        em.getTransaction().begin();
        em.merge(user);
        em.getTransaction().commit();
    }

    public void removeUser(UserGenEntity user) {
        em.getTransaction().begin();
        em.remove(user);
        em.getTransaction().commit();
    }

    public List getAll() {
        Query query = em.createQuery("select a from UserGenEntity a");
        List list = query.getResultList();
        return list;
    }

    public void close() {
        em.close();
    }
}
        

Code List has the following methods:

• createUser — this method is used to create a user in the database.
• searchById — this method is used to search a user by ID.
• updateUser — this method is used to update a user from the table.
• removeUser — this method is used to remove a user from the table.
• getAll — this method is used to get all the users from the table.

Testing the JPA code

Now its time to test the code and see how it works. Before that don’t forget to add the driver for MySQL to your project library.

Testing can be done using JUnit or a simple Java class with main method. Here we will create a simple java class with main method to test our code.

package com.myJpa;

import java.util.List;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

/**
 *
 * @author Sri hari
 */
public class TestJPA {

    private UserManager um;
    private EntityManager em;
    private EntityManagerFactory emf;
    private static final UserGenEntity user1 = new UserGenEntity(1, "Muthu", "Dhanagopal");
    private static final UserGenEntity user2 = new UserGenEntity(2, "Sri", "Hari");

    protected void setUp() throws Exception {
        emf = Persistence.createEntityManagerFactory("MyJPAApplicationPU");
        em = emf.createEntityManager();
        um = new UserManager(emf);
    }

    protected void close() throws Exception {
        um.close();
        em.close();
        emf.close();
    }

    public void test() {
        um.createUser(user1);
        UserGenEntity user = um.searchById(1);
        System.out.println("After creation of user in table");
        System.out.println("Firstname: " + user.getFirstname());
        System.out.println("Lastname: " + user.getLastname());

        user.setFirstname("Muthukumar");
        um.updateUser(user);

        user = um.searchById(1);
        System.out.println("After update.");
        System.out.println("Firstname: " + user.getFirstname());
        System.out.println("Lastname: " + user.getLastname());

        System.out.println("Adding one more record");
        um.createUser(user2);

        List list = um.getAll();
        System.out.println("Number of users: " + list.size());
    }

    public static void main(String args[]) {
        System.out.println("Inside TestJPA main");
        TestJPA testJPA = new TestJPA();
        try {
            testJPA.setUp();
            testJPA.test();
            testJPA.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
        System.out.println("End of TestJPA main");
    }
}
        

Result

init:
deps-jar:
compile-single:
run-single:
Inside TestJPA main
[TopLink Info]: 2008.07.27 09:42:50.500--ServerSession(16602326)--TopLink, version: Oracle TopLink Essentials - 2.0.1 (Build b09d-fcs (12/06/2007))
[TopLink Info]: 2008.07.27 09:42:52.253--ServerSession(16602326)--file:/C:/NetBeansProjects/MyJPAApplication/build/classes/-MyJPAApplicationPU login successful
[TopLink Warning]: 2008.07.27 09:42:52.410--ServerSession(16602326)--Exception [TOPLINK-4002] (Oracle TopLink Essentials - 2.0.1 (Build b09d-fcs (12/06/2007))): oracle.toplink.essentials.exceptions.DatabaseException
Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'user' already exists
Error Code: 1050
Call: CREATE TABLE user (ID INTEGER NOT NULL, FIRSTNAME VARCHAR(255), LASTNAME VARCHAR(255), PRIMARY KEY (ID))
Query: DataModifyQuery()
After creation of user in table
Firstname: Muthu
Lastname: Dhanagopal
After update.
Firstname: Muthukumar
Lastname: Dhanagopal
Adding one more record
Number of users: 2
[TopLink Info]: 2008.07.27 09:42:52.864--ServerSession(16602326)--file:/C:/NetBeansProjects/MyJPAApplication/build/classes/-MyJPAApplicationPU logout successful
End of TestJPA main
BUILD SUCCESSFUL (total time: 7 seconds)

Summary

In this article you have learnt how to develop a JPA persistence layer using Java Application. This is not the end, Still miles to go.

This article is the last part of the article series Java Persistence API (JPA), the earlier articles are introduction to JPA and the query api in JPA. This article is only for explaining the sample program with concepts used in the previous articles. I would recommend reading the previous two articles before start analyzing this sample code. If you are familiar with the JPA concepts, you can jump into the code and complete reading this article. If you have any doubts or queries, please post it in the comments section. Thank you for reading our blog. Have a fun!!

Following is a sample code in J2SE that creates and find Employee objects.

Code for Employee.java

package com.javabeat.ejb30.persistence.entities;

	import java.io.Serializable;
	import javax.persistence.Column;
	import javax.persistence.Entity;
	import javax.persistence.GeneratedValue;
	import javax.persistence.GenerationType;
	import javax.persistence.Id;
	import javax.persistence.NamedQueries;
	import javax.persistence.NamedQuery;

	@Entity(name = "EMPLOYEE")

	@NamedQueries({
		@NamedQuery(name = "Employee.findAll",
                query = "SELECT EMP FROM EMPLOYEE AS EMP")
	})

	public class Employee implements Serializable {

		@Column(name = "EMP_NAME", nullable = false, length = 100)
		private String name;

		@Column(name = "EMP_AGE", nullable = true)
		private int age;

		@Column(name = "EMP_SALARY", nullable = true)
		private double salary;

		@Id
		@Column(name = "EMP_ID", nullable = false)
		private Long id;

		public Employee() {
		}

		public String getName(){
			return name;
		}

		public void setName(String name){
			this.name = name;
		}

		public int getAge(){
			return age;
		}

		public void setAge(int age){
			this.age = age;
		}

		public double getSalary(){
			return salary;
		}

		public void setSalary(double salary){
			this.salary = salary;
		}
		public Long getId() {
			return this.id;
		}

		public void setId(Long id) {
			this.id = id;
		}
	}

The following code test the Employee entity class by creating some sample employee objects and then finding them using the Query API.

Code for EmployeeTest.java:

package employee.test;

	import com.javabeat.ejb30.persistence.entities.Employee;
	import java.util.Arrays;
	import java.util.List;
	import javax.naming.Name;
	import javax.persistence.EntityManager;
	import javax.persistence.EntityManagerFactory;
	import javax.persistence.Persistence;
	import javax.persistence.Query;

	public class EmployeeTest {

		private static EntityManagerFactory entityManagerFactory =
	     Persistence.createEntityManagerFactory("EmployeePersistentUnit");

		private EntityManager entityManager;

		public EmployeeTest() {
			entityManager = entityManagerFactory.createEntityManager();
		}

		public void createEmployees(){
			try{
				beginTransaction();
				Employee emp1 = createEmployee("Johny", 35, 10000, 1L);
				entityManager.persist(emp1);
				Employee emp2 = createEmployee("David", 43, 50000, 2L);
				entityManager.persist(emp2);
				Employee emp3 = createEmployee("Philip", 55, 70000, 3L);
				entityManager.persist(emp3);
				Employee emp4 = createEmployee("James", 29, 30000, 4L);
				entityManager.persist(emp4);
			}catch (Exception exception){
				failTransaction();
			}finally{
				commitTransaction();
			}
		}

		public List findAllEmployees(){
			Query query = entityManager.createNamedQuery("Employee.findAll");
			List employees = query.getResultList();
			return ((List)employees);
		}

		public Employee findByName(String empName){
			String queryString =
	"SELECT EMP FROM EMPLOYEE AS EMP WHERE EMP.EMP_NAME = ?1";
			Query query = entityManager.createQuery(queryString);
			query.setParameter(1, empName);
			return (Employee)query.getSingleResult();
		}

		public void display(List employees){
			for(Employee employee : employees){
				display(employee);
			}
		}

		private void display(Employee employee){
			StringBuilder results = new StringBuilder();
	results.append("Name = " + employee.getName() + ", Age = "
                     + employee.getAge() + ", ");
	results.append("Salary = " + employee.getSalary() + ",
                     Id = " + employee.getId());
			System.out.println(results.toString());
		}

		private void beginTransaction(){
			entityManager.getTransaction().begin();
		}

		private void commitTransaction(){
			entityManager.getTransaction().commit();
		}

		private void failTransaction(){
			entityManager.getTransaction().rollback();
		}

		private Employee createEmployee(String name, int age,
                         double salary, long primaryKey){
			Employee employee = new Employee();
			employee.setName(name);
			employee.setAge(age);
			employee.setSalary(salary);
			employee.setId(primaryKey);
			return employee;
		}
	}

For the above code to work, we have to create a persistence.xml file that contains the configurations for the EntityManager object like the database name, its URL, username/password etc inside the META-INF directory. Since it is a J2SE application we have to declare the type of transaction as Resource-Local. The following is the persistence.xml

Persistence.xml file:

<?xml version="1.0" encoding="UTF-8"?>
	<persistence>
	<persistence-unit name="EmployeePersistentUnit"
         transaction-type="RESOURCE_LOCAL">
                <provider>oracle.toplink.essentials.
               ejb.cmp3.EntityManagerFactoryProvider</provide>
		<class>
                    com.javabeat.ejb30.persistence.entities.Employee
                </class>
		<properties>
		  vproperty
	name="toplink.jdbc.url" value="jdbc:derby://localhost:1527/sample"/>
		  <property
	name="toplink.jdbc.user" value="app"/>
	 <property
	name="toplink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
		  <property name="toplink.jdbc.password" value="app"/>
		  <property name="toplink.ddl-generation"
                   value="drop-and-create-tables"/>
		</properties>
	  </persistence-unit>
	</persistence>

The above example uses the apache derby database for persisting the Employee objects as represented by the provider tag.

also read:

• Introduction to JPA
• The query api in JPA.

also read:

• Introduction to JPA
• Sample Application Using JPA

Types of Queries

Queries can be classified into two different types depending upon how actually the query string is defined. One is the static query (Named Query) and the other one, the Dynamic Query.

Static Query

A static query (or a named query) is one which is defined statically with the help of annotation (or XML) before the entity class. A name is usually given to the query definition so that other components in the same persistent unit can refer the query using the same.

For example,

@NamedQuery(name = "MobileEntity.findAll"
                  query = “SELECT M FROM MOBILEENTITY”)
	@Entity
	class MobileEntity{
	}

A named query (with a name ‘Mobile.findAll’) has been defined and this query can be referenced later in the code through its name, like this.

Query findAllQuery = entityManager.createNamedQuery
               ("MobileEntity.findAll");
	// Execute the query.

Note that the code is referring the query by its name (‘Mobile.findAll’) by calling the createNamedQuery() method. Also, since these named queries are statically defined, during deployment time itself, the persistent engine may parse and translate the JPQL into native SQL, cache them, thereby yielding better performance.

Multiple named queries can be logically defined with the help of @NamedQueries, like this,

@NamedQueries( {
	@NamedQuery(name = "Mobile.selectAllQuery"
                query = "SELECT M FROM MOBILEENTITY"),

		@NamedQuery(name = "Mobile.deleteAllQuery"
         query = "DELETE M FROM MOBILEENTITY")
	} )

[The @NamedQueries is very similar like @NamedQuery, but can accept multiple @NamedQuery objects, The definition of the @NamedQueries looks like this,

@interface NamedQuries{
		NamedQuery[] value;
	}

The way to specify arrayed elements with the definition of an annotation is by using {}. So was defined for the @NamedQueries( {…} ) and since the property called ‘value’ is the default property name for annotation, there is no need to explicitly mention the property name in the annotation definition. Following also works well which explicitly defines the property name ‘value’ for the annotation @NamedQueries.

@NamedQueries(value = { …. } )

Dynamic Queries

Dynamic Queries are nothing but whose query strings are provided at run-time. All calls to EntityManager.createQuery(queryString) are actually creating dynamic query objects. By defining query objects in this way, we lose the efficiency and from the performance point of view, the query execution may be slow as the persistence engine has to do all the parsing and validation stuffs, along with mapping the JPQL to the SQL at the run-time.

Following code creates a dynamic query object on the fly.

String queryString = …… // Obtained during run-time.
	Query dynaQuery = entityManager.createQuery(queryString);

Static Queries will be a better choice if the scenario for which the query to be executed is well known in advance.

Query Operations

Subsequent topics cover how to work with the query API for locating the entity objects, named and the positional support for Query objects and Paging Query Results for performance.

Single Result

The following code shows how to execute a query that returns a single entity object (assuming that a table called MobileEntity with field’s model, manufacturer and imei are available in the database).

Query singleSelectQuery = entityManager.createQuery(
	"SELECT M FROM MOBILEENTITY WHERE M.IMEI = 'ABC-123'");
	MobileEntity mobileObj = singleSelectQuery.getSingleResult();

The query string that’s defined inside the createQuery() method is the Java Persistence Query Language. The Java Persistent Query Language (JPQL) resembles more like a SQL. The query statement is a simple select statement that is used to select a particular mobile object with imeiNo ‘ABC-123’. M represents a named instance row, which can be used to directly refer the fields in the corresponding table.

A call to getSingleResult() will execute the query and returns a single row that matches the search criteria in the query string. If the match wasn’t successful, then the getSingleResult() will return an EntityNotFoundException. Also, if more than one matches occur during query execution (this may not happen in our case, since imeiNo is a primary key), a run-time NonUniqueResultException will be thrown.

Multiple Results

Query.getResultList() will execute a query and may return a List object containing multiple entity instances. The following code demonstrates the same.

Query multipleSelect = entityManager
                .createQuery("SELECT M FROM MOBILE");
	List mobiles =
	(List)multipleSelect.getResultList();

The type-cast (List) is necessary as the getResultList() method will return a non-parameterized List object. If only one mobile object is found as a result of executing the query, then this method may simple return a list with size 1. Also note that, getResultList() method can only execute on select statements as opposed to UPDATE or DELETE statements. If any statement other than SELECT statement is passed on to the method, then an IllegalStateException will be thrown at the run-time.

Working with parameters

To reuse and to execute the query more efficiently with different set of values, one can depend on the parameter support (positional and named) offered by the JPA. These techniques resembles the one we had for the java.sql.PreparedStatement where one can prepare the statement object once and can execute the query with different set of parameter values again and again.

The positional parameter is used to bind the parameter value in terms of positional index and it is denoted by ?index within the query string. Similarly the named parameter is used to substitute the parameter value which is specified in terms of :name.

Following examples will clarify the above concepts,

String selectQuery =
	“SELECT M FROM MOBILE WHERE M.MODEL = ?1 and M.MANUFACTURER = ?2”;
	Query selectQuery = entityManager.createQuery(selectQuery);

	selectQuery.setParameter(1, model);
	selectQuery.setParameter(2, manufacturer);

The above code illustrates the positional parameter support, during query execution,?1 and ?2 will be replaced with the values specified for model and manufacturer.

For named parameter, the parameter can be given with some meaningful name prefixed with :, like the below code,

String selectQuery = "SELECT M FROM MOBILE WHERE M.MODEL =
                 :modelName and M.MANUFACTURER = :manufacturer";
	Query selectQuery = entityManager.createQuery(selectQuery);

	selectQuery.setParameter(“modelName”, model);
	selectQuery.setParameter(“manufacturer”, manufacturer);

It is not that only dynamic queries can be benefited with positional and named parameters. Even for statically defined queries, the same is applicable. We can embed : or ? even in the static query definitions also,

@NamedQuery(
	name =
	"Mobile.findByModel” query = "SELECT M FROM MOBILEENTITY WHERE
                    M.MODEL  = :modelName
	)
	…

And later in code,

Query namedQuery = entityManager.createNamedQuery("Mobile.findByModel");
	namedQuery.setParameter("modelName", model);

Paging Query Results

Imagine that a select query is returning larger number of record entities, it may not be advisable to show the entire set of results to the end-user as it may eat performance. The following two methods can be used in tandem to solve this kind of performance issue.

Assume that we have 1000 mobile entities in our database and we wish to show only 100 objects in an application that displays them in a nice tabular view. In the following code, before calling the getResultList(), which will return all the mobile objects in the database, the query object is well configured with setMaxResults(maxResults) method (the number of maximum entity objects that will be returned) setFirstPosition(position) method (which tells starting position of the pointer is made to point to).

int maxRecords = 10;
	int startPosition = 0;
	String queryString = “SELECT M FROM MOBILEENTITY”;

	while(true){

		Query selectQuery = entityManager.createQuery(queryString);
		selectQuery.setMaxResults(maxRecords);
		selectQuery.setFirstResult(startPosition);
		List mobiles = entityManager.getResultList(queryString);

		if (mobiles.isEmpty()){
			break;
		}

	//Process the mobile entities.
	process(mobiles);
	entityManager.clear();

	startPosition = startPosition + mobiles.size();
	}

The above code loops through all the 100 objects in the database in a more efficient way. Also note that the EntityManager.clear() method is called every time, to clear (or to detach) the mobile objects which will make the EntityManager less burdened in terms of managing the mobile objects.

Flushing Query objects

JPA provides two modes of flushing query objects namely AUTO and COMMIT (which are defined in FlushModeType Enumeration). If the AUTO mode is set on the Query object which is the default one, then any changes made to entity objects will be reflected the very next time when a select query is made. That means that the persistence engine must make sure to update all the states of the entity objects which will affect the results of a SELECT query.

The AUTO flush mode can be set explicitly on the Query by calling setFlushMode().

queryObject.setFlushMode(FlushModeType.AUTO);

When the flush mode is set to COMMIT, then the persistence engine, may only update all the state of the entities during the database COMMIT. The dirty changes applied to entity objects and then querying for the results of the entities may be unspecified.

queryObject.setFlushMode(FlushModeType.COMMIT);

[The method setFlushMode(FlushModeType) is available in both EntityManager and Query interface. If the EntityManager has been configured with setFlushMode(FlushModeType.AUTO) and the Query object has been called with setFlushMode(FlushModeType.COMMIT), then the preference will always goes to the Query object.]

Persistent Units

Before getting into the theory of what is a persistence unit and how it has relations with EntityManagerFactory and EntityManager, let us look into a sample persistence.xml file.

<?xml version="1.0" encoding="UTF-8"?>
	<persistence>
	<persistence-unit name="EmployeePersistentUnit" transaction-type="RESOURCE_LOCAL"> <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provide>
		<class>com.javabeat.ejb30.persistence.entities.Employee</class>
		<properties>
		  vproperty
	name="toplink.jdbc.url" value="jdbc:derby://localhost:1527/sample"/>
		  <property
	name="toplink.jdbc.user" value="app"/>
	 <property
	name="toplink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
		  <property name="toplink.jdbc.password" value="app"/>
		  <property name="toplink.ddl-generation" value="drop-and-create-tables"/>
		</properties>
	  </persistence-unit>
	</persistence>

[A persistence.xml file is used to manage one or more persistence units. Like web.xml for a servlet application and ejb-jar.xml for an EJB application, this persistence.xml is a must for an entity application to run.]

At a very high-level, we can infer multiple persistence units within the same persistence.xml file being uniquely identified by its name tag. Each persistence unit is configured with a provider along with its data-source and with some set of entities. So, we can say that a persistence unit provides a logical grouping for some set of entities that share some configuration.

Imagine an application is having so many entity objects and these entity objects have been nicely categorized in a way that some set of entities are sharing a common provider (Toplink, for example), acting on some data-source, whereas other set of entities are depending on a different provider (Hibernate, for example). In such a case, we can define a persistent unit with some configuration properties for some set of entities and a different persistent unit with different set of configuration properties for the remaining entities. So a persistent unit is a way to categorize some set of entities that aimed to do some common goals and common configurations to share with.

Back to the above sample code, we have two different persistent units, one being configured to point to Toplink provider with the help oftag, and the other one pointing to a hibernate provider. We also have put some vendor specific hints (or properties) through the property tag (found within the properties tag). The meaning of toplink.ddl-generation with value drop-and-create-tables essentially tells the Toplink persistence engine that during deployment time, if already there exists a table for the corresponding class MobileEntity, just drop (delete ) the table and create it before using. Similarly the property-value pair “hibernate.hbm2ddl.auto-update” tells the persistence engine, to use the existing table and not to recreate it. Thetag represents the name of entity class that is to be included as part of this persistent unit.

Now, that we have a basic understanding about persistent units that how they are useful in categorizing entity objects, now its time to see how EntityManager and persistent units are related. In a regular J2SE application, instances of EntityManager class are obtained through EntityManagerFactory which is turn is obtained through the boot-strap class Persistence.

The following shows the sample code to achieve the same,

String persistentUnitName = "MyMobilePersistentUnit";
	EntityManagerFactoryfactory  factory = Persistence
                 .createEntityManagerFactory(persistentUnitName);
                       // Line 1

	EntityManager entityManager = factory.createEntityManager();
                    // Line 2

In line 1, an instance of EntityManagerFactory is obtained with a call to createEntityManagerFactory() with the name of the persistent unit being passed as an argument. At this stage, we know that the persistent unit by name MyMobilePersistentUnit has been configured with Toplink as its provider along with a data source object with some additional vendor specific properties. Therefore, EntityManager objects being created for this kind of configuration from the EntityManagerFactory have this configuration for their entire life-time.

In the case of a J2EE application , one can instantiate an instance of EntityManager object backed up with @PersistentUnit like this,

@PersistentUnit(unitName = "MyMobilePersistentUnit")
	private EntityManager entityManager;

Now, the EntityManager object will have the set of configuration parameters being loaded as referenced by the persistent unit name "MyMobilePersistentUnit".

also read:

• Introduction to JPA
• Sample Application Using JPA

also read:

• The Query API in JPA (EJB 3.0)
• Sample Application for Java Persistence API (JPA)

class MyServlet extends HttpServlet {}
	class MyRemote implements SessionBean {}

In the above cases, both MyServlet and MyRemote extends and implement specialized Servlet and Bean classes, therefore, these classes cannot be termed as POJO’s.

When we say that JPA follows the POJO standard, it follows that the entities (or the entity class) are very regular and normal Java classes, in the sense that they doesn’t need to extend or implement some specialized classes].

[OR Mapping – Object-Relation mapping is the process of the transformation of the data between the class objects and databases. Applications can depend on an OR-M like tool that greatly simplifies this work instead of manually coding the transformation process.]

About Persistence Entites

Persistent Data normally refers to permanent data in an application. The state of these data is made permanent by storing them in a persistent medium like database, files or a disk tape. In JPA terms, these persistent data are referred as entities. An entity refers to a logical collection of data that can be stored or retrieved as a whole. For example, in a banking application, Customer and BankAccount can be treated as entities. Customer name, customer address etc can be logically grouped together for representing a Customer entity. Similarly account number, total balance etc may be logically grouped under BankAccount entity.

Since entities form the heart of the JPA, they have some unique characteristics like persistability, identity and transactionability. The property of persistability deals with the storing and retrieving of entity from and to a persistent medium like database. Identity property is usually used to identity one unique entity among multiple entities (or multiple entity instances) in a database. All the CRUD operations (Create, Update and Delete) for entity objects will occur within a transactional context and it is one of the major characteristic for an entity object as the real state of an entity depends whether a transaction completes (commits/fails) or not.

Persistence API

All the classes, interfaces and annotations that make up the Java Persistence API are available in a single javax.persistence package. A brief look at the core objects and concepts within the package will be much useful before dealing with some sample code.

Entites

As mentioned previously, in JPA terms an entity refers to a persistent object which can be stored and retrieved from a persistent storage. In technical terms, this entity will correspond to a Java class.

Consider the following simple java class, named MobileEntity.

class MobileEntity{

	private String model;
	private String manufacturer;
	private Double price;
      private String imeiNo;

	…..
	// Getters and Setters go here.
}

The above class represents a mobile object which has its own model, manufacturer, price and an imei number. Suppose, we wish to persist this mobile java class using JPA. The first step is to qualify this java class as an entity. This is done by marking the class with @Entity annotation. Marking a class with @Entity annotation will tell to the persistence engine that objects created from this class can use the support of JPA to make them persistent. After adding the @Entity annotation to the above class the code looks like this,

@Entity
class MobileEntity{

	private String model;
	private String manufacturer;
private Double price;
	private String imeiNo;

	…..
	// Getters and Setters go here.
}

[A persistence engine or a persistence provider is nothing but an implementation of the Java Persistence API. Java Persistence API is just a specification from Sun and not an implementation and vendors are free to implement their own persistent framework following the JPA specification. Thus, JPA provided a pluggable interface, where more and more implementations can easily be associated with it at run-time.]

Since an entity always has an identity associated with it, it is the job of the programmer to tell to the persistence engine, how uniquely to identity an entity object. This is simply done by marking a field (or a set of fields) with the @Id annotation. A field that is marked with @Id annotation will be treated as a primary key for the table by the persistent engine.

It is an error to ignore any one of the fields in an Entity class with @Id annotation, because the persistence engine won’t be in a position to identity unique entity objects without the help of primary keys. In our case, since no two mobile phones in the world share the same IMEI (International Mobile Equipment Identity), imeiNo is an ideal candidate to be marked with @Id annotation.

@Id
	private String imeiNo;

It is an error to give null values, to a primary key field, during that case, the persistence engine may throw any kind of database exception.

The following is the default values for table and column names when the persistence engine was Oracle’s Toplink during the deployment time.

• Alias Name – MobileEntity (the unqualified (with-out the package name) name of the class).
• Table Name – MOBILEENTITY
• Column Names – [MODEL, MAUNFACTURER, PRICE and IMEINO] (These correspond to the variable names).

Customizing the Entity object

In most of the cases, the defaults that are created and provided by a persistence engine are sufficient. However, certain situations may demand for customization which includes factors like name collision, companies adopting standard naming conventions, etc., like that. In such a case, the entity class can greatly be customized with a huge set of annotations available in the javax.persistence package. Let us take a look one by one.

Changing the default table name

By default the table name corresponds to the unqualified name of the class. We can change this behavior with the help of @Entity annotation itself, like this.

@Entity(name = "MOBILE_ENTITY")
	public class MobileEntity{
	……
	}

Now, the table name becomes MOBILE_ENTITY and this should be the name that must be referred in query strings (Queries are discussed later). The value to the name property must be legal in the sense, it cannot accept any keywords that are found in the query language.

Customizing the Column behaviors

The default name of the columns, their size, whether they can accept null values or not etc., can be customized using the @Column annotation. Following is the sample code that illustrates this,

@Column(name = "MOBILE_MODEL", nullable = true, length = 35)
	private String model;

	@Column(name = "MOBILE_MANUFACTURER" nullable = true, length = 100)
	private String manufacturer;

	@Id
	@Column(name = "MOBILE_IMEI_NO", nullable = false)
	private String imeiNo;

The name property, when specified will override the default column name (which is the same as that of the field name in the Entity class). The nullable property tells that whether the column can accept null values. Length property is only applicable if the type of the column is String (or VARCHAR). There are also properties like scale and precision which is applicable only when the type of the column is NUMBER.

[Note, multiple annotations can be legally applied to elements (like class, field, method etc.). In the above example the imeiNo has two annotations attached with it, namely @Id and @Column.]

Auto-generation of Primary Keys

A primary key for an entity which is usually annotated with @Id annotation can be given a value manually or we can depend on the persistence provider for the same. For this we have to use the @GeneratedValue annotation.

Consider the following example,

@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	private String imeiNo;

Since the imeiNo is going to be the primary key for the mobile object, we have decorated the field with @GeneratedValue annotation, which delegates the burden of creating values from developers to the persistence engine. Also, there are 4 different methods (or strategies) for primary key generation, which are AUTO, IDENTITY, SEQUENCE and TABLE. The simplest one is the automatic primary key generation strategy which is represented as GenerationType.AUTO.

[GenerationType is an Enumeration (new feature in Java 5.0) and the four different strategies for primary key generation, namely AUTO, IDENTITY, TABLE and SEQUENCE are defined in that enumeration.]

EntityManager

This class follows the standard Manager Design pattern for managing entities. Managing an entity or a set of entities refers to the act of bring a set of Java objects under the control of EntityManager. Unless entities don’t have any explicit association with EntityManager they are just ordinary java objects (though their corresponding classes have been marked with @Entity annotation).

This EntityManager API provides services for persisting an entity, removing an entity, querying and deleting entities.

In a J2SE application, a reference to an entity manager (EntityManager) can be obtained using the entity manager factory (EntityManagerFactory) and the Persistence class. The persistence class is a helper class (or a bootstrap) used to create EntityManagerFactory objects. With EntityManagerFactory objects, references to EntityManager objects can be obtained. The following code illustrates the same,

EntityManagerFactory entityManagerFactory =
  Persistence.createEntityManagerFactory("PersistentUnitName");
  EntityManager eManager = entityManagerFactory.createEntityManager();

[An EntityManagerFactory can be configured with some set of properties with the help of Persistent Units. Notice that one of the arguments to createEntityManagerFactory() is the name of the persistent unit which is discussed in the later sections.]

In a J2EE application, the container will directly inject a reference to the EntityManager using dependency injection, so the code becomes as simple like this,

@Resource
private EntityManager entityManager;

Persistence Context

To be very precise, a persistent context manages a set of entities which in turn is managed by the EntityManager. A persistent context keeps track of the state (or the changes) that an entity object may undergo. And the EntityManager takes the support of this persistence context to commit or to undo the changes. As soon as an EntityManager object is created, it is implicitly associated with a persistence context for managing a set of entities.

Persistent Context comes in two flavors, one is the transaction-scoped persistent context and the other one is extended persistent context.

Transaction-Scoped Persistence Context: Imagine that a set of entities are managed by the persistence context. At this time, we say that the entities are bound to (or attached) to the persistent context. Changes may happen to these entities and these changes will occur within a transaction. Sometimes later when the transaction ends (commits or roll-back), the entities will unbind (detached) from the persistent context. As soon as the entities are detached from the persistence context, they are no longer being managed. Any changes that happen to these entities will not be persisted as they don’t have any association with the persistence context. Such kind of persistent context whose life-time is dependent on the life-time of the transaction (for a set of entities at that particular point of time) is termed as transaction-scoped persistent context.

All the transaction-scoped persistence context are configured by injecting @PersistentContext to EntityManager objects , like this,

@PersistenceContext(name="PersistentUnitName")
private EntityManager entityManager;

[Note: There is no such public interface called PersitenceContext in the Java Persistence API. The EntityManager may implicitly depend on a virtual Persistence Context class for managing the entities. So, creating a transaction-scoped persistence context is nothing but creating an EntityManager object that has been configured with @PersistenceContext annotation.]

Extended Persistence Context: Unlike transaction-scoped persistence context, where the life-time of the persistence context will end as soon the transaction is completed, a persistence context may be configured to live even after a transaction completes. In such a case, all the entities that are managed by such a persistence context will still be in a manageable state only even after the transaction ends. They won’t be detached from the context. Such long-lived persistence context that will continue to exist even after the completion of a transaction is called extended persistence context.

All the extended persistence context objects are created and managed manually by the application code only (that is by the developers).

[As soon as an EntityManager object is created, an implicit Persistence context will be associated with it and it is soon kept open and prepared for managing a set of entities, meaning that the calling EntityManager.isOpen() method will always return true. Calling the EntityManager.clear() method will clear the current persistence context associated with the EntityManager and all the entities that have their associations will now be cleared and they become detached from the EntityManager. To release all the resources referenced by the EntityManager, call the close() method, After this method call, calling any of the methods will throw IllegalStateException.]

Entities and Transactions

All entities have the property of transactionability and their CRUD operations will take place within a transactional context. Transactions can be broadly classified into two types based on who actually owns (or manages) the transaction. They are JTA and Resource-local transaction.

In the case of a J2EE Application, the default transaction type is JTA (Java Transaction API), unless explicitly specified. A method can be simply annotated with @RequiresNew (or @Requires) in which case a new transaction will always started by the container and the transaction completes as soon as the method ends.

Whereas in a J2SE application, the transaction-type defaults to Resource-local, which means that the developer (or the application code) has to explicitly start and end a transaction. It means that the user has to explicitly start a transaction with the help of EntityManager object, and then have to commit it, if everything goes normal, else have to roll-back the transaction if some error occurs.

The following code shows this,

EntityTransaction userTransaction = entityManager.getTransaction();
  try{
	userTransaction.begin();

	 // Do something here.

	// If everthing goes well, make a commit here.
	userTransaction.commit();
	}catch(Exception exception){
		// Exception has occurred, roll-back the transaction.
		userTransaction.rollback();
	}

Operations on Entity Objects

The following are the legal operations that can be performed on Entity objects with the help of EntityManager API. As seen previously, EntityManager are objects that manage one or more entity objects with the help of an implicit persistence context.

Persisting Entity Objects:

Entity objects are like regular java objects until they become managed and made persistent by the EntityManager. The following piece of code makes an entity to become persistent and managed.

MobileEntity mobileObject = new MobileEntity();
	mobileObject.set()... // Update the state values here.
	entityManager.persist(mobileObject);

The persist(entityObject) methods makes the entity persistent in the underlying database and managed within the persistence context of the EntityManager, whether the persistence context is a transaction-scoped or an extended persistence context depends upon how actually the EntityManager was configured.

[What happens when a managed entity is again forced to become managed by calling the persist() method. Or what happens when the persist() method is called couple of times on the same entity object.

Whenever the persist() method is called, the persistence engine will check for the existence of that object with the help of its unique identifier (which is represented in the form of primary key). If any duplicate object is found, then a run-time exception, EntityExistsException will be thrown.]

Querying for Entities:

Developers can either depend on the EntityManager for simple search or Query objects for providing powerful search conditions for locating and querying entity objects.

Using EntityManager object:

Following are the two different methods available in EntityManager interface for querying entity objects and there are some major differences between the two.

Using the EntityManager.find() method:

The find() method takes the class name of the Entity object and the primary key value for locating a single entity object. If the object of interest cannot be located by the EntityManager, then this method will simply return null. The following code illustrates this,

MobileEntity mobile = entityManager.find(MobileEntity.class, "ABC-123");
 If (mobile != null){ // mobile object may or may not be null.
 // Process the object.
 }

One good thing about the find() method is that, the returned entity object soon becomes managed automatically within the persistence context of the EntityManager.

Using the EntityManager.getReference() method:

This method, like the EntityManager.find() method, takes the name of the entity class and the primary key as their arguments. But the difference is, unlike the find() method which will return null if the entity object is not found, this method will throw an exception EntityNotFFoundException. Another difference between this method and the find() method is that, the entity that is fetched by this method may be lazily loaded. That is, the state of the state of entity (like model, manufacturer, imeiNo may be lazily loaded during the first time it is actually accessed).

MobileEntity mobile = entityManager.getReference(
     MobileEntity.class, "ABC-123");
// mobile object may not contain the actual state
//values for model, manufacturer
// and imei number, the states may be loaded during the first access.

String model = mobile.getModel();
// The persistence engine may fetch the model value for the mobile here
// at this particular point of time.
…..

Using the Query object:
Discussed later.

Deleting Entities:

To remove (delete) an entity object from the database, make a call to EntityManager.remove(entityObject) method. The entity object that is passed to the remove() must be a managed entity, else the operation will fail.

Also, making this call may or may-not remove the entity immediately from the database. The algorithm that achieves the same is implementation specific. Some implementation may only mark the entity as a removed entity after this method call, and the actual deletion of the entity object in the database may happen when a flush() operation (which is discussed later) is made.

After this method call, the entity will become detached from the persistence context and it is no longer a managed one.

Updating Entities:

The EntityManager.merge(entityObject) method will make a detached entity to get associated with the current persistence context of the EntityManager. Consider the following lines of code.

// Transaction has begin.
…..
MobileEntity mobile = entityManager.find(MobileEntity.class, "ABC-123");
…..
// Transaction ends.
mobile.set()…… // Updating the mobile object.
entityManager.merge(mobile);

In the above piece of code, a mobile entity object is located with the EntityManager.find() method. This entity is now in a managed state. Assume that the transaction ends after some point of time and also the persistence context is a transaction-scoped persistence context. As soon as the transaction completes, the persistence context will go off, (since the persistence context is a transaction-scoped persistence context). So the entity object becomes detached from the persistence context. After this any modifications that are made to the mobile object won’t be knowledgeable to the EntityManager as the mobile object has already been detached from it.

Now, calling the merge() method, will make the mobile object becomes managed, and all the recent changes that are made to it will become visible to the current persistence context of the EntityManager.

Flushing and Refreshing:

The EntityManager.flush() will synchronize all the changes that are made to the persistent entities back to the underlying database, whereas the EntityManager.refresh() does the reverse. It will update the entity object with values taken from the database. Any new values that are set to the entity objects will be lost as a result of this method call.

For example, consider the following piece of code,

MobileEntity mobile = …..
	mobile.set(); // Update the state values for the mobile object.
	….
	entityManager.flush();
	// Calling this flush method will synchronize the database with the values
	// taken from the entity object.

Now consider this code,

MobileEntity mobile = …
	mobile.set(); // The state values for the mobile object is updated.
	…..
	entityManager.refresh();
	// The refresh() method will refresh the entity object
        //with the values taken from the database.
	// All the updates that are done are lost.

Summary

also read:

• The Query API in JPA (EJB 3.0)
• Sample Application for Java Persistence API (JPA)

The above two links are continuous of this article with more features and the sample application for the JPA.This article began with the discussion of Java Persistent API and its advantages and what persistent entities are. Then the terminologies that are very specific to JPA like EntityManager, PersistenceContext have been discussed. The various features about the Query interface for locating Entity objects were explored in depth. Finally, it ended with Persistent Units and its relation with EntityManager objects along with a sample J2SE application.