Using Java Persistence in a Web Application

Tutorial Exercises

• Configuring the IDE to Use the Application Server
• Setting Up the Web Application Project
• Coding the Web Application
• Running the Project

Prerequisites

This document assumes you have some basic knowledge of, or programming experience with, the following technologies:

• Java Programming
• NetBeans IDE

Software Needed for This Tutorial

For this tutorial you need to have the following software installed on your computer:

• "Web & Java EE" or "All" download of NetBeans IDE 6.0.
• Java Standard Development Kit (JDK) version 5.0 or version 6.0
• GlassFish V2 Application Server (bundled with full IDE download) or Sun Java System Application Server Platform Edition 9 (download)

Summary

In this exercise we registered the application server with the IDE.

Summary

In this exercise we created a Java EE 5 web application which will contain the entity classes.

Managing Persistence

To manage persistence in our application we only need to create a persistence unit, specify which data source and entity manager to use, and then let the container do the work of managing entities and persistence. The container discovers the entity beans at runtime.

We create a persistence unit by definining it in persistence.xml. If there is no persistence.xml in our project or module, we need to create it. We can add a persistence unit to our project with the New Persistence Unit wizard, which will help us create the persistence.xml and define the properties of the persistence unit. Note: We can also create a persistence unit in the New Entity Class wizard. When creating an entity class, the wizard will prompt us to create a persistence unit if one does not exist.

1. Choose New File (Ctrl-N) to open the New File wizard.
2. From the Persistence category, select Persistence Unit and click Next.
3. Leave the default name for the persistence unit suggested by the wizard.
4. Use the TopLink (default) listed in the Persistence Provider drop-down list.

   The default provider is the TopLink Essential.jar. TopLink Essential.jar contains the libraries for Java Persistence. Our entity manager is located in TopLink Essential.jar.

5. Use the default jdbc/sample data source listed in the Data Source drop-down list.

   The default data source jdbc/sample is used to connect to the Java DB database that is bundled with GlassFish/Sun Java System Application Server.

6. Click Finish.

When you click Finish, persistence.xml is created for your project and opens in the Source Editor. You can click XML in the toolbar of the Source Editor to see the XML view of persistence.xml. This file contains all the information the Java EE 5 container needs to manage the entities and persistence of our application.

Creating the Entity Classes

When developing for the J2EE 1.4 platform, when you created entity beans you placed them in an EJB module even when the application was a simple web application. Each entity bean required several interfaces, and you had to configure the deployment descriptors in ejb-jar.xml to define the entity beans, the interfaces, persistence and finder queries for each entity bean.

In Java EE 5, instead of creating entity beans and putting them in the EJB module, we can use simple entity classes, and the entity classes can be placed anywhere in a Java EE 5 application. Writing classes for Java EE 5 applications is also easier than it was for the J2EE 1.4 platform because you can use annotations to define components and inject resources.

We will now use the Entity Classes from Database wizard to create the entity classes based on our relational database.

1. Start the Java DB database by choosing Tools > Java DB Database > Start Server from the main menu.
2. Choose New File (Ctrl-N) to open the New File wizard. Select Entity Classes from Database from the Persistence category and click Next.
3. In the Entity Classes from Database wizard, select the jdbc/sample data source for our database from the Data Source drop-down list and supply the password if necessary. (The password should be "app".) When you select the data source, a list of available tables appears in the Available Tables pane.
4. Select the CUSTOMER table from the Available Tables and click Add.

   When you click Add, any tables related to the selected table are also added. In this example, the DISCOUNT_CODE table is also added. DISCOUNT_CODE table is greyed-out because it is referenced by CUSTOMER table and an entity class for it must be generated in order to generate the Customer entity class. To see how the greyed-out table is related to the selected table, you can hover your mouse over the table name in the Selected Tables pane.

5. Click Next.

   The wizard displays the selected table and any related tables. The wizard also displays the entity classes that will be created based on the selected tables. If you want to modify the name of the class that will be generated, you can type the name in the Class Name field.

6. Specify ejb as the package for the generated classes and click Finish.

When you click Finish, the IDE generates entity classes for the CUSTOMER table and the tables related to CUSTOMER table. If you expand the ejb source package in the Projects window you can see that the IDE created the Java classes Customer.java and DiscountCode.java. You can see that the IDE created only two classes, one for each of the database tables.

If you look at Customer.java in the Source Editor, you will notice that the @Entity annotation is used to declare the class an entity class. Other annotations provide additional information such as the database table and columns the entity class and its properties are mapped to.

You will also notice that much of the boilerplate code commonly found in entity beans is gone. Methods such as ejbRemove, setMessage, setSessionContext, ejbActivate, and ejbPassivate are no longer needed in your entity class in Java EE 5.

Coding the Servlet

We now need to add a servlet to our web application. Instead of adding resource creation and lookup code to our servlet, with Java EE 5 we can use resource injection to move that work to the container. We can use annotations to inject resources directly into our servlet, and the container will manage the creation and lookup of the requested resource. In this case, we want to use an entity manager as specified in our persistence unit.

1. Right-click the project node in the Projects window and choose New > Servlet.
2. In the New Servlet wizard, name the servlet CustomerDetails and put the servlet into a package named web. Click Finish. When you click Finish, CustomerDetails.java opens in the Source Editor.
3. In the Source Editor, right-click in CustomerDetails.java and choose Persistence > Use Entity Manager to inject the PersistenceContext in the class. The IDE adds the following annotation that specifies the persistence unit used by the servlet. The annotation is added above the class declaration.

       
     @PersistenceContext(name = "persistence/LogicalName", unitName = "CustomerBookPU")
                       

   The IDE also adds the following annotation injecting a resource for managing transaction boundaries:

     @Resource
     private javax.transaction.UserTransaction utx;

   If you expand the editor fold you can see that the IDE adds the following default code to the servlet:

     public void persist(Object object) {
         try {
             Context ctx = (Context) new InitialContext().lookup("java:comp/env");
             utx.begin();
             EntityManager em =  (EntityManager) ctx.lookup("persistence/LogicalName");
             em.persist(object);    
             utx.commit();
         } catch(Exception e) {
             Logger.getLogger(getClass().getName()).log(Level.SEVERE,"exception caught", e);
             throw new RuntimeException(e);
         }
     }

   This code looks up the persistence unit defined by @PersistenceContext and an instance of the entity manager.

4. In CustomerDetails.java, modify the generated lookup code shown above to refer to our entity object. When you are finished, the modified code should look like the following (the code shown in bold indicates the changed lines):

     public Customer findByID(Integer customerNr) {
           Customer customer = null;
           try {
               Context ctx = (Context) new InitialContext().lookup("java:comp/env");
               EntityManager em =  (EntityManager) ctx.lookup("persistence/LogicalName");
               utx.begin();
               customer = em.find(Customer.class, customerNr);
               utx.commit();
           } catch(Exception e) {
               Logger.getLogger(getClass().getName()).log(Level.SEVERE,"exception caught", e);
               throw new RuntimeException(e);
           }
           return customer;
       }              
                   

5. Uncomment the code in the processRequest method and add the following code in bold:

       protected void processRequest(HttpServletRequest request, HttpServletResponse response)
           throws ServletException, IOException {
           response.setContentType("text/html;charset=UTF-8");
           PrintWriter out = response.getWriter();
           out.println("<html>");
           out.println("<head>");
           out.println("<title>Servlet CustomerDetails</title>");
           out.println("</head>");
           out.println("<body>");
           out.println("<h1>Search Customer Information</h1>");
           String customerNr = request.getParameter("customer_nr");
           if((customerNr != null) && !(customerNr.equals(""))) {
   
               Customer customer = findByID(new Integer(customerNr));
               if(customer != null){
                   out.println("Customer's info for nr. " + customerNr + ": " + customer.getName());
               }else{
                   out.println("Customer not found.");
               }
           }
           out.println("<form>");
           out.println("Customer number: <input type='text' name='customer_nr' />");
           out.println("<input type=submit value=Select />");
           out.println("</form>");        
           out.println("</body>");
           out.println("</html>");
           out.close();
       }
                       

6. Press Alt-Shift-F to generate any missing import statements.

Summary

In this exercise, you built the CustomerBook application using Java EE 5 technology. You then deployed the project and tested the web application.