This document takes you through the basics of developing a web application using Java™ Persistence. The Java Persistence API was introduced as part of the Java EE 5 platform. In this tutorial you will create a simple web application project. Though we will use persistence in our project, the Java Persistence API enables us to use persistence without needing to create an EJB module.
Using Java Persistence in your project greatly simplifies application development by removing the need for configuring deployment descriptors to provide object-relational mapping information for persistent fields or properties. Instead, you can use annotations to define these properties directly in a simple Java class.
Entity persistence is managed by the EntityManager API. The EntityManager API handles the persistence context, and each persistence context is a group of entity instances. When developing your application, you can use annotations in your class to specify the persistent context instance of your entity instances. The life-cycle of the entity instances is then handled by the container.
This document uses the NetBeans IDE 5.5 release.
Expected duration: 15 minutes
This document assumes you have some basic knowledge of, or programming experience with, the following technologies:
For this tutorial you need to have the following software installed on your computer:
For this tutorial you need to register a local instance of Sun Java System Application Server with the IDE.
The goal of this exercise is to create the ZooApp web application project. This application will take advantage of features of the new Java Persistence model. One of the features is that entity objects can be simple Java classes, so they no longer need to be placed in an EJB module and packaged in an EAR file. This means that we can create our entity classes directly inside a web application.
In this exercise you created a Java EE 5 web application which will contain the entity classes.
In this exercise we will create a persistence unit to tell the container which entity classes are to be managed by the entity manager, and also the datasource used by those entities.
We create the persistence unit by defining its properties in persistence.xml which we will create in our web module. After specifying the name of our persistence unit, we will specify the persistence provider, which contains the APIs the container will use for managing entity instances. We also need to specify the data source and our table generation strategy. We will create the persistence unit using the New Persistence Unit wizard.
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.
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.
The default data source jdbc/sample is used to connect to the Java DB database that is bundled with the Sun Java System Application Server.
When you click Finish, the IDE creates persistence.xml and opens it in the Source Editor in Design view. You can click XML in the toolbar of the Source Editor to see the XML for persistence.xml. This file contains all the information the Java EE 5 container needs to manage the entities and persistence of our application.
In this exercise, you created a persistence unit to specify the datasource, the entity classes to be persisted and the entity manager that the container will use to manage the life-cycle of the entities.
In this exercise we will create two entity classes, Animal.java and Pavilion.java, that represent the tables in the relational database we want to create. We will also define some fields in the classes to represent the data. The Java Persistence specification allows us to use annotations to provide information to the container about the fields, such as object-relational mapping information.
First we will create the entity class Animal. This class represents the ANIMAL table in our database. When you create the entity class, the IDE adds the @Entity annotation to define the class as an entity class. After we create the class, we will create fields in the class to represent the data that we want in our table, and use annotations to provide additional information about some of the fields.
Each entity class must have a primary key. When you create the entity class, the IDE adds the @Id annotation to declare which field to use as the primary key. The IDE also adds the @Generated annotation to specify the key generation strategy for the primary Id.
To create the Animal class, do the following:
When you click Finish, the new entity class Animal.java opens in the Source Editor. In the Source Editor, do the following:
String name; String kind; String weight; Pavilion pavilion;
@Column(name="animalName")
@ManyToOne
In the next step we will create the Pavilion entity class.
We now will create the entity class Pavilion representing the PAVILION table in our database. We will again use annotations in our class to specify the object-relational mapping of some of our fields. To create the Pavilion class, do the following:
When you click Finish, the new entity class Pavilion.java opens in the Source Editor. In the Source Editor, do the following:
String name; String address; Collection <Animal> animals;
@Column(name="pavilionName")
@OneToMany(mappedBy="pavilion")
In this exercise, you created two entity classes and defined fields. You also used annotations to define the properties of some of the columns in the tables that will be generated when you deploy the application.
We now want to create some simple web pages to see if our database tables were created and if we can add data. We will add Java Server Faces (JSF) pages to the application and use the JSF Pages from Entity Class wizard to quickly create a simple web interface.
When you click Finish, the IDE generates the required JavaServer Faces files so that we can run and test our ZooApp.
In this exercise we will deploy our ZooApp web application project and test our application.
When you click Run, a page opens in your browser with a menu enabling you to see a list of the pavilions and animals.
You can also add, edit or delete the data for animals and pavilions.
In this exercise, you built the ZooApp web application you developed for the Java EE 5 platform. You then deployed and tested the ZooApp web application.
The following are some of the problems you may encounter when creating your project.
When using the wizard to create JSF pages from an entity class, you may see the following error message in the wizard:
This wizard can only be used in a web project with JSF support.
If you see this message you need to check that the Java Server Faces framework has been added to the project properties. You can add Java Server Faces support to your web project by doing the following:
After adding the JSF Framework to the project properties, you should be able to create the JSF pages using the wizard.
For more information about using NetBeans IDE 5.5 to develop Java EE applications, see the following resources:
You can find more information about using Java Persistence in the Java EE 5 Tutorial.
To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join the nbj2ee mailing list.