The following class is a data object, a POJO, which represents a record of a particular genre of fictional books that have been popular for over 100 years. Some books from this particular genre about spying, intergovernmental agencies, and other forms of esoteric investigations, have been turned into motion-picture and television productions. The class SpyThriller, which contains an identity number, the writer of the book, the year it was published, and of course the title, is as follows:

package je7hb.basic.jpa;

public class SpyThriller {
  private long id;
  private String writer;
  private int year;
  private String title;
  
  public SpyThriller() {}
  
  public SpyThriller(String writer, int year, String title) {
    this.writer = writer;
    this.year = year;
    this.title = title;
    }
  
  public long getId() {return id;}
  public void setId(long id) {this.id = id;}
  
  public String getWriter() {return writer;}
  public void setWriter(String writer) {this.writer = writer;}
  
  public int getYear() {return year;}
  public void setYear(int year) {this.year = year;}
  
  public String getTitle() {return title;}
  public void setTitle(String title) {this.title = title;}
  
  // toString() method omitted
  }

So far there is nothing special to see here in the SpyThriller bean. These are the usual pair methods for fulfilling the constraints of a valid JavaBean object that has properties. It is important to note that we can access each property of this Java bean through the getter and setter methods.

Note that we have the constructor that can populate all of the fields of the bean, except for the identity property, which is called id. We will see in this section, why this was written this way.

Let us now transform this bean into a JPA entity bean with some annotations. The second version of our bean is as follows:

The SpyThriller bean with some annotations that transforms it into a working entity bean is as follows:

package je7hb.basic.jpa;
import javax.persistence.*;

@Entity
public class SpyThriller {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;
  private String writer;
  private int year;
  private String title;
  
  public SpyThriller() {}
  
  // Full constructor omitted
  
  public long getId() {return id;}
  public void setId(long id) {this.id = id;}
  
  public String getWriter() {return writer;}
  public void setWriter(String writer) {this.writer = writer;}
  
  public int getYear() {return year;}
  public void setYear(int year) {this.year = year;}
  
  public String getTitle() {return title;}
  public void setTitle(String title) {this.title = title;}
  
  // toString() method omitted
  }

First, we applied the annotation @javax.entity.Entity to the class itself, which denotes that the bean is a persistent capable object suitable for enhancement.

Second, we also make sure that this POJO is serializable and it can be detached from the persistent session by extending the java.io.Serializable marker interface. This means that the SpyThriller entity bean can also be sent across a network, for example, using a session bean with a remote business interface.

Third, we applied the id property with two new annotations: @javax.entity.Id and @javax.entity.GeneratedValue.

The annotation @Id denotes a Java property to be the primary key of the entity bean. In particular, every entity must have a primary key. The primary key of the entity is the unique identifier for the bean inside the database.

The annotation @GeneratedValue denotes the entity has a unique value that is generated by the database. There are different strategies for creating the database unique identifier, and in the preceding example, strategy=AUTO means that we are relying on the database to explicitly generate this identifier for our SpyThriller bean.

So, when we first insert a SpyThriller bean into the database, the identifier id will be automatically generated for us by the underlying database, and the bean's id property will be populated with this value by the JPA provider. This is the reason why the identifier id was not specified as part of the bean's constructor arguments.

In SpyThriller, all of the properties, the fields of the bean, are by default persistent capable, and they will be stored inside the database. What happens if we do not want this persistence for a particular field? We can apply to the field an annotation @javax.entity.Transient. Another version of our entity bean so far is as follows:

@Entity
public class SpyThriller extends java.io.Serializable {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;
  private String writer;
  private int year;
  private String title;
  
  @Transient
  private String secretCode;
  
  public SpyThriller() {}
  // Same code as before
  }

In the preceding code fragment, the field secretCode is not persistent capable, and it will never be stored inside the database because it is annotated with @Transient.

Let us summarize the annotations so far as follows:

The JPA specification is designed to allow programming by convention-over-configuration in order to ease software development. This means there are reasonable defaults; it follows the principle of least astonishment.

There are more annotations that the last example code hid from the naked eye. Let us look at an expanded definition of entity bean as follows:

import javax.persistence.*;

@Entity(name = "SpyThriller")
@Table(name = "SPY_THRILLER_BOOK")
public class SpyThriller extends Serializable {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  @Column(name = "BOOK_ID", table = "THRILLER_BOOK", unique = true, nullable = false, insertable = true, updatable = true)
  private long id;
  @Basic(fetch = FetchType.EAGER)
  @Column(name = "AUTHORS", nullable = false)
  private String writer;
  @Column(name = "BOOK_YEAR", nullable = false)
  private int year;
  @Column(name = "TITLE", nullable = false)
  private String title;
  
  public SpyThriller() {}
  }

publicenumFetchType {LAZY, EAGER};
@Target({METHOD, FIELD}) @Retention(RUNTIME)

Here is an entity bean class for a train system, Train, which is a very simple data object. It has three field variables standing for the source and target locations, and a time that is formatted as a long primitive with the pattern: yyyyMMdd.

package je7hb.basic.jpa;
import javax.persistence.*;
import java.io.Serializable;

@Entity
public class Train implements Serializable {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;
  
  @Column(name = "FROM_LOC", nullable = false)
  private String from;
  
  @Column(name = "TO_LOC", nullable = false)
  private String to;
  
  /** Pattern format yyyyMMdd */
  @Column(name = "TRAIN_DATE")
  private int trainDate;
  
  public Train() {this(null,null,0);}
  public Train(String from, String to, int trainDate) {
    this.from = from;
    this.to = to;
    this.trainDate = trainDate;
    }
  
  public long getId() {return id;}
  public void setId(long id) {this.id = id;}
  
  public String getFrom() {return from;}
  public void setFrom(String fromLoc) {
    this.from = fromLoc;
    }
  
  public String getTo() {return to;}
  public void setTo(String toLoc) {this.to = toLoc;}
  
  public int getTrainDate() {return trainDate;}
  public void setTrainDate(int trainDate) {
    this.trainDate = trainDate;
    }
  // toString() method omitted
  }

The Train entity class is annotated on the field variables: id, from, to, and trainDate. We have used the @Column annotation to explicitly specify the target database column names, because the field variables named are mostly reserved keywords in the underlying database.

The same entity class annotated on the getter and setter methods is as follows:

package je7hb.basic.jpa;

import javax.persistence.*;
import java.io.Serializable;

@Entity
public class Train implements Serializable {
  private long id;
  private String from;
  private String to;
  private int trainDate;
  public Train2() {this(null,null,0);}
  
  public Train(String from, String to, int trainDate) {
    this.from = from;
    this.to = to;
    this.trainDate = trainDate;
    }
  
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  public long getId() {return id;}
  public void setId(long id) {this.id = id;}
  
  @Column(name = "FROM_LOC", nullable = false)
  public String getFrom() {return from;}
  public void setFrom(String fromLoc) {
    this.from = fromLoc;
    }
  
  @Column(name = "TO_LOC", nullable = false)
  public String getTo() {return to;}
  public void setTo(String toLoc) {this.to = toLoc;}
  
  /** Pattern format yyyyMMdd */
  @Column(name = "TRAIN_DATE")
  public int getTrainDate() {return trainDate;}
  public void setTrainDate(int trainDate) {
    this.trainDate = trainDate;
    }
  
  // toString() method omitted
  }

Moving the annotations to the getter and setter methods has one advantage in that it allows the LAZY instantiation of the property. Let us suppose the Train entity had an expensive or large-dependent entity bean that implied significant performance cost, then annotating the getter and setter properties may be useful.

Developer, the bean provider, must ensure that there is no public access to the fields of the instance variables. In particular, the clients of entity bean and related entity beans must always call the getter methods in to access an entity's properties.

For entity beans that are standalone, the decision to annotate the field variables versus the accessor methods can be trivial. When entity bean is part of the object hierarchy, then choosing one style or the other is very important. If you choose the field instance for the root class of the hierarchy, you are advised to follow it for all the subentity bean classes. Do not mix the two styles.

A table of cost and benefits of annotating the instance variables versus the property accessor methods is as follows:

There are two styles to annotate JPA and entity beans. Injecting into the bean getter and setter methods, obviously, provides a way of intercepting the incoming argument, and also computing a result or triggering some other action. On the other hand, we recommend that entities should be kept relatively simple, and serious business logic should go into either Bean Validation or service endpoints.