SERDHA/serdha-0-api.kt
1
0
Fork 1
Code Issues 4 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Improvements in module creation interfaces

Browse Source
This commit is contained in:
Andrew Golovashevich 2025-02-02 02:17:03 +03:00
parent f6ab93af4c
commit 5e4e2bdf4a
4 changed files with 44 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/CreateModuleScope.kt
View File

@ -13,7 +13,7 @@ import ru.landgrafhomyak.db.serdha0.api.table.TableConstructor
* @see ModuleTemplate.ModuleCreator.createSchema * @see ModuleTemplate.ModuleCreator.createSchema
*/ */
public interface CreateModuleScope { public interface CreateModuleScope {
public val rootNs: Namespace
/** /**
* Creates table in [specified namespace][namespace] with [specified name][name] and stores it in the database. * 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]. * 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 namespace Way to group tables if there is a lot.
* @param name Name of table for debugging. * @param name Name of table for debugging.
* @param initializer Table-related descriptors initializer. * @param initializer Table-related descriptors initializer.
* @return Table descriptor. * @return Table descriptor.
*/ */
public fun <TableUserExtension : Any> createTable(namespace: Namespace, name: String, initializer: TableConstructor<TableUserExtension>): Table<TableUserExtension, Nothing> public fun <tUE : Any> createTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor<tUE>): Table<tUE, Nothing>
/** /**
* Creates a temporary table that exits only until connection to the database not [closed][SynchronizedDatabase._close]. * 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. * 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 namespace Way to group tables if there is a lot.
* @param name Name of table for debugging. * @param name Name of table for debugging.
* @param initializer Table-related descriptors initializer. * @param initializer Table-related descriptors initializer.
* @return Table descriptor. * @return Table descriptor.
*/ */
public fun <TableUserExtension : Any> createSessionScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor<TableUserExtension>): Table<TableUserExtension, Nothing> public fun <tUE : Any> createSessionScopeTemporaryTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor<tUE>): Table<tUE, Nothing>
/** /**
* Creates a temporary table that exits only inside [transaction][Transaction] and auto-deleted (or cleared, depends on driver implementation) when it [finished][Transaction._assertTransactionFinishedAndReleaseResources]. * 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. * 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 namespace Way to group tables if there is a lot.
* @param name Name of table for debugging. * @param name Name of table for debugging.
* @param initializer Table-related descriptors initializer. * @param initializer Table-related descriptors initializer.
* @return Table descriptor. * @return Table descriptor.
*/ */
public fun <TableUserExtension : Any> createTransactionScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor<TableUserExtension>): Table<TableUserExtension, Nothing> public fun <tUE : Any> createTransactionScopeTemporaryTable(namespace: Namespace = this.rootNs, name: String, initializer: TableConstructor<tUE>): Table<tUE, Nothing>
public val queries: _Query.Constructor.Scope public val queries: _Query.Constructor.Scope
@ -73,5 +73,5 @@ public interface CreateModuleScope {
* @param template Schema template. * @param template Schema template.
* @return Module descriptor. * @return Module descriptor.
*/ */
public fun <ModuleUserExtension : Any> substituteModule(rootNs: Namespace, template: ModuleTemplate<ModuleUserExtension>): Module<ModuleUserExtension> public fun <mUE : Any> substituteModule(rootNs: Namespace, template: ModuleTemplate<mUE>): Module<mUE>
} }

4
src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/Module.kt
View File

@ -6,13 +6,13 @@ import ru.landgrafhomyak.db.serdha0.api.runtime.SynchronizedDatabase
/** /**
* Descriptor of synchronized module. Used for schema manipulations. * Descriptor of synchronized module. Used for schema manipulations.
*/ */
public interface Module<ModuleUserExtension : Any> { public interface Module<mUE : Any> {
/** /**
* Reference user's extension with descriptors related to this module for use in runtime. * Reference user's extension with descriptors related to this module for use in runtime.
*/ */
@Suppress("INAPPLICABLE_JVM_NAME") @Suppress("INAPPLICABLE_JVM_NAME")
@get:JvmName("userExtension") @get:JvmName("userExtension")
public val userExtension: ModuleUserExtension public val uExt: mUE
/** /**
* Version key internally used for automatically [upgrading modules][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate]. For debugging. * Version key internally used for automatically [upgrading modules][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate]. For debugging.
*/ */

4
src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/ModuleTemplate.kt
View File

@ -20,13 +20,13 @@ public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> {
} }
public interface ModuleCreator<ModuleUserExtension : Any> { public interface ModuleCreator<ModuleUserExtension : Any> {
public fun createSchema(rootNs: Namespace, creator: CreateModuleScope): ModuleUserExtension public fun createSchema(context: CreateModuleScope): ModuleUserExtension
public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {} public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {}
} }
public interface ModuleUpgrade<OldModuleUserExtension : Any, NewModuleUserExtension : Any> { public interface ModuleUpgrade<OldModuleUserExtension : Any, NewModuleUserExtension : Any> {
public fun upgradeSchema(oldModule: Module<OldModuleUserExtension>, rootNs: Namespace, upgrader: CreateModuleScope): NewModuleUserExtension public fun upgradeSchema(context: UpgradeModuleScope<OldModuleUserExtension>): NewModuleUserExtension
public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {} public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {}
} }

62
src/commonMain/kotlin/ru/landgrafhomyak/db/serdha0/api/module/UpgradeModuleScope.kt
View File

@ -10,21 +10,23 @@ import ru.landgrafhomyak.db.serdha0.api.table.UpdateTableScope
* @see ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate * @see ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate
* @see ModuleTemplate.ModuleUpgrade.upgradeSchema * @see ModuleTemplate.ModuleUpgrade.upgradeSchema
*/ */
public interface UpgradeModuleScope : CreateModuleScope { public interface UpgradeModuleScope<omUE : Any> : CreateModuleScope {
public val oldModule: omUE
/** /**
* Functional interface for updating 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. * 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 tnUE User's type with table's descriptors from the previous table version.
* @param TableOldUserExtension User's type with descriptors of upgraded table. * @param toUE User's type with descriptors of upgraded table.
* *
* @see UpgradeModuleScope.upgradeTable * @see UpgradeModuleScope.upgradeTable
* @see UpgradeModuleScope.renameTable * @see UpgradeModuleScope.renameTable
* @see UpgradeModuleScope.upgradeAndRenameTable * @see UpgradeModuleScope.upgradeAndRenameTable
* @see UpgradeModuleScope.CreateTable * @see UpgradeModuleScope.CreateTable
*/ */
public interface TableUpgrade<TableNewUserExtension : Any, TableOldUserExtension : Any> { public interface TableUpgrade<tnUE : Any, toUE : Any> {
/** /**
* Scope method that uses [upgrader] to update table schema. * Scope method that uses [upgrader] to update table schema.
* *
@ -37,57 +39,57 @@ public interface UpgradeModuleScope : CreateModuleScope {
* @see UpgradeModuleScope.upgradeAndRenameTable * @see UpgradeModuleScope.upgradeAndRenameTable
* @see UpgradeModuleScope.CreateTable * @see UpgradeModuleScope.CreateTable
*/ */
public fun upgradeTable(oldTable: Table<TableOldUserExtension, *>, upgrader: UpdateTableScope<TableNewUserExtension, TableOldUserExtension>): TableNewUserExtension public fun upgradeTable(oldTable: Table<toUE, *>, upgrader: UpdateTableScope<tnUE, toUE>): tnUE
} }
/** /**
* Marks that table wouldn't be changed in this module version. * 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. * @param oldTable Descriptor of table created in a previous template version.
* @return New table descriptor. * @return New table descriptor.
*/ */
public fun <TableUserExtension : Any> keepTable( public fun <tUE : Any> keepTable(
table: Table<TableUserExtension, *>, table: Table<tUE, *>,
): Table<TableUserExtension, *> ): Table<tUE, *>
/** /**
* Renames or moves table without changing its schema. * 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 table Descriptor to table which should be renamed.
* @param newNamespace New namespace of the table. May be `null` if not changed. * @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 newName New namespace of the table. May be `null` if not changed.
* @return New table descriptor. * @return New table descriptor.
* @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`.
*/ */
public fun <TableUserExtension : Any> renameTable( public fun <tUE : Any> renameTable(
table: Table<TableUserExtension, *>, table: Table<tUE, *>,
newNamespace: Namespace? = null, newNamespace: Namespace? = null,
newName: String? = null newName: String? = null
): Table<TableUserExtension, *> ): Table<tUE, *>
/** /**
* Upgrade 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 upgraded table. * @param tnUE User's type with descriptors of upgraded table.
* @param TableOldUserExtension User's type with table's descriptors from the previous table version. * @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 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. * @param upgrade Object with descriptor providers and factories.
* @return New table descriptor. * @return New table descriptor.
*/ */
public fun <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeTable( public fun <tnUE : Any, toUE : Any> upgradeTable(
oldTable: Table<TableOldUserExtension, *>, oldTable: Table<toUE, *>,
upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension> upgrade: TableUpgrade<tnUE, toUE>
): Table<TableNewUserExtension, TableOldUserExtension> ): Table<tnUE, toUE>
/** /**
* Both upgrade 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 upgraded table. * @param tnUE User's type with descriptors of upgraded table.
* @param TableOldUserExtension User's type with table's descriptors from the previous table version. * @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 oldTable Descriptor of table which should be renamed and upgraded.
* @param newNamespace New namespace of the table. May be `null` if not changed. * @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 newName New namespace of the table. May be `null` if not changed.
@ -95,12 +97,12 @@ public interface UpgradeModuleScope : CreateModuleScope {
* @return New table descriptor. * @return New table descriptor.
* @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`. * @throws IllegalArgumentException If both [newName] and [newNamespace] are same as old or `null`.
*/ */
public fun <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeAndRenameTable( public fun <tnUE : Any, toUE : Any> upgradeAndRenameTable(
oldTable: Table<TableNewUserExtension, TableOldUserExtension>, oldTable: Table<tnUE, toUE>,
newNamespace: Namespace? = null, newNamespace: Namespace? = null,
newName: String? = null, newName: String? = null,
upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension> upgrade: TableUpgrade<tnUE, toUE>
): Table<TableNewUserExtension, TableOldUserExtension> ): Table<tnUE, toUE>
/** /**
* Deletes table and all data in it. * 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]. * 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 namespace Way to group tables if there is a lot.
* @param name Name of table for debugging. * @param name Name of table for debugging.
* @param initializer Table-related descriptors initializer. * @param initializer Table-related descriptors initializer.
@ -136,15 +138,15 @@ public interface UpgradeModuleScope : CreateModuleScope {
* @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable
*/ */
public fun <TableUserExtension : Any> createModuleUpgradeScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor<TableUserExtension>): Table<TableUserExtension, Nothing> public fun <tUE : Any> createModuleUpgradeScopeTemporaryTable(namespace: Namespace, name: String, initializer: TableConstructor<tUE>): Table<tUE, Nothing>
/** /**
* Upgrades [module][oldModule] located at [rootNs] with new schema template. * 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. * @param template Schema template.
* @return Module descriptor. * @return Module descriptor.
*/ */
public fun <ModuleUserExtension : Any> upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate<ModuleUserExtension>): Module<ModuleUserExtension> public fun <smUE : Any> upgradeModule(oldModule: Module<*>, rootNs: Namespace, template: ModuleTemplate<smUE>): Module<smUE>
} }