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 new file mode 100644 index 0000000..2653b2f --- /dev/null +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt @@ -0,0 +1,264 @@ +package ru.landgrafhomyak.serdha.api.v0.ddl.module + +import ru.landgrafhomyak.serdha.api.v0.ddl.table.Table +import ru.landgrafhomyak.serdha.api.v0.dml.Delete +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.Update +import ru.landgrafhomyak.serdha.api.v0.runtime.SynchronizedDatabase +import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction + +/** + * Scope methods for creating new [module template][ModuleTemplate]. + * + * @see ModuleTemplate.CreateModuleTemplatesScope.createTemplate + * @see ModuleTemplate.ModuleCreator.createSchema + */ +public interface CreateModuleScope { + /** + * Functional interface for creating table. + * + * Can be implemented like a companion object that just calls [TableUserExtension]'s constructor with the same or similar signature. + * + * @param TableUserExtension User's type for containing table-related descriptors. + * + * @see CreateModuleScope.createTable + * @see CreateModuleScope.createSessionScopeTemporaryTable + * @see CreateModuleScope.createTransactionScopeTemporaryTable + * @see CreateModuleScope.UpdateTable + */ + public interface TableCreator { + /** + * Scope method that uses [creator] to initialize table schema. + * + * @param creator Object with descriptor providers and factories. + * @return User's object with descriptors for future access. + * + * @see CreateModuleScope.createTable + * @see CreateModuleScope.createSessionScopeTemporaryTable + * @see CreateModuleScope.createTransactionScopeTemporaryTable + * @see CreateModuleScope.UpdateTable + */ + public fun createTable(creator: ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator): TableUserExtension + } + + /** + * 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]. + * + * @param TableUserExtension 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: TableCreator): 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 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: TableCreator): 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 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: TableCreator): Table + + /** + * Functional interface for creating 'SELECT' query. + * + * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. + * + * @param QueryUserWrapper User's type with descriptors related to query. + * + * @see CreateModuleScope.createSelectQuery + */ + public interface SelectQueryCreator { + /** + * 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. + * + * @see CreateModuleScope.createSelectQuery + */ + public fun createSelect(creator: ru.landgrafhomyak.serdha.api.v0.dml.SelectCreator): QueryUserWrapper + } + + /** + * Creates 'SELECT' query. + * + * 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. + */ + public fun createSelectQuery(initializer: SelectQueryCreator): Select + + /** + * Functional interface for creating 'INSERT ... VALUES' query. + * + * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. + * + * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. + * @param QueryUserWrapper User's type with descriptors related to query. + * + * @see CreateModuleScope.createInsertParamsQuery + */ + public interface InsertParamsQueryCreator { + /** + * Scope method that uses [creator] to create a query. + * + * @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. + * + * @see CreateModuleScope.createInsertParamsQuery + */ + public fun createInsert(table: Table, creator: InsertCreator.InsertParams): QueryUserWrapper + } + + /** + * Creates 'INSERT ... VALUES' query. + * + * 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. + */ + public fun createInsertParamsQuery(table: Table, initializer: InsertParamsQueryCreator): Insert.InsertParams + + /** + * Functional interface for creating 'INSERT ... FROM' query. + * + * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. + * + * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. + * @param QueryUserWrapper User's type with descriptors related to query. + * + * @see CreateModuleScope.createInsertFromQueryQuery + */ + public interface InsertFromQueryQueryCreator { + /** + * Scope method that uses [creator] to create a query. + * + * @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. + * + * @see CreateModuleScope.createInsertFromQueryQuery + */ + public fun createInsert(table: Table, creator: InsertCreator.InsertFromQuery): QueryUserWrapper + } + + /** + * Creates 'INSERT ... FROM' query. + * + * 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. + */ + public fun createInsertFromQueryQuery(table: Table, initializer: InsertFromQueryQueryCreator): Insert.InsertFromQuery + + /** + * Functional interface for creating 'UPDATE' query. + * + * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. + * + * @param TableUserExtension User's type with descriptors related to table, whose rows will be updated. + * @param QueryUserWrapper User's type with descriptors related to query. + * + * @see CreateModuleScope.createUpdateQuery + */ + public interface UpdateQueryCreator { + /** + * Scope method that uses [creator] to create a query. + * + * @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. + * + * @see CreateModuleScope.createUpdateQuery + */ + public fun createUpdate(table: Table, creator: ru.landgrafhomyak.serdha.api.v0.dml.UpdateCreator): QueryUserWrapper + } + + /** + * Creates 'UPDATE' query. + * + * 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. + */ + public fun createUpdateQuery(table: Table, initializer: UpdateQueryCreator): Update + + /** + * Functional interface for creating 'DELETE' query. + * + * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. + * + * @param TableUserExtension User's type with descriptors related to table from which data will be deleted. + * @param QueryUserWrapper User's type with descriptors related to query. + * + * @see CreateModuleScope.createDeleteQuery + */ + public interface DeleteQueryCreator { + /** + * Scope method that uses [creator] to create a query. + * + * @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. + * + * @see CreateModuleScope.createDeleteQuery + */ + public fun createDelete(table: Table, creator: ru.landgrafhomyak.serdha.api.v0.dml.DeleteCreator): QueryUserWrapper + } + + /** + * Creates 'DELETE' query. + * + * 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. + */ + public fun createDeleteQuery(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. + * + * @param rootNs Namespace where the new module will be located. + * @param template Schema template. + * @return Module descriptor. + */ + public fun substituteModule(rootNs: Namespace, template: ModuleTemplate): Module +} \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/Module.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/Module.kt index 61b63c3..e6304cf 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/Module.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/Module.kt @@ -14,7 +14,7 @@ public interface Module { @get:JvmName("userExtension") public val userExtension: ModuleUserExtension /** - * Version key internally used for automatically [upgrading modules][ModuleTemplate.Creator.upgradeTemplate]. For debugging. + * Version key internally used for automatically [upgrading modules][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate]. For debugging. */ @Suppress("INAPPLICABLE_JVM_NAME") @get:JvmName("versionKey") diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleCreator.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleCreator.kt deleted file mode 100644 index 9f6b264..0000000 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleCreator.kt +++ /dev/null @@ -1,373 +0,0 @@ -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 - -/** - * Interface providing factory methods for descriptors of tables and queries. - */ -public interface ModuleCreator { - /** - * Functional interface for creating table. - * - * Can be implemented like a companion object that just calls [TableUserExtension]'s constructor with the same or similar signature. - * - * @param TableUserExtension User's type for containing table-related descriptors. - * - * @see ModuleCreator.createTable - * @see ModuleCreator.createSessionScopeTemporaryTable - * @see ModuleCreator.createTransactionScopeTemporaryTable - * @see ModuleCreator.UpdateTable - */ - public interface CreateTable { - /** - * Scope method that uses [creator] to initialize table schema. - * - * @param creator Object with descriptor providers and factories. - * @return User's object with descriptors for future access. - * - * @see ModuleCreator.createTable - * @see ModuleCreator.createSessionScopeTemporaryTable - * @see ModuleCreator.createTransactionScopeTemporaryTable - * @see ModuleCreator.UpdateTable - */ - public fun createTable(creator: TableCreator): TableUserExtension - } - - /** - * 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.Creator.upgradeTemplate] this table must be [kept][ModuleCreator.updateTable] (or [renamed][ModuleCreator.renameTable]) or [deleted][ModuleCreator.deleteTable]. - * - * @param TableUserExtension 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: CreateTable): Table - - /** - * Creates a temporary table that exits only until connection to the database not [closed][SynchronizedDatabase._close]. - * - * On [module upgrading][ModuleTemplate.Creator.upgradeTemplate] must be recreated if needed. - * - * @param TableUserExtension 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: CreateTable): 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.Creator.upgradeTemplate] must be recreated if needed. - * - * @param TableUserExtension 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: CreateTable): Table - - /** - * 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. - * - * @see ModuleCreator.updateTable - * @see ModuleCreator.renameTable - * @see ModuleCreator.updateAndRenameTable - * @see ModuleCreator.CreateTable - */ - public interface UpdateTable { - /** - * Scope method that uses [updater] 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. - * - * @see ModuleCreator.updateTable - * @see ModuleCreator.renameTable - * @see ModuleCreator.updateAndRenameTable - * @see ModuleCreator.CreateTable - */ - public fun updateTable(oldTable: Table, updater: TableUpdater): TableNewUserExtension - } - - - /** - * Marks that table wouldn't be changed in this module version. - * - * @param TableUserExtension 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( - oldTable: Table, - ): Table - - /** - * Renames or moves table without changing its schema. - * - * @param TableUserExtension 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, - newNamespace: Namespace? = null, - newName: String? = null - ): Table - - /** - * Updates table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. - * - * @param TableNewUserExtension User's type with descriptors of updated 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. - * @return New table descriptor. - */ - public fun updateTable( - oldTable: Table, - updater: UpdateTable - ): Table - - - /** - * Both updates table's schema and renames or moves table. - * - * @param TableNewUserExtension User's type with descriptors of updated 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 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. - * @return New table descriptor. - * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. - */ - public fun updateAndRenameTable( - oldTable: Table, - newNamespace: Namespace? = null, - newName: String? = null, - updater: UpdateTable - ): Table - - /** - * Deletes table and all data in it. - * - * @param table Descriptor of table which should be deleted. - */ - public fun deleteTable(table: Table<*, *>) - - /** - * Functional interface for creating 'SELECT' query. - * - * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. - * - * @param QueryUserWrapper User's type with descriptors related to query. - * - * @see ModuleCreator.createSelect - */ - public interface CreateSelect { - /** - * 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. - * - * @see ModuleCreator.createSelect - */ - public fun createSelect(creator: SelectCreator): QueryUserWrapper - } - - /** - * Creates 'SELECT' query. - * - * On [module upgrading][ModuleTemplate.Creator.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. - */ - public fun createSelect(initializer: CreateSelect): Select - - /** - * Functional interface for creating 'INSERT ... VALUES' query. - * - * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. - * - * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. - * @param QueryUserWrapper User's type with descriptors related to query. - * - * @see ModuleCreator.createInsertParams - */ - public interface CreateInsertParams { - /** - * Scope method that uses [creator] to create a query. - * - * @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. - * - * @see ModuleCreator.createInsertParams - */ - public fun createInsert(table: Table, creator: InsertCreator.InsertParams): QueryUserWrapper - } - - /** - * Creates 'INSERT ... VALUES' query. - * - * On [module upgrading][ModuleTemplate.Creator.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. - */ - public fun createInsertParams(table: Table, initializer: CreateInsertParams): Insert.InsertParams - - /** - * Functional interface for creating 'INSERT ... FROM' query. - * - * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. - * - * @param TableUserExtension User's type with descriptors related to table to which values will be inserted. - * @param QueryUserWrapper User's type with descriptors related to query. - * - * @see ModuleCreator.createInsertFromQuery - */ - public interface CreateInsertFromQuery { - /** - * Scope method that uses [creator] to create a query. - * - * @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. - * - * @see ModuleCreator.createInsertFromQuery - */ - public fun createInsert(table: Table, creator: InsertCreator.InsertFromQuery): QueryUserWrapper - } - - /** - * Creates 'INSERT ... FROM' query. - * - * On [module upgrading][ModuleTemplate.Creator.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. - */ - public fun createInsertFromQuery(table: Table, initializer: CreateInsertFromQuery): Insert.InsertFromQuery - - /** - * Functional interface for creating 'UPDATE' query. - * - * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. - * - * @param TableUserExtension User's type with descriptors related to table, whose rows will be updated. - * @param QueryUserWrapper User's type with descriptors related to query. - * - * @see ModuleCreator.createUpdate - */ - public interface CreateUpdate { - /** - * Scope method that uses [creator] to create a query. - * - * @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. - * - * @see ModuleCreator.createUpdate - */ - public fun createUpdate(table: Table, creator: UpdateCreator): QueryUserWrapper - } - - /** - * Creates 'UPDATE' query. - * - * On [module upgrading][ModuleTemplate.Creator.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. - */ - public fun createUpdate(table: Table, initializer: CreateUpdate): Update - - /** - * Functional interface for creating 'DELETE' query. - * - * Can be implemented like a companion object that just calls [QueryUserWrapper]'s constructor with the same or similar signature. - * - * @param TableUserExtension User's type with descriptors related to table from which data will be deleted. - * @param QueryUserWrapper User's type with descriptors related to query. - * - * @see ModuleCreator.createDelete - */ - public interface CreateDelete { - /** - * Scope method that uses [creator] to create a query. - * - * @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. - * - * @see ModuleCreator.createDelete - */ - public fun createDelete(table: Table, creator: DeleteCreator): QueryUserWrapper - } - - /** - * Creates 'DELETE' query. - * - * On [module upgrading][ModuleTemplate.Creator.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. - */ - public fun createDelete(table: Table, initializer: CreateDelete): 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. - * - * @param rootNs Namespace where the new module will be located. - * @param template Schema template. - * @return Module descriptor. - */ - public fun substituteModule(rootNs: Namespace, template: ModuleTemplate): Module - - /** - * 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 template Schema template. - * @return Module descriptor. - */ - public fun upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate): Module -} \ No newline at end of file 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 73da697..038dc18 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 @@ -2,35 +2,33 @@ package ru.landgrafhomyak.serdha.api.v0.ddl.module import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction -public interface ModuleTemplate { +public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> { public interface Provider { - public fun createModuleTemplates(creator: Creator): UserExtension + public fun createModuleTemplates(creator: CreateModuleTemplatesScope): UserExtension } - public interface Creator { + public interface CreateModuleTemplatesScope { public fun createTemplate( versionKey: String, - updater: CreateModule, + updater: ModuleCreator, ): ModuleTemplate public fun upgradeTemplate( versionKey: String, - updater: UpgradeModule, + updater: ModuleUpdater, ): ModuleTemplate } - public interface CreateModule { - public fun createSchema(rootNs: Namespace, creator: ModuleCreator): ModuleUserExtension + public interface ModuleCreator { + public fun createSchema(rootNs: Namespace, creator: CreateModuleScope): ModuleUserExtension public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {} } - public interface UpgradeModule { - public fun upgradeSchema(oldModule: Module, rootNs: Namespace, updater: ModuleCreator): NewModuleUserExtension + public interface ModuleUpdater { + public fun upgradeSchema(oldModule: Module, rootNs: Namespace, updater: CreateModuleScope): NewModuleUserExtension public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {} - - public fun postUpgradeCleanupSchema(ext: NewModuleUserExtension, updater: ModuleCreator) {} } public val versionKey: String 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/UpdateModuleScope.kt new file mode 100644 index 0000000..8278190 --- /dev/null +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/UpdateModuleScope.kt @@ -0,0 +1,130 @@ +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 + */ +public interface UpdateModuleScope : 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. + * + * @see UpdateModuleScope.updateTable + * @see UpdateModuleScope.renameTable + * @see UpdateModuleScope.updateAndRenameTable + * @see UpdateModuleScope.CreateTable + */ + public interface UpdateTable { + /** + * Scope method that uses [updater] 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. + * + * @see UpdateModuleScope.updateTable + * @see UpdateModuleScope.renameTable + * @see UpdateModuleScope.updateAndRenameTable + * @see UpdateModuleScope.CreateTable + */ + public fun updateTable(oldTable: Table, updater: TableUpdater): TableNewUserExtension + } + + + /** + * Marks that table wouldn't be changed in this module version. + * + * @param TableUserExtension 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 + + /** + * Renames or moves table without changing its schema. + * + * @param TableUserExtension 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, + newNamespace: Namespace? = null, + newName: String? = null + ): Table + + /** + * Updates table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. + * + * @param TableNewUserExtension User's type with descriptors of updated 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. + * @return New table descriptor. + */ + public fun updateTable( + oldTable: Table, + updater: UpdateTable + ): Table + + + /** + * Both updates table's schema and renames or moves table. + * + * @param TableNewUserExtension User's type with descriptors of updated 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 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. + * @return New table descriptor. + * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. + */ + public fun updateAndRenameTable( + oldTable: Table, + newNamespace: Namespace? = null, + newName: String? = null, + updater: UpdateTable + ): Table + + /** + * Deletes table and all data in it. + * + * @param table Descriptor of table which should be deleted. + */ + public fun deleteTable(table: 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 template Schema template. + * @return Module descriptor. + */ + public fun upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate): Module +} \ No newline at end of file