Creating the Java Persistence API Entity

The Java Persistence API allows you to create and use Java programming language classes that represent data in a database table. A Java Persistence API entity is a lightweight, persistent Java programming language object that represents data in a data store. Entities can be created, modified, and removed from the data store by calling the operations of the Java Persistence API entity manager. Entities, or the data encapsulated by the persistent fields or properties of a entity, can be queried using the Java Persistence Query Language (JPQL), a language similar to SQL that operates on entities.

In firstcup, there is a single entity that defines one query.

Creating the FirstcupUser Entity Class

The FirstcupUser Java Persistence API entity represents a particular firstcup user, and stores the user's birthday and the difference in age between the user and Duke. FirstcupUser also defines a Java Persistence API query used to calculate the average age difference of all users.

1. With the firstcup project selected in the Projects pane, select File -> New File.

2. Under Categories select Persistence, then under File Types select Entity Class, and click Next.

3. Enter FirstcupUser under Class Name and firstcup.entity under Package.

4. Click Create Persistence Unit, select jdbc/__default under Data Source, and click Create.

5. Click Finish.

Add Properties to the FirstcupUser Entity

Create the FirstcupUser entity's two properties: birthday, of type java.util.Calendar; and ageDifference, of type int.

The birthday property must be annotated with the javax.persistence.Temporal annotation to mark the property as date field in the underlying database table. All persistent fields or properties of type java.util.Calendar or java.util.Date must be annotated with @Temporal.

1. Right-click the editor window, select Insert Code, then Add Property.

2. In the Add Property dialog, enter birthday under Name, java.util.Calendar under Type, and click OK.

3. Click the error glyph next to the new birthday field and select Add @Temporal Annotation.

4. Right-click the editor window, select Insert Code, then Add Property.

5. In the Add Property dialog, enter ageDifference under Name, int under Type, and click OK.

Add a Named Query to the FirstcupUser Entity

Add a JPQL named query to the FirstcupUser entity that returns the mean average age difference of all firstcup users.

This query uses the AVG aggregate function to return the mean average of all the values of the ageDifference property of the FirstcupUser entities.

1. Directly before the class definition, paste in the following code:

   @NamedQuery(name="findAverageAgeDifferenceOfAllFirstcupUsers",
   query="SELECT AVG(u.ageDifference) FROM FirstcupUser u)

   The @NamedQuery annotation appears just before the class definition of the entity, and has two required attributes: name, with the unique name for this query; and query, the JPQL query definition.

Add a Business Method to DukesBirthdayBean that Gets the Average Age Difference of firstcup Users

Once the FirstcupUser entity is complete, add a business method to the DukesBirthdayBean session bean to call the named query that returns the average age difference of all users.

1. Double-click DukesBirthdayBean in the Projects Pane under Enterprise Beans.

2. Below the class definition, add a @PersistenceContext annotation and field of type EntityManager:

   @PersistenceContext
   private EntityManager em;

3. Right-click in the Editor window, select Insert Code, then Add Business Method.

4. In the Add Business Method dialog, enter getAverageAgeDifference under Name, set the Return Type to Double, and click OK.

5. Replace the body of the newly created getAverageAgeDifference method with the following code:

   public Double getAverageAgeDifference() {
       Double avgAgeDiff = (Double) 
           em.createNamedQuery("findAverageAgeDifferenceOfAllFirstcupUsers")
           .getSingleResult();
       logger.info("Average age difference is: " + avgAgeDiff);
       return avgAgeDiff; 
   }

   The named query in FirstcupUser is called by using the EntityManager's createNamedQuery method. Because this query returns a single number, the getSingleResult method is called on the returned Query object. The query returns a Double.

6. Select File -> Save.