Show TOC

Background documentationEntities Locate this document in the navigation structure

 

JPA is an API for storing lightweight Java objects called “entities” in a relational database.

An “entity” is a regular Java object (also referred to as “Plain Old Java Object” or POJO) with mapping to a relational database. To make a class an entity, you therefore have to:

  • Declare that a class is an entity explicitly to distinguish it from the other regular Java objects that you use within your application.

  • Map the entity to a database table.

As these specifics can be considered as metadata for the entity class, JPA relies on the Java SE 5 standard technique for providing metadata: annotations.

Note Note

JPA also allows the object/relational mapping information to be provided in XML format in a mapping file. However, annotations are easier to understand and work with. Hence, this documentation is written in terms of annotations only. If not explicitly mentioned otherwise, XML can be used instead.

End of the note.

For more information about annotations, refer to the JDK 5.0 documentation at http://java.sun.com/.

Implementation of Entity Classes

To convert a regular Java object to a valid entity, you use two annotations from the javax.persistence package:

@Entity - to declare the class as an entity. The @Entity annotation is placed at the class definition.

@Id - to declare the unique identifier corresponding to the primary key in the database. The @Id annotation can be placed either at the definition of the field that serves as a unique identifier for the entity or, alternatively, at the corresponding getter method.

The JPA specification requires that entity classes:

  • Are annotated with the @Entity annotation.

  • Have one or more fields that form their unique identifier, that is, their primary key.

  • Have a public or protected nonargument constructor.

  • Are not final - no method or variable can be final.

  • Have private, package-private or protected instance variables that keep the persistent state and that may only be accessed by clients of the entity through its getter and setter methods or business methods.

  • Expose their persistent state to the Entity Manager (EM) through either the instance variables (field-based access) or through public or protected getter/setter methods (property-based access).

Note Note

The position of the @Id annotation determines the mechanism by which the JPA implementation accesses the entity. Depending on the type of access you choose, you annotate either fields or methods.

  • Field-based access

    If you place the @Id annotation at a field of a class, the JPA implementation reads data directly from and writes data to this field of the entity instance.

  • Property-based access

    If you place the @Id annotation at a getter method, the JPA implementation works with the getter and setter methods, ignoring any instance variables that may be available.

All examples in this documentation are using field access. Property access can be used instead, analogously.

End of the note.

Since JPA employs configuration by exception, the only mandatory annotations on an entity class are @Entity (to denote the class an entity class) and @Id (to denote the unique identifier field).

Syntax Syntax

  1. @Entity
    public class Employee {
    	@Id
    	private int employeeId;
    	private String name;
    	private String eMail;
    	private BigDecimal salary;
    }
End of the code.

You are free to define the entity according to your data model, including inheritance and polymorphism, without major restrictions being imposed by the persistence framework.

Example

This example is based on a simple employee data model and describes how to create the entity.

To start, you can use the simple Java class Employee. The class defines two fields, id and name, and provides the corresponding getter and setter methods according to the JavaBeans naming conventions. As mentioned, JPA requires you to provide a public constructor with no arguments. You can also add other constructors. To convert the class into an entity, you import the javax.persistence package and add the @Entity and @Id annotations. In this example, the field id serves as a unique identifier and field-based access is chosen, so that finally the entity looks as follows:

Syntax Syntax

  1. import javax.persistence.Entity;
    import javax.persistence.Id;
    
    @Entity
    public class Employee {
    	@Id
    	private int id;
    	rivate String name;
    }
    
    public Employee() {
    }
    
    public Employee(int id) {
    	this.id = id;
    }
    
    public int getId() {
    	return id;
    }
    
    public void setId(int id) {
    	this.id = id;
    }
    
    public String getName() {
    	return name;
    }
    
    public void setName(String name) {
    	this.name = name;
    }
    }
End of the code.