2.7.24 @JoinColumn

Organization of this subsection
(1) Description
(2) Element

(1) Description

This annotation specifies the external key column for the binding table, or the column name of the binding--destination table that is referenced from the external key column, when the entity classes are correlated. Always specify the column that acts as the primary key of the binding--destination table.

When multiple external key columns exist, use @JoinColumns, and specify @JoinColumn for each relation. When multiple @JoinColumns are specified, specify the name element and referencedColumnName element in each annotation.

When @JoinColumn is not specified explicitly, it is assumed that a single external key column is specified in the persistence property or persistence field that specifies the relation. Also, the default value is applied to each element value of @JoinColumn.

Furthermore, if the changes made in a single column of the field and the changes made by correlating the cascade operation are performed concurrently, consistency might not be achieved. Therefore, when the column specified in the name element and the referencedColumnName element is defined in a field of the entity, the insertable element and the updatable element must be set to false. With this, only the changes made in the field will be applied to the database, but the changes made due to the correlation of the cascade operation will not be applied to the database.

The applicable targets are method and field.

(2) Element

The following table lists the elements of @JoinColumn:

Element nameOptional/RequiredElement description
nameOptionalThis element specifies the external key column name used to bind the target tables.
referencedColumnNameOptionalThis element specifies the column name of the binding--destination table that is referenced from the external key column specified in the name element.
uniqueOptionalThis element specifies whether or not the property is a unique key.
Note that Cosminexus JPA provider does not support this attribute.
nullableOptionalThis element specifies whether or not a null value can be specified in the database column.
Note that Cosminexus JPA provider does not support this attribute.
insertableOptionalThis element specifies whether or not to include the column specified by @JoinColumn in the INSERT statement of the SQL.
updatableOptionalThis element specifies whether or not to include the column specified by @JoinColumn in the UPDATE statement of the SQL.
columnDefinitionOptionalThis element is used to describe the constraints added to the external column in the DDL, when the CREATE statement is output.
Note that Cosminexus JPA provider does not support this attribute.
tableOptionalThis element specifies the table name that includes the external key column.

The details of attributes that are supported in Cosminexus JPA provider are as follows:

(a) name element
Type
String
Description
This element specifies the external key column name used to bind the target tables.
The location of existence of the external key column is different for each type of the entity relationship. The location of existence of the external key column for each type of the entity relationship is as follows:
  • In the case of OneToOne relationship or ManyToOne relationship
    Within the local entity table
  • In the case of ManyToMany relationship
    Within the binding table of @JoinTable
The values that can be specified depend on the specifications of the database column name.
Default value
  • When a single external key column is specified in the local entity, and nothing is specified in the value of the name element
    name-of-the-related-property-or-field-within-the-local-entity_name--of-the-referenced--primary--key--column
  • When the related property and field that is being referenced does not exist (example: when @JoinTable is used)
    name-of-the-referenced-entity_name-of-the-referenced-primary-key-column
(b) referencedColumnName element
Type
String
Description
This element specifies the column name of the binding--destination table that is referenced by the external key column specified in the name element.
The column name of the binding--destination table exists at the following locations:
  • When the relationship annotation is used
    Within the referenced table
  • When @JoinTable is used
    Within the entity table of the owner entity
Note
When binding is defined as a part of reverse binding, the location will be within the table of the non--owner entity class.
The column names that can be specified depend on the database specifications.
Default value
Column name of the primary key of the table referenced from the external key
Note
If a single external key column is specified, the default value will be applied.
(c) insertable element
Type
boolean
Description
This element specifies whether or not to include the column specified by @JoinColumn in the INSERT statement of the SQL. You can specify either true or false.
These values imply the following meaning:
true: The column specified by @JoinColumn is included in the INSERT statement of the SQL.
false: The column specified by @JoinColumn is not included in the INSERT statement of the SQL.
Default value
true
(d) updatable element
Type
boolean
Description
This element specifies whether or not to include the column specified by @JoinColumn in the UPDATE statement of the SQL. You can specify either true or false.
These values imply the following meaning:
true: The column specified by @JoinColumn is included in the UPDATE statement of the SQL.
false: The column specified by @JoinColumn is not included in the UPDATE statement of the SQL.
Default value
true
(e) table element
Type
String
Description
This element specifies the table name that includes the external key column.
The table name that can be specified depends on the database specifications.
Default value
Primary table name