Defining JPA Persistence Units in your Java Enterprise Applications

By Rob Gravelle

Defining JPA Persistence Units in your Java Enterprise Applications

In the Java Persistence API (JPA), Persistence Units are declared in the persistence.xml file. JPA defines a Persistence Unit as a logical grouping of persistable classes along with their related settings. The Persistence Unit settings are then referenced by the EntityManagerFactory in JPA in order to manage transactions. In the Connect to a Database from your Java Enterprise Applications tutorial, we wrote a JUnit test to verify the database connection. In today's follow-up, we'll be writing the persistence.xml file and DAO class that will handle all database transactions.

The persistence.xml File

The persistence.xml file may include definitions for one or more Persistence Units, which each in turn containing a number of properties and attributes. At the very least, you'll want to include one persistence-unit with a name attribute (the EntityManagerFactory will need it to refer to the persistence-unit), as well as database connection information such as the URL, ID, and password.

Here is the persistence.xml file that we will be using for our Exercise application. Notice the persistence-unit name of "ExercisesPU". We'll be referring back to it at a later time.

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.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_2_0.xsd">
 
  <persistence-unit name="ExercisesPU" transaction-type="JTA">
    <provider>com.objectdb.jpa.Provider</provider>
    <properties>
      <property name="javax.persistence.jdbc.url" value="$objectdb/db/exercises.odb"/>
      <property name="javax.persistence.jdbc.user" value="admin"/>
      <property name="javax.persistence.jdbc.password" value="admin"/>
    </properties>
  </persistence-unit>
 
</persistence>

The above persistence.xml file defines a database named "exercises.odb" that can be accessed using the default $objectdb administrator credentials.

To add the persistence.xml file to your project:

  • Right-click on the META-INF directory, located under the Java Resources/src folder in the Project Explorer, and select new > XML File from the popup menu.
    If you don't see the XML File item on the menu,
    • Choose Other... at the bottom of the list to bring up the Select a wizard dialog.
    • Type "XML" in the search box and choose "XML File" from the XML folder.
    • Click Next > to continue.
    • On the next screen, name the file "persistence.xml".
    • Click Finish to create the file.
  • If it isn't already, open the file in the editor and paste the above code snippet into the editor, replacing the existing file contents. Save the file.

Coding the EJB Session Bean

All database operations will be handled by an EJB session bean instance that we will define in this step.

First, we'll create a package in which to put the bean:

  • Right-click on the src folder in the Project Explorer and select New Package from the popup menu.
  • In the New Package dialog, name the package "com.robgravelle.exercises.dao".
  • Click Finish to create the package.

Now we'll create the file inside our new package:

  • Right-click the new package in the Project Explorer and select New > Class from the popup menu.
  • Enter "ExercisesDAO" as the class name - pay attention to the case because Java is case-sensitive!
  • Click Finish to create the new session bean (EJB) class.

Session beans can either be stateful or stateless. With stateful beans, the EJB container saves internal bean data during and in between method calls on the user's behalf. With stateless beans, the user may call any available instance of an instantiated bean from the pool. This enables the number of bean instances, thereby saving memory.

A session bean represents work performed by a single user. That work can be performed within a single method invocation, or it may span multiple method invocations. In the case of the former, a stateless bean will suffice. However, if a transaction spans multiple method invocations, the bean must retain the user's object state across the method calls, requiring the use of a stateful session bean.

Generally, stateless beans are the lightest weight and easiest to manage of the various EJB component configurations, so we will use that type here.

To define our bean as being stateless, we would add the @Stateless annotation immediately before the class definition. Our bean will define two methods: one that saves an exercise to the database and one that retrieves all stored exercises.

Injecting the EntityManager Persistence Context

There are two types of Persistence Contexts: container-managed and application-managed. The great majority of Java EE applications - including the one we are building here today - use container-managed persistence. It's much easer to use because it lets the container inject the EntityManager for you. Alternatively, you can create an EntityManager by yourself via the EntityManagerFactory.

Declare a private EntityManager named "em" at the top of your class and preface it with the @PersistenceContext annotation:

@Stateless
public class ExercisesDAO {
    // Injected database connection:
    @PersistenceContext private EntityManager em;

The persist() Method

The persist() method will accept an Exercise instance and delegates the invocation to the EntityManager instance's method of the same name. It does not return a value:

// Stores a new exercise:
public void persist(Exercise exercise) {
    em.persist(exercise);
}

The getAllExercises() Method

The getAllExercises() method calls the EntityManager instance's createQuery() method, passing in a SELECT statement to retrieve all of the exercises in the database. The results of the method call are stored in a TypedQuery named "query". This method should return the results of a call to the query's getResultList() method:

// Retrieves all the exercises:
public List<Exercise> getAllExercises() {
   TypedQuery<Exercise> query = em.createQuery(
        "SELECT * FROM Exercises e ORDER BY e.name", Exercise.class);
      return query.getResultList();
}

The ExercisesDAO Source Code

Here is the full source code for the ExercisesDAO class:

package com.robgravelle.exercises.dao;

import java.util.List;

import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.TypedQuery;

import com.robgravelle.exercises.entities.Exercise;

@Stateless
public class ExercisesDAO {
    // Injected database connection:
    @PersistenceContext private EntityManager em;
 
    // Stores a new exercise:
    public void persist(Exercise exercise) {
        em.persist(exercise);
    }
 
    // Retrieves all the exercises:
    public List<Exercise> getAllExercises() {
        TypedQuery<Exercise> query = em.createQuery(
            "SELECT * FROM Exercises e ORDER BY e.name", Exercise.class);
        return query.getResultList();
    }
}

Conclusion

In the next instalment, we'll be adding a Servlet Class that will accept a request from the browser and invoke a DAO method accordingly. As such, it will function as our application controller.



Rob Gravelle

Rob Gravelle resides in Ottawa, Canada, and is the founder of GravelleWebDesign.com. Rob has built systems for Intelligence-related organizations such as Canada Border Services, CSIS as well as for numerous commercial businesses.

In his spare time, Rob has become an accomplished guitar player, and has released several CDs. His band, Ivory Knight, was rated as one of Canada's top hard rock and metal groups by Brave Words magazine (issue #92) and reached the #1 spot in the National Heavy Metal charts on Reverb Nation.



Make a Comment

Loading Comments...

  • Web Development Newsletter Signup

    Invalid email
    You have successfuly registered to our newsletter.
  •  
  •  
  •  
Thanks for your registration, follow us on our social networks to keep up-to-date