Skip to content

Commit

Permalink
docs: Add missing KDocs for exposed-dao Entity References API
Browse files Browse the repository at this point in the history 
Add KDocs in `exposed-dao` to files relating to References.
Add more samples to reference functions (that show referenced table too).
  • Loading branch information
@bog-walk
bog-walk committed Mar 1, 2024
1 parent 1742b95 commit 46a32d3
Show file tree
Hide file tree
Showing 3 changed files with 82 additions and 1 deletion.
21 changes: 21 additions & 0 deletions exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -330,7 +330,10 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
*
* 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 <REF : Comparable<REF>> referencedOn(column: Column<REF>) = registerRefRule(column) { Reference(column, this) }

Expand All @@ -341,6 +344,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <REF : Comparable<REF>> optionalReferencedOn(column: Column<REF?>) = registerRefRule(column) { OptionalReference(column, this) }
Expand All @@ -352,6 +357,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.backReferencedOn(
column: Column<REF>
Expand All @@ -364,6 +371,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.backReferencedOn(
Expand All @@ -378,6 +387,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* `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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.optionalBackReferencedOn(
column: Column<REF>
Expand All @@ -392,6 +403,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* `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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.optionalBackReferencedOn(
Expand All @@ -408,6 +421,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.referrersOn(column: Column<REF>) =
registerRefRule(column) { Referrers<ID, Entity<ID>, TargetID, Target, REF>(column, this, true) }
Expand All @@ -421,6 +436,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.referrersOn(
column: Column<REF>,
Expand All @@ -438,6 +455,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.optionalReferrersOn(
column: Column<REF?>
Expand All @@ -454,6 +473,8 @@ abstract class EntityClass<ID : Comparable<ID>, out T : Entity<ID>>(
* 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 <TargetID : Comparable<TargetID>, Target : Entity<TargetID>, REF : Comparable<REF>> EntityClass<TargetID, Target>.optionalReferrersOn(
column: Column<REF?>,
Expand Down
60 changes: 60 additions & 0 deletions exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<REF : Comparable<REF>, ID : Comparable<ID>, out Target : Entity<ID>>(
val reference: Column<REF>,
val factory: EntityClass<ID, Target>
Expand All @@ -28,6 +35,13 @@ class Reference<REF : Comparable<REF>, ID : Comparable<ID>, 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<REF : Comparable<REF>, ID : Comparable<ID>, out Target : Entity<ID>>(
val reference: Column<REF?>,
val factory: EntityClass<ID, Target>
Expand All @@ -37,6 +51,13 @@ class OptionalReference<REF : Comparable<REF>, ID : Comparable<ID>, 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<ParentID : Comparable<ParentID>, out Parent : Entity<ParentID>, ChildID : Comparable<ChildID>, in Child : Entity<ChildID>, REF>(
reference: Column<REF>,
factory: EntityClass<ParentID, Parent>
Expand All @@ -47,6 +68,13 @@ internal class BackReference<ParentID : Comparable<ParentID>, 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<ParentID : Comparable<ParentID>, out Parent : Entity<ParentID>, ChildID : Comparable<ChildID>, in Child : Entity<ChildID>, REF>(
reference: Column<REF?>,
factory: EntityClass<ParentID, Parent>
Expand All @@ -57,6 +85,14 @@ class OptionalBackReference<ParentID : Comparable<ParentID>, 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<ParentID : Comparable<ParentID>, in Parent : Entity<ParentID>, ChildID : Comparable<ChildID>, out Child : Entity<ChildID>, REF>(
val reference: Column<REF>,
val factory: EntityClass<ChildID, Child>,
Expand Down Expand Up @@ -88,6 +124,14 @@ class Referrers<ParentID : Comparable<ParentID>, in Parent : Entity<ParentID>, 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<ParentID : Comparable<ParentID>, in Parent : Entity<ParentID>, ChildID : Comparable<ChildID>, out Child : Entity<ChildID>, REF>(
val reference: Column<REF?>,
val factory: EntityClass<ChildID, Child>,
Expand Down Expand Up @@ -238,6 +282,14 @@ private fun <ID : Comparable<ID>> List<Entity<ID>>.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 <SRCID : Comparable<SRCID>, SRC : Entity<SRCID>, REF : Entity<*>, L : Iterable<SRC>> L.with(vararg relations: KProperty1<out REF, Any?>): L {
toList().apply {
if (any { it.isNewEntity() }) {
Expand All @@ -248,6 +300,14 @@ fun <SRCID : Comparable<SRCID>, SRC : Entity<SRCID>, 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 <SRCID : Comparable<SRCID>, SRC : Entity<SRCID>> SRC.load(vararg relations: KProperty1<out Entity<*>, Any?>): SRC = apply {
listOf(this).with(*relations)
}
2 changes: 1 addition & 1 deletion exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ object EntityTestsData {

class YEntity(id: EntityID<String>) : Entity<String>(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<String, YEntity>(YTable)
Expand Down

0 comments on commit 46a32d3

Please sign in to comment.