Entities

Each entity class must be marked with the @Entity annotation and must be added to the persistence.xml file as explained here. The entity attributes, which in the end maps to database structure and properties, can then be set as explained in the following chapters.

Table

The table name can be specified using the @Table annotation.

@Entity
@Table(name = "table_name")
public class EntityClass {

If the annotation is omitted, a default table name is assigned by replacing each uppercase character with an underscore followed by the same character in the lowercase version, apart from the first character for which the underscore is avoided. For example, the above entity would have a default table name of "entity_class".

Columns

Simple columns are mapped to the fields of the entity by using the @Column annotation.

@Column(name = "first_name")
public String firstName;

@Column(name = "last_name")
public String lastName;

The column properties can be set as follows:

• name: name to be assigned to the column
• nullable: whether the column can be null or not
• unique: whether the column is a unique key
• defaultValue: default value for the column
• columnDefinition: custom definition to be used when generating the DDL of the column (e.g. "REAL NOT NULL" would lead to the DDL "name REAL NOT NULL")

Join columns

A join column is specified by using the @JoinColumn annotation and allows to create a relationship between two entities, by specifying a dependency between the new local column (whose name is specified in the "name" parameter) and a remote one (whose name is specified in the "referencedColumnName" parameter) that must be already present in the foreign entity.

@JoinColumn(name = "author_id", referencedColumnName = "ssn")
public Person author;

It is also possible to use more join columns for the same field by using the @JoinColumns annotation

@JoinColumns({
        @JoinColumn(name = "author_first_name", referencedColumnName = "first_name"),
        @JoinColumn(name = "author_last_name", referencedColumnName = "last_name")
})
public Person author;

The join column properties can be set in a similar way to the simple column ones:

• name: name to be assigned to the column
• referencedColumnName: name of the foreign referenced column
• nullable: whether the column can be null or not
• unique: whether the column is a unique key
• defaultValue: default value for the column
• columnDefinition: custom definition to be used when generating the DDL of the column (e.g. "REAL NOT NULL" would lead to the DDL "name REAL NOT NULL")

Join tables

The join tables purpose is similar to the join columns one, but they lead to some mapping differences: first of all they don't lead to new local columns, not in the declaring entity and neither in the foreign entity, but they are only limited to map already existing local columns to the columns that will be created in a new middle table that will store the relationships. By doing this, the @JoinTable relationship allows to create the many to many relationship between two entities.

@ManyToMany
@JoinTable(
        name = "acting",
        joinClass = Film.class,
        joinColumns = {
                @JoinColumn(name = "film_title", referencedColumnName = "title"),
                @JoinColumn(name = "film_year", referencedColumnName = "year")
        },
        inverseJoinClass = Person.class,
        inverseJoinColumns = {
                @JoinColumn(name = "actor_first_name", referencedColumnName = "first_name"),
                @JoinColumn(name = "actor_last_name", referencedColumnName = "last_name")
        }
        )
public Collection<Person> actors;

The annotation parameters are the following ones:

• name: name to be assigned to the new table
• joinClass: class of the declaring entity
• joinColumns: links between the mid table columns and the local ones
• inverseJoinClass: class of the foreign entity
• inverseJoinColumns: links between the mid table columns and the foreign ones

Please note that the name and referencedColumnName parameters of the inner JoinColumn annotations are swapped with respect to the previously explained configuration: the name parameter refers to the new table column, while the referencedColumnName refers to the local column. This is because the @JoinTable annotation considers the new middle table as its main "point of view".

Primary keys

Each entity must have at least one primary key among its fields and be set by using the @Id annotation. Multiple primary keys are allowed and can be set by just using the @Id annotation on all the desired fields.

@Id
@Column(name = "first_name")
public String firstName;

@Id
@Column(name = "last_name")
public String lastName