Using Hibernate with the Java Persistence API

If you are using the Java Persistence API you can choose the persistence provider that you want to use in your application. The GlassFish application server ships with Oracles's Toplink persistence provider, but you can easily configure your application to use the Hibernate persistence provider and quickly develop an application that accesses a database with the Java Persistence API.

Before starting this tutorial you may want to familiarize yourself with the following documents:

• Hibernate documentation at hibernate.org.
• Introduction to the JavaServer Faces Framework
• Generating a JavaServer Faces CRUD Application from a Database

Contents

• Creating the Web Application Project
• Creating the Entity Classes and Persistence Unit
• Creating the JSF Pages
• Testing the Web Application

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	6.5 Java
Java Development Kit (JDK)	version 6 or version 5
GlassFish Application Server	V2

Note. Before you start you need to register the application server with the IDE. If the application server is not registered in the IDE, register it by choosing Tools > Servers and clicking the Add Server button. You can see all registered application servers by opening the Services window and expanding the Servers node.

Creating the Web Application Project

In this exercise you will create a simple web application project to access the sample database. The application will use a JSF web interface for viewing and modifying the data so you will specify the JSF framework when you create the project.

1. Choose File > New Project (Ctrl-Shift-N). Select Web Application from the Java Web category.
2. Type HibernateApp for the Project Name and specify a location.
3. Deselect the Use Dedicated Folder option, if selected.
   For this tutorial there is little reason to copy project libraries to a dedicated folder because you will not need to share libraries with other users.
   Click Next. Click Next.
4. Set the server to GlassFish and the Java EE version to Java EE 5. Click Next.
5. Select the JavaServer Faces framework (NOT Visual Web JavaServer Faces). Click Finish.

When you click Finish the IDE creates the project and opens welcomeJSF.jsp in the editor.

Creating the Entity Classes and Persistence Unit

You now use the Entity Classes from Database wizard to create entity classes based on tables in the bundled sample database. The sample database is a JavaDB database, but you can use the wizard to quickly generate entity classes from any supported database if the database connection is registered with the IDE.

When you create the entity classes in the wizard you will also create a persistence unit where you specify how the entities are managed. The IDE includes support for Hibernate and Hibernate is listed as one of the persistence provider options. When you choose Hibernate as the persistence provider the IDE automatically adds the required Hibernate libraries to the project.

1. In the Projects window, right-click the project node and choose New > Entity Classes from Database. In the Data Source drop-down, select the jdbc/sample database. If prompted for a user name and password, use app and app. Select the CUSTOMER table from the list, click Add and then click Next.
2. Leave the tables and class names as their default, and type hibernatesample.db for the Package.
3. Click the Create Persistence Unit button.
4. Choose Hibernate as the Persistence Provider, and select None as the table generation strategy. Keep the default Persistence Unit Name. Click Create to close the dialog box.
   

   Click Next in the wizard.

5. Select eager from the Association Fetch drop down list.
6. Select java.util.Set from the Collection Type drop down list. Click Finish.
   

Note. At the time of writing, the Hibernate JPA persistence provider has some known issues that can cause problems in web applications such as JavaServer Faces applications. While not specific to NetBeans, these issues can be worked around by choosing eager as the association fetch value and java.util.Set as the collection type in the Mapping Options pane. If you use the Hibernate JPA persistence provider and choose default or lazy as the association fetch value in the Mapping Options pane, an org.hibernate.LazyInitializationException exception can occur at runtime. If you choose an association fetch value of eager and you do not also choose java.util.Set as the collection type, an org.hibernate.HibernateException can occur (with the message "cannot simultaneously fetch multiple bags") at runtime. These issues pertain to the Hibernate JPA persistence provider and not to the default persistence provider.

When you click Finish the IDE creates an entity class for each of the selected tables and creates persistence.xml under the Configuration Files node. You can open persistence.xml to view the details for the persistence unit.

When you choose Hibernate as the persistence provider, the IDE also adds the Hibernate libraries to the project. You can expand the Libraries node in the Projects window to view the Hibernate libraries that the IDE added to the project.

You can modify persistence.xml to add some Hibernate-specific properties.

1. Double-click persistence.xml to open the file in the editor and click the XML button at the top of the editor to switch to the XML view.
2. Modify the XML to add the following property.
   

     <persistence-unit name="HibernateApp" transaction-type="JTA">
       <provider>org.hibernate.ejb.HibernatePersistence</provider>
       <jta-data-source>jdbc/sample</jta-data-source>
       <properties>
           <property name="hibernate.show_sql" value="true" />
       </properties>
     </persistence-unit>
   </persistence>

   This property causes all SQL statements to be printed to the application server's log file.

3. Save your changes.

Creating the JSF Pages

You can now use the JSF JPA CRUD wizard to quickly generate JSF pages for displaying and modifying the data. In the wizard you select the entity classes and for each entity class the wizard will generate the following:

• a JPA controller class
• a JSF controller class
• a JSF converter class
• a directory containing four JSP files (Detail.jsp, Edit.jsp, List.jsp, New.jsp)
• managed bean elements, converter elements and navigation rules for the class in faces-config.xml

The wizard also automatically generates exception classes and utility classes that are used by the generated classes.

1. Right-click the project node and choose New > JSF Pages from Entity Classes.
2. Click Add All to add the Customer and DiscountCode classes to the list of selected classes. Click Next.
3. Type hibernatesample.db for the JPA Controller Package.
4. Type hibernatesample.jsf for the JSF Classes Package. Click Finish.

When you click Finish, the IDE creates the JPA controller classes for each entity class in the hibernatesample.db package. Each controller class handles the operations for the corresponding entity class, including creating, editing, and destroying instances of the entity class via the Java Persistence API. The IDE generated exception classes in the hibernatesample.db.exceptions package to handle exceptions thrown by the JPA controller classes.

For each entity class the IDE also created JSF converter and controller classes in the hibernatesample.jsf package. Each JSF converter class implements the javax.faces.convert.Converter interface defined by JavaServer Faces and performs the work of converting instances of the corresponding entity class to String objects and vice versa. The IDE generated three utility classes in the hibernatesample.jsf.util package containing the general JSF logic used by the JSF controllers.

If you expand the Web Pages node, you can see that the IDE generated a folder for each of the entity classes. Each folder contains the files Detail.jsp, Edit.jsp, List.jsp and New.jsp. The IDE also modified welcomeJSF.jsp to insert links to each of the List.jsp pages.

If you expand the Configuration Files node and open faces-config.xml in the XML editor, you can see that the IDE inserted the managed-bean and converter elements for each of the controller and converter classes. The IDE also inserted a navigation-rule element for each JSP, indicating the logical outcome that causes the application to navigate to that JSP.

After creating the JSF pages and modifying the code in the controller classes, you should be able to run and test the application.

Testing the Project

Now we need to run the project to test if the application is functioning correctly.

1. Right-click the project and choose Run Project. The IDE starts the application server, builds and deploys the application, and shows welcomeJSF.jsp in the external web browser.
2. Click the Show All Customer Items link and you should see the following web page:
   
3. Use the New Customer link to create a customer. Then check the server log by right-clicking the application server node in the Services window and choosing View Server Log. The SQL for creating the customer should be listed in the server log.

Next Steps

For more information about using NetBeans IDE 6.5 to develop web applications using Hibernate and the Java Persistence API, see the following resources:

• Java Java Web Application Learning Trail
• EJB & Web Service Applications Learning Trail
• Using Hibernate in a Visual Web JSF Application
• Generating a JavaServer Faces CRUD Application from a Database

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join the mailing list.