From 5e4e2bdf4ab0c52e638415e7b73f1e8f6ff415a1 Mon Sep 17 00:00:00 2001 From: Andrew Golovashevich Date: Sun, 2 Feb 2025 02:17:03 +0300 Subject: [PATCH] Improvements in module creation interfaces --- .../serdha0/api/module/CreateModuleScope.kt | 16 ++--- .../db/serdha0/api/module/Module.kt | 4 +- .../db/serdha0/api/module/ModuleTemplate.kt | 4 +- .../serdha0/api/module/UpgradeModuleScope.kt | 62 ++++++++++--------- 4 files changed, 44 insertions(+), 42 deletions(-) diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/CreateModuleScope.kt b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/CreateModuleScope.kt index a5e81b3..0421757 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/CreateModuleScope.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/CreateModuleScope.kt @@ -13,7 +13,7 @@ import ru.landgrafhomyak.db.serdha0.api.table.TableConstructor * @see ModuleTemplate.ModuleCreator.createSchema */ public interface CreateModuleScope { - + public val rootNs: Namespace /** * Creates table in [specified namespace][namespace] with [specified name][name] and stores it in the database. @@ -21,39 +21,39 @@ public interface CreateModuleScope { * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] this table must be [kept][UpgradeModuleScope.upgradeTable] (or [renamed][UpgradeModuleScope.renameTable]) or [deleted][UpgradeModuleScope.deleteTable]. * - * @param TableUserExtension User's type for containing table-related descriptors. + * @param tUE User's type for containing table-related descriptors. * @param namespace Way to group tables if there is a lot. * @param name Name of table for debugging. * @param initializer Table-related descriptors initializer. * @return Table descriptor. */ - public fun createTable(namespace: Namespace, name: String, initializer: TableConstructor): Table + public fun createTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor): Table /** * Creates a temporary table that exits only until connection to the database not [closed][SynchronizedDatabase._close]. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. * - * @param TableUserExtension User's type for containing table-related descriptors. + * @param tUE User's type for containing table-related descriptors. * @param namespace Way to group tables if there is a lot. * @param name Name of table for debugging. * @param initializer Table-related descriptors initializer. * @return Table descriptor. */ - public fun createSessionScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor): Table + public fun createSessionScopeTemporaryTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor): Table /** * Creates a temporary table that exits only inside [transaction][Transaction] and auto-deleted (or cleared, depends on driver implementation) when it [finished][Transaction._assertTransactionFinishedAndReleaseResources]. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. * - * @param TableUserExtension User's type for containing table-related descriptors. + * @param tUE User's type for containing table-related descriptors. * @param namespace Way to group tables if there is a lot. * @param name Name of table for debugging. * @param initializer Table-related descriptors initializer. * @return Table descriptor. */ - public fun createTransactionScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor): Table + public fun createTransactionScopeTemporaryTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor): Table public val queries: _Query.Constructor.Scope @@ -73,5 +73,5 @@ public interface CreateModuleScope { * @param template Schema template. * @return Module descriptor. */ - public fun substituteModule(rootNs: Namespace, template: ModuleTemplate): Module + public fun substituteModule(rootNs: Namespace, template: ModuleTemplate): Module } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/Module.kt b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/Module.kt index bb5cbde..9d32406 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/Module.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/Module.kt @@ -6,13 +6,13 @@ import ru.landgrafhomyak.db.serdha0.api.runtime.SynchronizedDatabase /** * Descriptor of synchronized module. Used for schema manipulations. */ -public interface Module { +public interface Module { /** * Reference user's extension with descriptors related to this module for use in runtime. */ @Suppress("INAPPLICABLE_JVM_NAME") @get:JvmName("userExtension") - public val userExtension: ModuleUserExtension + public val uExt: mUE /** * Version key internally used for automatically [upgrading modules][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate]. For debugging. */ diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/ModuleTemplate.kt b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/ModuleTemplate.kt index 23741d7..7653c14 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/ModuleTemplate.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/ModuleTemplate.kt @@ -20,13 +20,13 @@ public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> { } public interface ModuleCreator { - public fun createSchema(rootNs: Namespace, creator: CreateModuleScope): ModuleUserExtension + public fun createSchema(context: CreateModuleScope): ModuleUserExtension public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {} } public interface ModuleUpgrade { - public fun upgradeSchema(oldModule: Module, rootNs: Namespace, upgrader: CreateModuleScope): NewModuleUserExtension + public fun upgradeSchema(context: UpgradeModuleScope): NewModuleUserExtension public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {} } diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/UpgradeModuleScope.kt b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/UpgradeModuleScope.kt index 5ec3c01..1d1ee58 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/UpgradeModuleScope.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/UpgradeModuleScope.kt @@ -10,21 +10,23 @@ import ru.landgrafhomyak.db.serdha0.api.table.UpdateTableScope * @see ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate * @see ModuleTemplate.ModuleUpgrade.upgradeSchema */ -public interface UpgradeModuleScope : CreateModuleScope { +public interface UpgradeModuleScope : CreateModuleScope { + public val oldModule: omUE + /** * Functional interface for updating table. * - * Can be implemented like a companion object that just calls [TableNewUserExtension]'s constructor with the same or similar signature. + * Can be implemented like a companion object that just calls [tnUE]'s constructor with the same or similar signature. * - * @param TableNewUserExtension User's type with table's descriptors from the previous table version. - * @param TableOldUserExtension User's type with descriptors of upgraded table. + * @param tnUE User's type with table's descriptors from the previous table version. + * @param toUE User's type with descriptors of upgraded table. * * @see UpgradeModuleScope.upgradeTable * @see UpgradeModuleScope.renameTable * @see UpgradeModuleScope.upgradeAndRenameTable * @see UpgradeModuleScope.CreateTable */ - public interface TableUpgrade { + public interface TableUpgrade { /** * Scope method that uses [upgrader] to update table schema. * @@ -37,57 +39,57 @@ public interface UpgradeModuleScope : CreateModuleScope { * @see UpgradeModuleScope.upgradeAndRenameTable * @see UpgradeModuleScope.CreateTable */ - public fun upgradeTable(oldTable: Table, upgrader: UpdateTableScope): TableNewUserExtension + public fun upgradeTable(oldTable: Table, upgrader: UpdateTableScope): tnUE } /** * Marks that table wouldn't be changed in this module version. * - * @param TableUserExtension User's type with descriptors of related to table. + * @param tUE User's type with descriptors of related to table. * @param oldTable Descriptor of table created in a previous template version. * @return New table descriptor. */ - public fun keepTable( - table: Table, - ): Table + public fun keepTable( + table: Table, + ): Table /** * Renames or moves table without changing its schema. * - * @param TableUserExtension User's type with descriptors of related to table. + * @param tUE User's type with descriptors of related to table. * @param table Descriptor to table which should be renamed. * @param newNamespace New namespace of the table. May be `null` if not changed. * @param newName New namespace of the table. May be `null` if not changed. * @return New table descriptor. * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. */ - public fun renameTable( - table: Table, + public fun renameTable( + table: Table, newNamespace: Namespace? = null, newName: String? = null - ): Table + ): Table /** * Upgrade table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. * - * @param TableNewUserExtension User's type with descriptors of upgraded table. - * @param TableOldUserExtension User's type with table's descriptors from the previous table version. + * @param tnUE User's type with descriptors of upgraded table. + * @param toUE User's type with table's descriptors from the previous table version. * @param oldTable Descriptor to the previous version of table from which can be got user's extension with old descriptors. * @param upgrade Object with descriptor providers and factories. * @return New table descriptor. */ - public fun upgradeTable( - oldTable: Table, - upgrade: TableUpgrade - ): Table + public fun upgradeTable( + oldTable: Table, + upgrade: TableUpgrade + ): Table /** * Both upgrade table's schema and renames or moves table. * - * @param TableNewUserExtension User's type with descriptors of upgraded table. - * @param TableOldUserExtension User's type with table's descriptors from the previous table version. + * @param tnUE User's type with descriptors of upgraded table. + * @param toUE User's type with table's descriptors from the previous table version. * @param oldTable Descriptor of table which should be renamed and upgraded. * @param newNamespace New namespace of the table. May be `null` if not changed. * @param newName New namespace of the table. May be `null` if not changed. @@ -95,12 +97,12 @@ public interface UpgradeModuleScope : CreateModuleScope { * @return New table descriptor. * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. */ - public fun upgradeAndRenameTable( - oldTable: Table, + public fun upgradeAndRenameTable( + oldTable: Table, newNamespace: Namespace? = null, newName: String? = null, - upgrade: TableUpgrade - ): Table + upgrade: TableUpgrade + ): Table /** * Deletes table and all data in it. @@ -125,7 +127,7 @@ public interface UpgradeModuleScope : CreateModuleScope { /** * Creates a temporary table that exits only while module upgrading and auto-deleted after [ModuleTemplate.ModuleUpgrade.upgradeData]. * - * @param TableUserExtension User's type for containing table-related descriptors. + * @param tUE User's type for containing table-related descriptors. * @param namespace Way to group tables if there is a lot. * @param name Name of table for debugging. * @param initializer Table-related descriptors initializer. @@ -136,15 +138,15 @@ public interface UpgradeModuleScope : CreateModuleScope { * @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable */ - public fun createModuleUpgradeScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor): Table + public fun createModuleUpgradeScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor): Table /** * Upgrades [module][oldModule] located at [rootNs] with new schema template. * - * @param rootNs Namespace where the [old module][oldModule] is located and where upgaded module will be. + * @param rootNs Namespace where the [old module][oldModule] is located and where upgraded module will be. * @param template Schema template. * @return Module descriptor. */ - public fun upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate): Module + public fun upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate): Module } \ No newline at end of file