JPA Entities

An entity is persistence domain object which represents a table in relational database. Each instance of an entity corresponds to a row in the table. The instance variables (fields and/or JavaBean properties) of an entity correspond to columns of the table.

In this tutorial we will quickly go through basic aspects of using entities per JPA 2.1 specifications. Examples are also included using database H2 and JPA implementation Eclipse link.

Using @Entity

Each class which needs to be persisted in the database must be annotated with @Entity. @Entity has a 'name' element which is used in query and also for table name. By default Entity name defaults to unqualified name of the class. If multiple entity classes have same name (but in different packages), explicit names should be set using 'name' element. Every entity must also have an instance variable with @Id to specify a primary key.

@Entity
public class MyEntity {
  @Id
  private String id;
}

Entity - Table mapping using @Table

By default database table is mapped by the entity name (as stated above). If table and entity name cannot be same then we can use @Table (along with @Entity). The 'name' element of @Table annotation can specify the table name. This annotation also has other optional elements to specify things like database schema, catalog etc.

@Table(name = "exampleTable")
@Entity
public class MyEntity {
  @Id
  private String id;
}

Entity instance variables to column mapping

All instance variables of the entity class are mapped to individual columns of the table. By default table column name will be same as variable name.

@Entity
public class MyEntity {
  @Id
  private String id;
  private String myString;
  private int myInteger;
}

Specifying different column names by using @Column

If we need to map different column names to our entity instance variables then we will use @Column and specify it's 'name' element for the table's column name.

@Entity
public class ExampleEntity {
  @Id
  @Column(name = "example_id")
  private String id;
  @Column(name = "example_String")
  private String myString;
  @Column(name = "example_integer")
  private int myInteger;
}

@Column annotation has other optional elements to specify attributes like length, nullable, unique for the column.

Excluding entity variables

If we want to exclude any of entity variables from being mapped to a column and persisted in the table then we will use @Transient. We can also use transient keyword to exclude them. Also all 'static' fields are implicitly excluded.

In the following example only id, aFinalString, aVolatileString and anInstanceString are mapped.

@Entity
public class MyEntity {
  @Id
  private String id;
  @Transient
  private String myString;
  private transient int myInteger;
  private static String aStaticString;
  private final String aFinalString = "";
  private volatile String aVolatileString;
  private String anInstanceString;
}

final fields are not allowed

Final fields or final entity classes are not allowed. According to the specs:

The entity class must not be final. No methods or persistent instance variables of the entity class may be final.

The reason for this restriction is: a JPA implementation cannot set the field values loaded from the database if they are final. Some implementation (e.g. EclipseLink like in above example) can ignore this restriction and can use reflection to set final fields. We, however, should avoid that for portable application.

The difference between @Transient and transient

transient keyword is used to exclude variables from being serialized (saving to file or sending a copy remotely), whereas, @Transient is to exclude from being persisted in the database. Serialization can be considered a general way to save to a disk (that includes saving to database as well). A field with @Transient will be not be saved to the database but can be serialized. According to Specification:

All non-transient instance variables that are not annotated with the Transient annotation are persistent.

Mapping annotations (e.g. @Column) cannot be applied to the fields or properties that are declared @Transient, doing so will end up in exception during deployment/validation time.

No enum or interface allowed

The entity class must be top-level class (not inner/nested). An enum or interface cannot be an entity

Entity class constructor

The class must have a public or protected, no-argument constructor. The class may have other additional constructors.

Non final Entity class

The class must not be declared final. No persistent instance variables or corresponding methods must be declared final.

Implementing Serializable

The entity can optionally implement Serializable interface. This interface is needed when object must be replicated remotely, e.g. scenario like this.

Note that some of the above rules may be ignored by some implementations but we should stick to the specification to write a portable application.