From c43c1a2b70037ea97306442766c8c424bb3739eb Mon Sep 17 00:00:00 2001 From: Andrew Golovashevich Date: Fri, 3 Jan 2025 14:40:00 +0300 Subject: [PATCH] [history/serdha] 'Update' -> 'Upgrade' and other minor naming and docs fixes --- .../api/v0/ddl/module/CreateModuleScope.kt | 97 +++++++++++++++++-- .../api/v0/ddl/module/ModuleTemplate.kt | 10 +- 2 files changed, 94 insertions(+), 13 deletions(-) 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 2653b2f..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 */ @@ -112,9 +112,25 @@ public interface CreateModuleScope { * @param QueryUserWrapper User's type for containing query-related descriptors. * @param initializer Query-related descriptors initializer. * @return Query descriptor. + * + * @see CreateModuleScope.createTemporarySelectQuery */ public fun createSelectQuery(initializer: SelectQueryCreator): Select + /** + * 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. + * + * @param QueryUserWrapper User's type for containing query-related descriptors. + * @param initializer Query-related descriptors initializer. + * @return Query descriptor. + * + * @see CreateModuleScope.createSelectQuery + */ + public fun createTemporarySelectQuery(initializer: SelectQueryCreator): Select + /** * Functional interface for creating 'INSERT ... VALUES' query. * @@ -131,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 */ @@ -147,9 +163,26 @@ public interface CreateModuleScope { * @param QueryUserWrapper User's type for containing query-related descriptors. * @param initializer Query-related descriptors initializer. * @return Query descriptor. + * + * @see CreateModuleScope.createTemporaryInsertParamsQuery */ 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.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. + * + * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. + * @param QueryUserWrapper User's type for containing query-related descriptors. + * @param initializer Query-related descriptors initializer. + * @return Query descriptor. + * + * @see CreateModuleScope.createInsertParamsQuery + */ + public fun createTemporaryInsertParamsQuery(table: Table, initializer: InsertParamsQueryCreator): Insert.InsertParams + /** * Functional interface for creating 'INSERT ... FROM' query. * @@ -166,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 */ @@ -181,9 +214,25 @@ public interface CreateModuleScope { * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. * @param initializer Query-related descriptors initializer. * @return Query descriptor. + * + * @see CreateModuleScope.createTemporaryInsertFromQueryQuery */ 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.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. + * + * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. + * @param initializer Query-related descriptors initializer. + * @return Query descriptor. + * + * @see CreateModuleScope.createInsertFromQueryQuery + */ + public fun createTemporaryInsertFromQueryQuery(table: Table, initializer: InsertFromQueryQueryCreator): Insert.InsertFromQuery + /** * Functional interface for creating 'UPDATE' query. * @@ -200,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 */ @@ -215,9 +264,25 @@ public interface CreateModuleScope { * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. * @param initializer Query-related descriptors initializer. * @return Query descriptor. + * + * @see CreateModuleScope.createTemporaryUpdateQuery */ public fun createUpdateQuery(table: Table, initializer: UpdateQueryCreator): Update + /** + * 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. + * + * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. + * @param initializer Query-related descriptors initializer. + * @return Query descriptor. + * + * @see CreateModuleScope.createUpdateQuery + */ + public fun createTemporaryUpdateQuery(table: Table, initializer: UpdateQueryCreator): Update + /** * Functional interface for creating 'DELETE' query. * @@ -234,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 */ @@ -249,9 +314,25 @@ public interface CreateModuleScope { * @param TableUserExtension User's type with descriptors related to table from which data will be deleted. * @param initializer Query-related descriptors initializer. * @return Query descriptor. + * + * @see CreateModuleScope.createTemporaryDeleteQuery */ public fun createDeleteQuery(table: Table, initializer: DeleteQueryCreator): Delete + /** + * 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. + * + * @param TableUserExtension User's type with descriptors related to table from which data will be deleted. + * @param initializer Query-related descriptors initializer. + * @return Query descriptor. + * + * @see CreateModuleScope.createDeleteQuery + */ + public fun createTemporaryDeleteQuery(table: Table, initializer: DeleteQueryCreator): Delete + /** * Replaces [specified namespace][rootNs] with schema provided by [template]. * [This namespace][rootNs] will be root namespace for module and shouldn't contain any other definitions. 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) {} }