diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt index ca141464be..d70ca30236 100644 --- a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt +++ b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt @@ -48,7 +48,7 @@ enum class ReferenceOption { * Represents a foreign key constraint. */ data class ForeignKeyConstraint( - /** Mapping of referenced parent table columns to the foreign key columns in their child tables. */ + /** Mapping of the foreign key columns in the referencing child table to their referenced parent table columns. */ val references: Map, Column<*>>, private val onUpdate: ReferenceOption?, private val onDelete: ReferenceOption?, @@ -65,31 +65,31 @@ data class ForeignKeyConstraint( private val tx: Transaction get() = TransactionManager.current() - /** The columns of the referencing child table. */ + /** The columns of the referenced parent table. */ val target: LinkedHashSet> = LinkedHashSet(references.values) - /** The referencing child table. */ + /** The referenced parent table. */ val targetTable: Table = target.first().table - /** Name of the child table. */ + /** Name of the referenced parent table. */ val targetTableName: String get() = tx.identity(targetTable) - /** Names of the foreign key columns. */ + /** Names of the referenced parent table columns. */ private val targetColumns: String get() = target.joinToString { tx.identity(it) } - /** The columns of the referenced parent table. */ + /** The foreign key columns of the referencing child table. */ val from: LinkedHashSet> = LinkedHashSet(references.keys) - /** The referenced parent table. */ + /** The referencing child table. */ val fromTable: Table = from.first().table - /** Name of the parent table. */ + /** Name of the referencing child table. */ val fromTableName: String get() = tx.identity(fromTable) - /** Names of the key columns from the parent table. */ + /** Names of the foreign key columns from the referencing child table. */ private val fromColumns: String get() = from.joinToString { tx.identity(it) } @@ -105,7 +105,7 @@ data class ForeignKeyConstraint( val customFkName: String? get() = name - /** Name of this constraint. */ + /** Name of this foreign key constraint. */ val fkName: String get() = tx.db.identifierManager.cutIfNecessaryAndQuote( name ?: ( @@ -168,7 +168,7 @@ data class ForeignKeyConstraint( return listOf("ALTER TABLE $fromTableName DROP $constraintType $fkName") } - /** Returns the child table column that is referencing the provided column in the parent table. */ + /** Returns the parent table column that is referenced by the [from] column in the child table. */ fun targetOf(from: Column<*>): Column<*>? = references[from] operator fun plus(other: ForeignKeyConstraint): ForeignKeyConstraint { diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Table.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Table.kt index 5d531443dd..ae77b71a6e 100644 --- a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Table.kt +++ b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Table.kt @@ -461,7 +461,7 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { private val _foreignKeys = mutableListOf() - /** Returns all foreignKeys declared on the table. */ + /** Returns all foreign key constraints declared on the table. */ val foreignKeys: List get() = columns.mapNotNull { it.foreignKey } + _foreignKeys private val checkConstraints = mutableListOf>>() @@ -918,13 +918,13 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { // Column references /** - * Create reference from a @receiver column to [ref] column. + * Creates a reference from this @receiver column to a [ref] column. * - * It's a short infix version of [references] function with default onDelete and onUpdate behavior. + * This is a short infix version of `references()` with default `onDelete` and `onUpdate` behavior. * - * @receiver A column from current table where reference values will be stored + * @receiver A column from the current table where reference values will be stored. * @param ref A column from another table which will be used as a "parent". - * @see [references] + * @sample org.jetbrains.exposed.sql.tests.shared.dml.JoinTests.testJoin04 */ infix fun , S : T, C : Column> C.references(ref: Column): C = references( ref, @@ -934,15 +934,17 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { ) /** - * Create reference from a @receiver column to [ref] column with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * Creates a reference from this @receiver column to a [ref] column with [onDelete], [onUpdate], and [fkName] options. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * - * @receiver A column from current table where reference values will be stored + * @receiver A column from the current table where reference values will be stored. * @param ref A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. See [ReferenceOption] documentation for details. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. See [ReferenceOption] documentation for details. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. + * @sample org.jetbrains.exposed.sql.tests.sqlite.ForeignKeyConstraintTests.testUpdateAndDeleteRulesReadCorrectlyWhenSpecifiedInChildTable */ fun , S : T, C : Column> C.references( ref: Column, @@ -960,15 +962,17 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { } /** - * Create reference from a @receiver column to [ref] column with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * Creates a reference from this @receiver column to a [ref] column with [onDelete], [onUpdate], and [fkName] options. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * - * @receiver A column from current table where reference values will be stored + * @receiver A column from the current table where reference values will be stored. * @param ref A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. See [ReferenceOption] documentation for details. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. See [ReferenceOption] documentation for details. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. + * @sample org.jetbrains.exposed.sql.tests.shared.ddl.CreateMissingTablesAndColumnsTests.ExplicitTable */ @JvmName("referencesById") fun , S : T, C : Column> C.references( @@ -987,17 +991,18 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { } /** - * Creates a column with the specified [name] with a reference to the [refColumn] column and with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * Creates a column with the specified [name] with a reference to the [refColumn] column and with [onDelete], + * [onUpdate], and [fkName] options. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param refColumn A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Orders */ fun > reference( name: String, @@ -1016,17 +1021,18 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { } /** - * Creates a column with the specified [name] with a reference to the [refColumn] column and with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * Creates a column with the specified [name] with a reference to the [refColumn] column and with [onDelete], + * [onUpdate], and [fkName] options. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param refColumn A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Schools */ @Suppress("UNCHECKED_CAST") @JvmName("referenceByIdColumn") @@ -1042,17 +1048,18 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { } /** - * Creates a column with the specified [name] with a reference to the `id` column in [foreign] table and with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * Creates a column with the specified [name] with a reference to the `id` column in [foreign] table and with + * [onDelete], [onUpdate], and [fkName] options. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param foreign A table with an `id` column which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Schools */ fun > reference( name: String, @@ -1064,16 +1071,16 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { /** * Creates a column with the specified [name] with an optional reference to the [refColumn] column with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param refColumn A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Posts */ fun > optReference( name: String, @@ -1085,16 +1092,15 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { /** * Creates a column with the specified [name] with an optional reference to the [refColumn] column with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param refColumn A column from another table which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. - * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Posts */ @JvmName("optReferenceByIdColumn") fun , E : EntityID> optReference( @@ -1107,16 +1113,16 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { /** * Creates a column with the specified [name] with an optional reference to the `id` column in [foreign] table with [onDelete], [onUpdate], and [fkName] options. - * [onDelete] and [onUpdate] options describes behavior on how links between tables will be checked in case of deleting or changing corresponding columns' values. - * Such relationship will be represented as FOREIGN KEY constraint on a table creation. + * [onDelete] and [onUpdate] options describe the behavior for how links between tables will be checked when deleting + * or changing corresponding columns' values. + * Such a relationship will be represented as a FOREIGN KEY constraint on table creation. * * @param name Name of the column. * @param foreign A table with an `id` column which will be used as a "parent". - * @param onDelete Optional reference option for cases when linked row from a parent table will be deleted. - * @param onUpdate Optional reference option for cases when value in a referenced column had changed. + * @param onDelete Optional [ReferenceOption] for cases when a linked row from a parent table will be deleted. + * @param onUpdate Optional [ReferenceOption] for cases when a value in a referenced column will be changed. * @param fkName Optional foreign key constraint name. - * - * @see ReferenceOption + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Schools */ fun > optReference( name: String, @@ -1235,11 +1241,13 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { /** * Creates a composite foreign key. * - * @param from Columns that compose the foreign key. Their order should match the order of columns in referenced primary key. - * @param target Primary key of the referenced table. - * @param onUpdate Reference option when performing update operations. - * @param onUpdate Reference option when performing delete operations. - * @param name Custom foreign key name + * @param from Columns in this referencing child table that compose the foreign key. + * Their order should match the order of columns in the referenced parent table's primary key. + * @param target Primary key of the referenced parent table. + * @param onUpdate [ReferenceOption] when performing update operations. + * @param onUpdate [ReferenceOption] when performing delete operations. + * @param name Custom foreign key constraint name. + * @sample org.jetbrains.exposed.sql.tests.shared.ddl.CreateMissingTablesAndColumnsTests.CompositeForeignKeyTable */ fun foreignKey( vararg from: Column<*>, @@ -1258,13 +1266,15 @@ open class Table(name: String = "") : ColumnSet(), DdlAware { /** * Creates a composite foreign key. * - * @param references Pairs of columns that compose the foreign key. - * First value of pair is a column of referencing table, second value - a column of a referenced one. + * @param references Pairs of child table and parent table columns that compose the foreign key. + * The first value of each pair should be a column from this referencing child table, + * with the second value being a column from the referenced parent table. * All referencing columns must belong to this table. * All referenced columns must belong to the same table. - * @param onUpdate Reference option when performing update operations. - * @param onUpdate Reference option when performing delete operations. - * @param name Custom foreign key name + * @param onUpdate [ReferenceOption] when performing update operations. + * @param onUpdate [ReferenceOption] when performing delete operations. + * @param name Custom foreign key constraint name. + * @sample org.jetbrains.exposed.sql.tests.shared.DDLTests.testCompositeFKReferencingUniqueIndex */ fun foreignKey( vararg references: Pair, Column<*>>,