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
*/
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 <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].
*
* 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 <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].
*
* 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 <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
@ -73,5 +73,5 @@ public interface CreateModuleScope {
* @param template Schema template.
* @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.
*/
public interface Module<ModuleUserExtension : Any> {
public interface Module<mUE : Any> {
/**
* 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.
*/

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 fun createSchema(rootNs: Namespace, creator: CreateModuleScope): ModuleUserExtension
public fun createSchema(context: CreateModuleScope): ModuleUserExtension
public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {}
}
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) {}
}

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.ModuleUpgrade.upgradeSchema
*/
public interface UpgradeModuleScope : CreateModuleScope {
public interface UpgradeModuleScope<omUE : Any> : 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<TableNewUserExtension : Any, TableOldUserExtension : Any> {
public interface TableUpgrade<tnUE : Any, toUE : Any> {
/**
* 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<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.
*
* @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 <TableUserExtension : Any> keepTable(
table: Table<TableUserExtension, *>,
): Table<TableUserExtension, *>
public fun <tUE : Any> keepTable(
table: Table<tUE, *>,
): Table<tUE, *>
/**
* 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 <TableUserExtension : Any> renameTable(
table: Table<TableUserExtension, *>,
public fun <tUE : Any> renameTable(
table: Table<tUE, *>,
newNamespace: Namespace? = null,
newName: String? = null
): Table<TableUserExtension, *>
): Table<tUE, *>
/**
* 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 <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeTable(
oldTable: Table<TableOldUserExtension, *>,
upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension>
): Table<TableNewUserExtension, TableOldUserExtension>
public fun <tnUE : Any, toUE : Any> upgradeTable(
oldTable: Table<toUE, *>,
upgrade: TableUpgrade<tnUE, toUE>
): Table<tnUE, toUE>
/**
* 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 <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeAndRenameTable(
oldTable: Table<TableNewUserExtension, TableOldUserExtension>,
public fun <tnUE : Any, toUE : Any> upgradeAndRenameTable(
oldTable: Table<tnUE, toUE>,
newNamespace: Namespace? = null,
newName: String? = null,
upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension>
): Table<TableNewUserExtension, TableOldUserExtension>
upgrade: TableUpgrade<tnUE, toUE>
): Table<tnUE, toUE>
/**
* 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 <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.
*
* @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 <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>
}