1. Choose File > New Project (Ctrl-Shift-N). Select Web Application from the Web category and click Next.
2. Type ZooApp for the project name and set the project 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.
4. Set the server to GlassFish and set the Java EE Version to Java EE 5. Click Next.
5. Select the JavaServer Faces checkbox and click Finish.

Summary

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

Creating a Persistence Unit

1. Right-click the ZooApp web application node in the Projects window and choose New > Other to open the New File wizard.
2. From the Persistence category, select Persistence Unit and click Next.
3. Keep the default Persistence Unit Name.
4. For the Persistence Provider, use TopLink (default).

   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. For the Data Source, use the default data source jdbc/sample.

   The data source jdbc/sample is already configured to connect to the Java DB database that is bundled with the GlassFish application server. You can use another database if you create a data source for the database.

6. Check that the persistence unit is using the Java Transaction API and that the Table Generation Strategy is set to Create so that the tables based on our entity classes are created when the application is deployed.
7. Click Finish.

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 the application.

Summary

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.

Creating the Animal and Pavilion Entity Class

First you will create the entity classes Animal and Pavilion. The classes represent the ANIMAL and PAVILION tables in the database.

When you create an entity class, the IDE adds the @Entity annotation to define the class as an entity class. After you create the class, you will create fields in the class to represent the data that you want in your 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 entity classes, do the following:

1. Right-click the ZooApp project node and choose New > Other.
2. From the Persistence category, select Entity Class and click Next.
3. Type Animal for the class name, entity for the package, and leave the Primary Key Type as Long. Click Finish.
4. Repeat the steps above to create the Pavilion class in the entity source package.

When you click Finish, the new entity classes open in the editor. If you expand the entity node under the Source Packages in the Projects window, you can see that the entity classes Animal and Pavilion are there.

Defining the Fields in the Animal Class

Open the Animal class in the editor and do the following:

1. Add the following field declarations (in bold) to the class:

   public class Animal implements Serializable {
   
       private static final long serialVersionUID = 1L;
       private Long id;
       private String name;
       private String kind;
       private String weight;
       private Pavilion pavilion;

2. Right-click in the Source Editor and choose Insert Code (Alt-Insert) and then select Getter and Setter to open the Generate Getters and Setters dialog box.
3. In the Generate Getters and Setters dialog box, select all the fields and click Generate.
   

   In the Generate Getters and Setters dialog box, you can use the Up arrow on the keyboard to move the selected item to the Animal item and then hit the Space bar to select all fields in Animal.

4. You now want to change the name of one of the columns that will be created in the Animal table so that the column is called animalName instead of name. You can use annotations to specify the name of the generated column by adding the following annotation above the name field declaration:

      @Column(name="animalName")
       private String name;

5. When you annotated the name field with the @Column annotation, the IDE displayed a warning in the left margin next to the class identifier. Click the warning icon in the margin and select Unify field access.
   

   When you click Unify field access, the IDE moves the @Id and @GeneratedValue annotations from the getId getter

   so that the annotations are now directly above the private Long id.
6. The pavilion column in our Animal table should also have a many-to-one relationship. You can do this using annotations by adding the following annotation above the pavilion declaration:

      @ManyToOne
       private Pavilion pavilion;

7. Press Alt-Shift-I to generate any necessary import statements for the class.
8. Save your changes.

In the next step we will define the fields in the Pavilion entity class.

Defining the Fields in the Pavilion Class

Open the Pavilion class in the editor and do the following:

1. Add the following field declarations (in bold) to the class:

   public class Pavilion implements Serializable {
   
       private static final long serialVersionUID = 1L;
       private Long id;
       private String name;
       private String address;
       private Collection <Animal> animals;

2. Add the following annotation above the name declaration to change the name of the generated column:

      @Column(name="pavilionName")
       private String name;

3. Add the following annotation above the animals collection to specify a One-to-Many relationship for the entity:

      @OneToMany(mappedBy="pavilion")
       private Collection <Animal> animals;

4. Right-click in the editor and choose Insert Code (Alt-Insert) and then select Getter and Setter.
5. In the Generate Getters and Setters dialog box, select all the fields and click Generate.
   
6. Click the warning icon in the margin and unify field access as you did for the Animal class.
7. Press Alt-Shift-I to generate any missing import statements.
8. Save your changes.

Summary

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.

Problem with New JSF Pages from Entity Class Wizard

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:

1. Right-click the web application node in the Projects window and select Properties.
2. Select Frameworks in the Categories pane of the Project Properties dialog box and then click Add.
3. In the Select Frameworks dialog box select Java Server Faces and click OK.
4. Click OK in the Project Properties dialog box to close the window.

After adding the JSF Framework to the project properties, you should be able to create the JSF pages using the wizard.

When Modifying Pavilion Data You Get IllegalArgumentException

If you see the following exception:

java.lang.IllegalArgumentException: Expected a child component type of UISelectItem/UISelectItems for component type javax.faces.SelectMany(animals). Found null.

the problem is probably caused by incorrect getter and setter methods for Collection <Animal> in the Pavilion class.

Make sure that the getters and setters for Collection <Animal> looks like the following:

public Collection<Animal> getAnimals() {
    return animals;
}

public void setAnimals(Collection<Animal> animals) {
    this.animals = animals;
}

If the getters and setters are not correct in your project, do the following:

1. Delete the Controller and Converter classes for the entity classes.
2. Delete the animal and pavilion directories under the Web Pages node in the Projects window.
3. Fix the getters and setters in the Pavilion entity class.
4. Use the JSF Pages from Entity Class wizard to regenerate the JSF pages and Controllers and Converter classes.