From 46a32d3ebf18b42009e424a0c932f6914a2c27d9 Mon Sep 17 00:00:00 2001 From: Chantal Loncle <82039410+bog-walk@users.noreply.github.com> Date: Fri, 1 Mar 2024 15:47:27 -0500 Subject: [PATCH] docs: Add missing KDocs for exposed-dao Entity References API Add KDocs in `exposed-dao` to files relating to References. Add more samples to reference functions (that show referenced table too). --- .../org/jetbrains/exposed/dao/EntityClass.kt | 21 +++++++ .../org/jetbrains/exposed/dao/References.kt | 60 +++++++++++++++++++ .../sql/tests/shared/entities/EntityTests.kt | 2 +- 3 files changed, 82 insertions(+), 1 deletion(-) diff --git a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt index 327d8cacf3..1d8072a206 100644 --- a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt +++ b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt @@ -330,7 +330,10 @@ abstract class EntityClass, out T : Entity>( * * The reference should have been defined by the creation of a [column] using `reference()` on the child table. * + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Parent + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Children * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Child + * */ infix fun > referencedOn(column: Column) = registerRefRule(column) { Reference(column, this) } @@ -341,6 +344,8 @@ abstract class EntityClass, out T : Entity>( * The reference should have been defined by the creation of a [column] using either `optReference()` or * `reference().nullable()` on the child table. * + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Board + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Posts * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Post */ infix fun > optionalReferencedOn(column: Column) = registerRefRule(column) { OptionalReference(column, this) } @@ -352,6 +357,8 @@ abstract class EntityClass, out T : Entity>( * The reference should have been defined by the creation of a [column] using `reference()` on the child table. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.YEntity + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.XTable + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.BEntity */ infix fun , Target : Entity, REF : Comparable> EntityClass.backReferencedOn( column: Column @@ -364,6 +371,8 @@ abstract class EntityClass, out T : Entity>( * The reference should have been defined by the creation of a [column] using `reference()` on the child table. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.YEntity + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.XTable + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTestsData.BEntity */ @JvmName("backReferencedOnOpt") infix fun , Target : Entity, REF : Comparable> EntityClass.backReferencedOn( @@ -378,6 +387,8 @@ abstract class EntityClass, out T : Entity>( * `reference().nullable()` on the child table. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Student + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.StudentBios + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.StudentBio */ infix fun , Target : Entity, REF : Comparable> EntityClass.optionalBackReferencedOn( column: Column @@ -392,6 +403,8 @@ abstract class EntityClass, out T : Entity>( * `reference().nullable()` on the child table. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Student + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.StudentBios + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.StudentBio */ @JvmName("optionalBackReferencedOnOpt") infix fun , Target : Entity, REF : Comparable> EntityClass.optionalBackReferencedOn( @@ -408,6 +421,8 @@ abstract class EntityClass, out T : Entity>( * By default, this also stores the loaded entities to a cache. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityHookTestData.Country + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityHookTestData.Cities + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityHookTestData.City */ infix fun , Target : Entity, REF : Comparable> EntityClass.referrersOn(column: Column) = registerRefRule(column) { Referrers, TargetID, Target, REF>(column, this, true) } @@ -421,6 +436,8 @@ abstract class EntityClass, out T : Entity>( * Set [cache] to `true` to also store the loaded entities to a cache. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.School + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Students + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Student */ fun , Target : Entity, REF : Comparable> EntityClass.referrersOn( column: Column, @@ -438,6 +455,8 @@ abstract class EntityClass, out T : Entity>( * By default, this also stores the loaded entities to a cache. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Category + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Posts + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Post */ infix fun , Target : Entity, REF : Comparable> EntityClass.optionalReferrersOn( column: Column @@ -454,6 +473,8 @@ abstract class EntityClass, out T : Entity>( * Set [cache] to `true` to also store the loaded entities to a cache. * * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Student + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Detentions + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Detention */ fun , Target : Entity, REF : Comparable> EntityClass.optionalReferrersOn( column: Column, diff --git a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt index 74c0921a80..440a67f302 100644 --- a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt +++ b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt @@ -19,6 +19,13 @@ private fun checkReference(reference: Column<*>, factoryTable: IdTable<*>) { } } +/** + * Class representing a table relation between 2 [Entity] classes, which is responsible for + * retrieving the parent entity referenced by the child entity. + * + * @param reference The reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the parent entity referenced by the child entity. + */ class Reference, ID : Comparable, out Target : Entity>( val reference: Column, val factory: EntityClass @@ -28,6 +35,13 @@ class Reference, ID : Comparable, out Target : Entity< } } +/** + * Class representing an optional table relation between 2 [Entity] classes, which is responsible for + * retrieving the parent entity optionally referenced by the child entity. + * + * @param reference The nullable reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the parent entity optionally referenced by the child entity. + */ class OptionalReference, ID : Comparable, out Target : Entity>( val reference: Column, val factory: EntityClass @@ -37,6 +51,13 @@ class OptionalReference, ID : Comparable, out Target : } } +/** + * Class responsible for implementing property delegates of the read-only properties involved in a table + * relation between 2 [Entity] classes, which retrieves the child entity that references the parent entity. + * + * @param reference The reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the child entity that references the parent entity. + */ internal class BackReference, out Parent : Entity, ChildID : Comparable, in Child : Entity, REF>( reference: Column, factory: EntityClass @@ -47,6 +68,13 @@ internal class BackReference, out Parent : Entit delegate.getValue(thisRef.apply { thisRef.id.value }, property).single() // flush entity before to don't miss newly created entities } +/** + * Class responsible for implementing property delegates of the read-only properties involved in an optional table + * relation between 2 [Entity] classes, which retrieves the child entity that optionally references the parent entity. + * + * @param reference The nullable reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the child entity that optionally references the parent entity. + */ class OptionalBackReference, out Parent : Entity, ChildID : Comparable, in Child : Entity, REF>( reference: Column, factory: EntityClass @@ -57,6 +85,14 @@ class OptionalBackReference, out Parent : Entity delegate.getValue(thisRef.apply { thisRef.id.value }, property).singleOrNull() // flush entity before to don't miss newly created entities } +/** + * Class responsible for implementing property delegates of the read-only properties involved in a one-to-many + * relation, which retrieves all child entities that reference the parent entity. + * + * @param reference The reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the child entity that references the parent entity. + * @param cache Whether loaded reference entities should be stored in the [EntityCache]. + */ class Referrers, in Parent : Entity, ChildID : Comparable, out Child : Entity, REF>( val reference: Column, val factory: EntityClass, @@ -88,6 +124,14 @@ class Referrers, in Parent : Entity, C } } +/** + * Class responsible for implementing property delegates of the read-only properties involved in an optional one-to-many + * relation, which retrieves all child entities that optionally reference the parent entity. + * + * @param reference The nullable reference column defined on the child entity's associated table. + * @param factory The [EntityClass] associated with the child entity that optionally references the parent entity. + * @param cache Whether loaded reference entities should be stored in the [EntityCache]. + */ class OptionalReferrers, in Parent : Entity, ChildID : Comparable, out Child : Entity, REF>( val reference: Column, val factory: EntityClass, @@ -238,6 +282,14 @@ private fun > List>.preloadRelations( } } +/** + * Eager loads references for all [Entity] instances in this collection and returns this collection. + * + * **See also:** [Eager Loading](https://github.com/JetBrains/Exposed/wiki/DAO#eager-loading) + * + * @param relations The reference fields of the entities, as [KProperty]s, which should be loaded. + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.preloadRelationAtDepth + */ fun , SRC : Entity, REF : Entity<*>, L : Iterable> L.with(vararg relations: KProperty1): L { toList().apply { if (any { it.isNewEntity() }) { @@ -248,6 +300,14 @@ fun , SRC : Entity, REF : Entity<*>, L : Iterab return this } +/** + * Eager loads references for this [Entity] instance and returns this entity instance. + * + * **See also:** [Eager Loading](https://github.com/JetBrains/Exposed/wiki/DAO#eager-loading) + * + * @param relations The reference fields of this entity, as [KProperty]s, which should be loaded. + * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.preloadOptionalReferencesOnAnEntity + */ fun , SRC : Entity> SRC.load(vararg relations: KProperty1, Any?>): SRC = apply { listOf(this).with(*relations) } diff --git a/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt b/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt index 24af0a7c75..0cbf09ddab 100644 --- a/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt +++ b/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt @@ -89,7 +89,7 @@ object EntityTestsData { class YEntity(id: EntityID) : Entity(id) { var x by YTable.x - val b: BEntity? by BEntity.backReferencedOn(XTable.y1) + val b by BEntity.backReferencedOn(XTable.y1) var content by YTable.blob companion object : EntityClass(YTable)