From a4f66191c9958a5492cc5cfb5b551bb2f0f4d95a Mon Sep 17 00:00:00 2001 From: Andrew Golovashevich Date: Fri, 3 Jan 2025 14:40:11 +0300 Subject: [PATCH] 'Update' -> 'Upgrade' and other minor naming and docs fixes --- .../api/v0/ddl/module/CreateModuleScope.kt | 28 +++---- .../api/v0/ddl/module/ModuleTemplate.kt | 10 +-- ...teModuleScope.kt => UpgradeModuleScope.kt} | 75 ++++++++----------- 3 files changed, 51 insertions(+), 62 deletions(-) rename src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/{UpdateModuleScope.kt => UpgradeModuleScope.kt} (68%) diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt index 8198f46..f1fa1ca 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt @@ -26,7 +26,7 @@ public interface CreateModuleScope { * @see CreateModuleScope.createTable * @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable - * @see CreateModuleScope.UpdateTable + * @see UpgradeModuleScope.TableUpgrade */ public interface TableCreator { /** @@ -38,7 +38,7 @@ public interface CreateModuleScope { * @see CreateModuleScope.createTable * @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable - * @see CreateModuleScope.UpdateTable + * @see UpgradeModuleScope.TableUpgrade */ public fun createTable(creator: ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator): TableUserExtension } @@ -47,7 +47,7 @@ public interface CreateModuleScope { * Creates table in [specified namespace][namespace] with [specified name][name] and stores it in the database. * If table was created by previous synchronizations, asserts that table at the specified path in the database is same as table provided by [initializer]. * - * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] this table must be [kept][CreateModuleScope.updateTable] (or [renamed][CreateModuleScope.renameTable]) or [deleted][CreateModuleScope.deleteTable]. + * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] this table must be [kept][UpgradeModuleScope.upgradeTable] (or [renamed][CreateModuleScope.renameTable]) or [deleted][CreateModuleScope.deleteTable]. * * @param TableUserExtension User's type for containing table-related descriptors. * @param namespace Way to group tables if there is a lot. @@ -97,7 +97,7 @@ public interface CreateModuleScope { * Scope method that uses [creator] to create a query. * * @param creator Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @return User's object with query-related descriptors for future access. * * @see CreateModuleScope.createSelectQuery */ @@ -118,7 +118,7 @@ public interface CreateModuleScope { public fun createSelectQuery(initializer: SelectQueryCreator): Select /** - * Creates 'SELECT' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. + * Creates 'SELECT' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade]. * Using this function instead of [CreateModuleScope.createSelectQuery] may help the driver to optimize caches and runtime indexes. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. @@ -147,7 +147,7 @@ public interface CreateModuleScope { * * @param table Descriptor of table to which values will be inserted. * @param creator Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @return User's object with query-related descriptors for future access. * * @see CreateModuleScope.createInsertParamsQuery */ @@ -169,7 +169,7 @@ public interface CreateModuleScope { public fun createInsertParamsQuery(table: Table, initializer: InsertParamsQueryCreator): Insert.InsertParams /** - * Creates 'INSERT ... VALUES' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. + * Creates 'INSERT ... VALUES' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade]. * Using this function instead of [CreateModuleScope.createInsertParamsQuery] may help the driver to optimize caches and runtime indexes. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. @@ -199,7 +199,7 @@ public interface CreateModuleScope { * * @param table Descriptor of table to which values will be inserted. * @param creator Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @return User's object with query-related descriptors for future access. * * @see CreateModuleScope.createInsertFromQueryQuery */ @@ -220,7 +220,7 @@ public interface CreateModuleScope { public fun createInsertFromQueryQuery(table: Table, initializer: InsertFromQueryQueryCreator): Insert.InsertFromQuery /** - * Creates 'INSERT ... FROM' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. + * Creates 'INSERT ... FROM' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade]. * Using this function instead of [CreateModuleScope.createInsertFromQueryQuery] may help the driver to optimize caches and runtime indexes. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. @@ -249,7 +249,7 @@ public interface CreateModuleScope { * * @param table Descriptor of table which rows will be updated. * @param creator Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @return User's object with query-related descriptors for future access. * * @see CreateModuleScope.createUpdateQuery */ @@ -270,7 +270,7 @@ public interface CreateModuleScope { public fun createUpdateQuery(table: Table, initializer: UpdateQueryCreator): Update /** - * Creates 'UPDATE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. + * Creates 'UPDATE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade]. * Using this function instead of [CreateModuleScope.createUpdateQuery] may help the driver to optimize caches and runtime indexes. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. @@ -299,7 +299,7 @@ public interface CreateModuleScope { * * @param table Descriptor of table from which data will be deleted. * @param creator Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @return User's object with query-related descriptors for future access. * * @see CreateModuleScope.createDeleteQuery */ @@ -320,8 +320,8 @@ public interface CreateModuleScope { public fun createDeleteQuery(table: Table, initializer: DeleteQueryCreator): Delete /** - * Creates 'DELETE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. - * Using this function instead of [CreateModuleScope.createUpdateQuery] may help the driver to optimize caches and runtime indexes. + * Creates 'DELETE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade]. + * Using this function instead of [CreateModuleScope.createDeleteQuery] may help the driver to optimize caches and runtime indexes. * * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed. * diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleTemplate.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleTemplate.kt index 038dc18..5be54e6 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleTemplate.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleTemplate.kt @@ -4,18 +4,18 @@ import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> { public interface Provider { - public fun createModuleTemplates(creator: CreateModuleTemplatesScope): UserExtension + public fun createModuleTemplates(scope: CreateModuleTemplatesScope): UserExtension } public interface CreateModuleTemplatesScope { public fun createTemplate( versionKey: String, - updater: ModuleCreator, + creator: ModuleCreator, ): ModuleTemplate public fun upgradeTemplate( versionKey: String, - updater: ModuleUpdater, + upgrade: ModuleUpgrade, ): ModuleTemplate } @@ -25,8 +25,8 @@ public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> { public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {} } - public interface ModuleUpdater { - public fun upgradeSchema(oldModule: Module, rootNs: Namespace, updater: CreateModuleScope): NewModuleUserExtension + public interface ModuleUpgrade { + public fun upgradeSchema(oldModule: Module, rootNs: Namespace, upgrader: CreateModuleScope): NewModuleUserExtension public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {} } diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpdateModuleScope.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpgradeModuleScope.kt similarity index 68% rename from src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpdateModuleScope.kt rename to src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpgradeModuleScope.kt index 4e1ae41..f5e02b5 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpdateModuleScope.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpgradeModuleScope.kt @@ -1,53 +1,42 @@ package ru.landgrafhomyak.serdha.api.v0.ddl.module import ru.landgrafhomyak.serdha.api.v0.ddl.table.Table -import ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator import ru.landgrafhomyak.serdha.api.v0.ddl.table.TableUpdater -import ru.landgrafhomyak.serdha.api.v0.dml.Delete -import ru.landgrafhomyak.serdha.api.v0.dml.DeleteCreator -import ru.landgrafhomyak.serdha.api.v0.dml.Insert -import ru.landgrafhomyak.serdha.api.v0.dml.InsertCreator -import ru.landgrafhomyak.serdha.api.v0.dml.Select -import ru.landgrafhomyak.serdha.api.v0.dml.SelectCreator -import ru.landgrafhomyak.serdha.api.v0.dml.Update -import ru.landgrafhomyak.serdha.api.v0.dml.UpdateCreator -import ru.landgrafhomyak.serdha.api.v0.runtime.SynchronizedDatabase -import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction /** * Scope methods for upgrading [module template][ModuleTemplate]. * * @see ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate - * @see ModuleTemplate.ModuleUpdater.upgradeSchema + * @see ModuleTemplate.ModuleUpgrade.upgradeSchema */ -public interface UpdateModuleScope : CreateModuleScope { +public interface UpgradeModuleScope : CreateModuleScope { /** * Functional interface for updating table. * * Can be implemented like a companion object that just calls [TableNewUserExtension]'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 updated table. + * @param TableOldUserExtension User's type with descriptors of upgraded table. * - * @see UpdateModuleScope.updateTable - * @see UpdateModuleScope.renameTable - * @see UpdateModuleScope.updateAndRenameTable - * @see UpdateModuleScope.CreateTable + * @see UpgradeModuleScope.upgradeTable + * @see UpgradeModuleScope.renameTable + * @see UpgradeModuleScope.upgradeAndRenameTable + * @see UpgradeModuleScope.CreateTable */ - public interface UpdateTable { + public interface TableUpgrade { /** - * Scope method that uses [updater] to update table schema. + * Scope method that uses [upgrader] to update table schema. * * @param oldTable Descriptor to the previous version of table from which can be got user's extension with old descriptors. - * @param updater Object with descriptor providers and factories. - * @return User's object with updated descriptors for future access. + * @param upgrader Object with descriptor providers and factories. + * @return User's object with upgraded descriptors for future access. * - * @see UpdateModuleScope.updateTable - * @see UpdateModuleScope.renameTable - * @see UpdateModuleScope.updateAndRenameTable - * @see UpdateModuleScope.CreateTable + * @see UpgradeModuleScope.upgradeTable + * @see UpgradeModuleScope.renameTable + * @see UpgradeModuleScope.upgradeAndRenameTable + * @see UpgradeModuleScope.CreateTable */ - public fun updateTable(oldTable: Table, updater: TableUpdater): TableNewUserExtension + public fun upgradeTable(oldTable: Table, upgrader: TableUpdater): TableNewUserExtension } @@ -79,37 +68,37 @@ public interface UpdateModuleScope : CreateModuleScope { ): Table /** - * Updates table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. + * Upgrade table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. * - * @param TableNewUserExtension User's type with descriptors of updated 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 oldTable Descriptor to the previous version of table from which can be got user's extension with old descriptors. - * @param updater Object with descriptor providers and factories. + * @param upgrade Object with descriptor providers and factories. * @return New table descriptor. */ - public fun updateTable( + public fun upgradeTable( oldTable: Table, - updater: UpdateTable + upgrade: TableUpgrade ): Table /** - * Both updates table's schema and renames or moves table. + * Both upgrade table's schema and renames or moves table. * - * @param TableNewUserExtension User's type with descriptors of updated 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 oldTable Descriptor of table which should be renamed and updated. + * @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. - * @param updater Object with descriptor providers and factories. + * @param upgrade Object with descriptor providers and factories. * @return New table descriptor. * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. */ - public fun updateAndRenameTable( + public fun upgradeAndRenameTable( oldTable: Table, newNamespace: Namespace? = null, newName: String? = null, - updater: UpdateTable + upgrade: TableUpgrade ): Table /** @@ -117,23 +106,23 @@ public interface UpdateModuleScope : CreateModuleScope { * * @param table Descriptor of table which should be deleted. * - * @see UpdateModuleScope.deleteTableAfterModuleUpgraded + * @see UpgradeModuleScope.deleteTableAfterModuleUpgraded */ public fun deleteTable(table: Table<*, *>) /** - * Keeps table while module upgrading and deletes it after [ModuleTemplate.ModuleUpdater.upgradeData]. + * Keeps table while module upgrading and deletes it after [ModuleTemplate.ModuleUpgrade.upgradeData]. * [Table's][table] name become free and can be used for another table. * * @param table Descriptor of table which should be deleted. * - * @see UpdateModuleScope.deleteTable + * @see UpgradeModuleScope.deleteTable */ public fun deleteTableAfterModuleUpgraded(table: Table<*, *>) /** - * Creates a temporary table that exits only while module upgrading and auto-deleted after [ModuleTemplate.ModuleUpdater.upgradeData]. + * 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 namespace Way to group tables if there is a lot. @@ -141,7 +130,7 @@ public interface UpdateModuleScope : CreateModuleScope { * @param initializer Table-related descriptors initializer. * @return Table descriptor. * - * @see UpdateModuleScope.deleteTableAfterModuleUpgraded + * @see UpgradeModuleScope.deleteTableAfterModuleUpgraded * @see CreateModuleScope.createTable * @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable