TopLink JPA: How-To Define an Entity Using Annotations

Version: 5/12/06

Introduction
Configuration using Field Annotations
Configuration by Exception
Configuration using Property Annotations
Summary

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:

it is a plain java class (POJO)--it does not need to implement any interfaces or extend any classes;
it must have its identity defined--a unique field or a set of fields typically mapping to the primary key of the primary table to which this entity maps;
it can have configuration metadata specified with Java annotations and/or XML.

Configuration Using Field Annotations

The entity class is a plain Java class that is annotated with @Entityto 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() {
    return empNo;
  }

  public void setId(int id) {
    this.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.