The Programming Model

The Programming Model

Entities are plain Java classes in Java Persistence. You declare and allocate these bean classes just as you would any other plain Java object. You interact with the entity manager service to persist, update, remove, locate, and query for entity beans. The entity manager service is responsible for automatically managing the entity beans' state. This service takes care of enrolling the entity bean in transactions and persisting its state to the database. Chapter 5 discussed the entity manager in great detail.

The Customer Bean

The Customer bean is a simple entity bean that models the concept of a cruise customer or passenger, but its design and use are applicable across many commercial domains. Java Persistence is all about relational databases. This section introduces the Customer entity's design and implementation. This entity will be refactored in many different ways throughout this chapter so that we can show you the multiple ways in which you can map the Customer entity to a relational database.

The Bean Class

The Customer bean class is a plain Java object that you map to your relational database. It has fields that hold state and, optionally, it has getter and setter methods to access this state. It must have, at minimum, a no-argument constructor:

package com.titan.domain;

import javax.persistence.*;

@Entity
public class Customer implements java.io.Serializable {
   private long id;
   private String firstName;
   private String lastName;

   @Id
   public long getId( ) { return id; }
   public void setId(long id) { this.id = id; }

   public String getFirstName( ) { return firstName; }
   public void setFirstName(String firstName) { this.firstName = firstName; }

   public String getLastName( ) { return lastName; }
   public void setLastName(String lastName) { this.lastName = lastName; }
}

Java Persistence requires only two pieces of metadata when you are creating a persistent class: the @javax.persistence.Entity annotation denotes that the class should be mapped to your database, and the @javax.persistence.Id annotation marks which property in your class will be used as the primary key. The persistence provider will assume that all other properties in your class will map to a column of the same name and of the same type. The table name will default to the unqualified name of the bean class. Here is the table definition the persistence provider is assuming you are mapping to:

create table Customer(
   id long primary key not null,
   firstName VARCHAR(255),
   lastName VARCHAR(255)
);

The @javax.persistence.Entity annotation tells the persistence provider that your class can be persisted:

package javax.persistence;

@Target(TYPE) @Retention(RUNTIME)
public @interface Entity
{
   String name( ) default "";
}

The @Entity annotation has one name( ) attribute. This name is used to reference the entity within an EJB QL expression. If you do not provide a value for this attribute, the name defaults to the unqualified name of the bean class.

How you apply the @javax.persistence.Id annotation determines whether you will use the Java bean style for declaring your persistent properties or whether you will use Java fields. If you place the @Id annotation on a getter method, as done in this example, then you must apply any other mapping annotations on getter and setter methods in the class. The provider will also assume that any other getter and setter methods in your class represent persistent properties and will automatically map them based on their base name and type.

@Entity
public class Customer implements java.io.Serializable {
@Id
   private long id;
   private String firstName;
   private String lastName;

   public long getId( ) { return id; }
   public void setId(long id) { this.id = id; }

   public String getFirstName( ) { return firstName; }
   public void setFirstName(String firstName) { this.firstName = firstName; }

   public String getLastName( ) { return lastName; }
   public void setLastName(String lastName) { this.lastName = lastName; }
}

Here, we have placed the @Id annotation on a member field of the class. The persistence provider will also assume that any other member fields of the class are also persistent properties and will automatically map them based on their base name and type. Any mapping annotations must be placed on member fields in this example, not on getter or setter methods. Here, we are really defining the access type that is, whether our relational mappings are defined on the fields or the methods of a class.

XML Mapping File

If you do not want to use annotations to identify and map your entity beans, you can alternatively use an XML mapping file to declare this metadata. By default, the persistence provider will look in the META-INF directory for a file named orm.xml, or you can declare the mapping file in the <mapping-file> element in the persistence.xml deployment descriptor. Here's how the Customer entity mapping would look in XML:

<entity-mappings>
   <entity class="com.titan.domain.Customer" access="PROPERTY">
      <attributes>
         <id name="id"/>
      </attributes>
   </entity>
</entity-mappings>

The mapping file has a top element of <entity-mappings>. The <entity> element defines the entity class and access type: PROPERTY or FIELD . The <id> element is a subelement of the <attributes> element and defines what attribute your primary key is. Like annotated classes, the persistence provider will assume that any other property in your class is a persistent property, and you do not have to explicitly define them.