From 543023d2df721683b77cec33e8ac377e0c911355 Mon Sep 17 00:00:00 2001 From: Iaroslav Postovalov Date: Sun, 9 May 2021 15:19:07 +0700 Subject: [PATCH] Documentation for ExposedTable --- .../dataforge/exposed/ExposedTable.kt | 76 +++++++++++++++++-- 1 file changed, 71 insertions(+), 5 deletions(-) diff --git a/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt b/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt index 2f79b604..81c3cb29 100644 --- a/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt +++ b/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt @@ -1,6 +1,5 @@ package space.kscience.dataforge.exposed -import org.jetbrains.exposed.dao.id.EntityID import org.jetbrains.exposed.dao.id.IntIdTable import org.jetbrains.exposed.sql.* import org.jetbrains.exposed.sql.transactions.transaction @@ -12,26 +11,55 @@ import kotlin.reflect.KType import kotlin.reflect.typeOf import org.jetbrains.exposed.sql.Column as SqlColumn +/** + * Exposed based [Column] implementation. + * + * @param T The type of table items. + * @property db The Exposed database. + * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable]. + * @param sqlColumn The Exposed column. + * @param type The type of [T]. + */ public class ExposedColumn( public val db: Database, public val sqlTable: IntIdTable, public val sqlColumn: SqlColumn, public override val type: KType, ) : Column { + /** + * The name of this column. + */ public override val name: String get() = sqlColumn.name + /** + * Returns [Meta.EMPTY] because it is impossible to store metadata correctly with SQL columns. + */ public override val meta: Meta get() = Meta.EMPTY + /** + * Returns the count of rows in the table. + */ public override val size: Int get() = transaction(db) { sqlColumn.table.selectAll().count().toInt() } + /** + * Acquires the value of this column in the row [index]. + */ public override fun get(index: Int): T? = transaction(db) { sqlTable.select { sqlTable.id eq index + 1 }.firstOrNull()?.getOrNull(sqlColumn) } } +/** + * Exposed based [Row] implementation. + * + * @param T The type of table items. + * @param db The Exposed database. + * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable]. + * @param sqlRow The Exposed row. + */ @Suppress("UNCHECKED_CAST") public class ExposedRow( public val db: Database, @@ -39,19 +67,39 @@ public class ExposedRow( public val sqlRow: ResultRow, ) : Row { + /** + * Acquires the value of [column] in this row. + */ public override fun get(column: String): T? = transaction(db) { val theColumn = sqlTable.columns.find { it.name == column } as SqlColumn? ?: return@transaction null sqlRow.getOrNull(theColumn) } } +/** + * Exposed based [Table] implementation. + * + * @property db The Exposed database. + * + * @property sqlTable The Exposed table. It must have the following properties: + * 1. Integer `id` column must be present with auto-increment by sequence 1, 2, 3… + * 1. All other columns must be of type [T]. + * + * @property type The type of [T]. + */ @Suppress("UNCHECKED_CAST") public class ExposedTable(public val db: Database, public val sqlTable: IntIdTable, public val type: KType) : Table { - public override val columns: List> = + /** + * The list of columns in this table. + */ + public override val columns: List> = sqlTable.columns.filterNot { it.name == "id" }.map { ExposedColumn(db, sqlTable, it as SqlColumn, type) } - public override val rows: List> + /** + * The list of rows in this table. + */ + public override val rows: List> get() = transaction(db) { sqlTable.selectAll().map { ExposedRow(db, sqlTable, it) } } @@ -64,9 +112,27 @@ public class ExposedTable(public val db: Database, public val sqlTable: } } -public inline fun ExposedTable(db: Database, table: IntIdTable): ExposedTable = - ExposedTable(db, table, typeOf()) +/** + * Constructs [ExposedTable]. + * + * @param T The type of table items. + * @param db The Exposed database. + * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable]. + * @return A new [ExposedTable]. + */ +public inline fun ExposedTable(db: Database, sqlTable: IntIdTable): ExposedTable = + ExposedTable(db, sqlTable, typeOf()) +/** + * Constructs [ExposedTable]. + * + * @param T The type of table items. + * @param db The Exposed database. + * @param tableName The name of table. + * @param columns The list of columns' names. + * @param sqlColumnType The [IColumnType] for [T]. + * @return A new [ExposedTable]. + */ public inline fun ExposedTable( db: Database, tableName: String,