Show TOC

Background documentationRelationships Mapping Principles Locate this document in the navigation structure

 

JPA uses two mechanisms for mapping relationships: “foreign key relationships” (also referred to as “join-column relationships”) and “join-table relationships”.

Foreign Key Relationships

Foreign key relationships are used for mapping one-to-one, for many-to-one, and bidirectional many-to-one relationships.

A foreign key relationship requires an additional column in the database table of the referring entity. This column is called a “foreign key column” (also called “join column”) and holds the primary key of the related database table. If there is no related entity, the foreign key column holds a NULL value.

The owning side of a foreign key relationship is always the entity that is mapped to the database table containing the foreign key column.

There is no difference in the way you define a foreign key column for one-to-one or many-to-one relationships. If it is a bidirectional relationship, you simply add the mappedBy element on the inverse side.

Example Example

There is a relationship from entity Employee to entity Phone. The entity Employee is mapped to the database table TMP_EMPLOYEE, and the entity Phone is mapped to the database table TMP_PHONE. The column TMP_EMPLOYEE.PHONE_ID is the foreign key column and it holds the primary key of the related table TMP_PHONE.

In this example, the owning side of the relationship is the entity Employee.

End of the example.

If you do not want to adhere to the default foreign key column name, you can specify its mapping explicitly, using the @JoinColumn annotation.

Syntax Syntax

  1. @Entity
public class Employee {
	@Id
	private int id;
	// ...
	@OneToOne
	@JoinColumn(name="PHONE_ID",referencedColumnName="ID")
	private Phone phone;
	// ...
}
End of the code.

The element name specifies the name of the foreign key column, and the element referencedColumnName denotes the name of the primary key column of the related entity. The latter required to identify the referenced primary key column only if the related entity has multiple primary key columns.

Join-Table Relationships

Join-table relationships are used for mapping many-to-many and unidirectional one-to-many relationships. In both cases, one entity is related to multiple other entities. On the database, this relation cannot be established using a single join-column, as in the foreign key relationships mapping. Instead, an additional join-table is needed that pairs the related entities. This table holds the foreign keys to the database tables of both related entities.

If you do not want to adhere to the default names for the join-table and its columns, you can override the defaults using the @JoinTable annotation (or the XML equivalent).

Syntax Syntax

  1. @Entity
public class Employee {
	@Id
	private int id;
	// ...
	@ManyToMany
	@JoinTable(name="TMP_EMPLOYEE_PROJECT", joinColumns={ @JoinColumn(name=”EMPOYEES_ID”) }, 
		inverseJoinColumns={ @JoinColumn(name=”PROJECTS_ID”) })
	private Set<Project> projects;
	// ...
}
End of the code.