TopLink JPA: How-To Define an Entity Using Annotations

Version: 5/12/06

Introduction

In the Java Persistence API (JPA) a persistent class is referred to as an entity. An entity is a plain old Java object (POJO) class that is mapped to the database and configured for usage through JPA using annotations and/or XML.

This How-To document demonstrates the minimal configuration of a JPA entity using annotations.

In JPA, an entity class possesses the following characteristics:

Configuration Using Field Annotations

The entity class is a plain Java class that is annotated with @Entity to mark it as an entity, as the following example shows:

@Entity
@Table(name = "EMP")
public class Employee implements java.io.Serializable {

  @Id
  @Column(name = "EMP_NO")
  private int empNo;

  @Basic
  @Column(name = "NAME")
  private String name;

  @Basic
  @Column(name = "SALARY")
  private double salary;

  ...

}

The @ Table annotation is used to specify the table to which this entity class maps. This annotation is optional and is only required when the default table name to be assumed by JPA does not match the relational schema. In the preceding example, the @ Table annotation is required, because the table name ( EMP) is different from the assumed default ( EMPLOYEE). The @ Id annotation is used to mark the empNo field as the primary key of the entity for every entity must have its primary key fields indicated. If compound primary key fields were required, you could specify a primary key class using either @ IdClass or @ EmbeddedId annotation.

Configuration by Exception

In the Employee example, because the employee name and salary fields match default JPA column names NAME and SALARY, there is no need for @ Column annotations on the Employee entity. Only the empNo field requires a @ Column annotation as it differs from the default JPA name EMPNO. Because of the defaulting, you only need to annotate a field (or properties) for which the default is wrong. This type of specification is known as configuration by exception. The advantage of this approach is clear when you compare the fully annotated Employee class from the preceding example with the minimally annotated one from the following example--the configuration by exception reduces the amount of work you need to do.

@Entity
@Table(name = "EMP")
public class Employee implements java.io.Serializable {

  @Id
  @Column(name = "EMP_NO")
  private int empNo;
  private String name;
  private double salary;

  ...
}

Configuration Entity Using Property Annotations

You can also specify your mappings on the getter method for the property (the get part of a get/set pair that imply the existence of a field). You could use this approach when the internal structure of the entity does not allow the fields to hold the configuration annotations, as the following example demonstrates:

@Entity
public class Employee implements java.io.Serializable {

  private int empNo;
  private String name;
  private double salary;

  @Id
  @Column(name = "EMP_NO")
  public int getId() {
   &nbspreturn empNo;
  }


  public void setId(int id) {
   &nbspthis.empNo = id;
  }

  ...
}

Summary

This how-to page demonstrated the basics of configuring an entity using annotations. See the TopLink JPA Annotations Reference Guide for a complete list of JPA annotations, as well as the ways to use them.


 
 

 

Left Curve
Popular Downloads
Right Curve
Untitled Document