'Update' -> 'Upgrade' and other minor naming and docs fixes

This commit is contained in:
Andrew Golovashevich 2025-01-03 14:40:11 +03:00
parent 797ab51c58
commit a4f66191c9
3 changed files with 51 additions and 62 deletions

View File

@ -26,7 +26,7 @@ public interface CreateModuleScope {
* @see CreateModuleScope.createTable * @see CreateModuleScope.createTable
* @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable
* @see CreateModuleScope.UpdateTable * @see UpgradeModuleScope.TableUpgrade
*/ */
public interface TableCreator<TableUserExtension : Any> { public interface TableCreator<TableUserExtension : Any> {
/** /**
@ -38,7 +38,7 @@ public interface CreateModuleScope {
* @see CreateModuleScope.createTable * @see CreateModuleScope.createTable
* @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable
* @see CreateModuleScope.UpdateTable * @see UpgradeModuleScope.TableUpgrade
*/ */
public fun createTable(creator: ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator<TableUserExtension>): TableUserExtension public fun createTable(creator: ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator<TableUserExtension>): TableUserExtension
} }
@ -47,7 +47,7 @@ public interface CreateModuleScope {
* 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.
* If table was created by previous synchronizations, asserts that table at the specified path in the database is same as table provided by [initializer]. * 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 TableUserExtension 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.
@ -97,7 +97,7 @@ public interface CreateModuleScope {
* Scope method that uses [creator] to create a query. * Scope method that uses [creator] to create a query.
* *
* @param creator Object with descriptor providers and factories. * @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 * @see CreateModuleScope.createSelectQuery
*/ */
@ -118,7 +118,7 @@ public interface CreateModuleScope {
public fun <QueryUserWrapper : Any> createSelectQuery(initializer: SelectQueryCreator<QueryUserWrapper>): Select<QueryUserWrapper> public fun <QueryUserWrapper : Any> createSelectQuery(initializer: SelectQueryCreator<QueryUserWrapper>): Select<QueryUserWrapper>
/** /**
* 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. * 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. * 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 table Descriptor of table to which values will be inserted.
* @param creator Object with descriptor providers and factories. * @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 * @see CreateModuleScope.createInsertParamsQuery
*/ */
@ -169,7 +169,7 @@ public interface CreateModuleScope {
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertParamsQuery(table: Table<TableUserExtension, *>, initializer: InsertParamsQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertParams<QueryUserWrapper> public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertParamsQuery(table: Table<TableUserExtension, *>, initializer: InsertParamsQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertParams<QueryUserWrapper>
/** /**
* 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. * 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. * 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 table Descriptor of table to which values will be inserted.
* @param creator Object with descriptor providers and factories. * @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 * @see CreateModuleScope.createInsertFromQueryQuery
*/ */
@ -220,7 +220,7 @@ public interface CreateModuleScope {
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertFromQueryQuery(table: Table<TableUserExtension, *>, initializer: InsertFromQueryQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertFromQuery<QueryUserWrapper> public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertFromQueryQuery(table: Table<TableUserExtension, *>, initializer: InsertFromQueryQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertFromQuery<QueryUserWrapper>
/** /**
* 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. * 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. * 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 table Descriptor of table which rows will be updated.
* @param creator Object with descriptor providers and factories. * @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 * @see CreateModuleScope.createUpdateQuery
*/ */
@ -270,7 +270,7 @@ public interface CreateModuleScope {
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createUpdateQuery(table: Table<TableUserExtension, *>, initializer: UpdateQueryCreator<TableUserExtension, QueryUserWrapper>): Update<QueryUserWrapper> public fun <TableUserExtension : Any, QueryUserWrapper : Any> createUpdateQuery(table: Table<TableUserExtension, *>, initializer: UpdateQueryCreator<TableUserExtension, QueryUserWrapper>): Update<QueryUserWrapper>
/** /**
* 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. * 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. * 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 table Descriptor of table from which data will be deleted.
* @param creator Object with descriptor providers and factories. * @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 * @see CreateModuleScope.createDeleteQuery
*/ */
@ -320,8 +320,8 @@ public interface CreateModuleScope {
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createDeleteQuery(table: Table<TableUserExtension, *>, initializer: DeleteQueryCreator<TableUserExtension, QueryUserWrapper>): Delete<QueryUserWrapper> public fun <TableUserExtension : Any, QueryUserWrapper : Any> createDeleteQuery(table: Table<TableUserExtension, *>, initializer: DeleteQueryCreator<TableUserExtension, QueryUserWrapper>): Delete<QueryUserWrapper>
/** /**
* Creates 'DELETE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpdater]. * Creates 'DELETE' 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. * 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. * On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
* *

View File

@ -4,18 +4,18 @@ import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction
public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> { public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> {
public interface Provider<UserExtension : Any> { public interface Provider<UserExtension : Any> {
public fun createModuleTemplates(creator: CreateModuleTemplatesScope): UserExtension public fun createModuleTemplates(scope: CreateModuleTemplatesScope): UserExtension
} }
public interface CreateModuleTemplatesScope { public interface CreateModuleTemplatesScope {
public fun <NewModuleUserExtension : Any> createTemplate( public fun <NewModuleUserExtension : Any> createTemplate(
versionKey: String, versionKey: String,
updater: ModuleCreator<NewModuleUserExtension>, creator: ModuleCreator<NewModuleUserExtension>,
): ModuleTemplate<NewModuleUserExtension> ): ModuleTemplate<NewModuleUserExtension>
public fun <OldModuleUserExtension : Any, NewModuleUserExtension : Any> upgradeTemplate( public fun <OldModuleUserExtension : Any, NewModuleUserExtension : Any> upgradeTemplate(
versionKey: String, versionKey: String,
updater: ModuleUpdater<OldModuleUserExtension, NewModuleUserExtension>, upgrade: ModuleUpgrade<OldModuleUserExtension, NewModuleUserExtension>,
): ModuleTemplate<NewModuleUserExtension> ): ModuleTemplate<NewModuleUserExtension>
} }
@ -25,8 +25,8 @@ public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> {
public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {} public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {}
} }
public interface ModuleUpdater<OldModuleUserExtension : Any, NewModuleUserExtension : Any> { public interface ModuleUpgrade<OldModuleUserExtension : Any, NewModuleUserExtension : Any> {
public fun upgradeSchema(oldModule: Module<OldModuleUserExtension>, rootNs: Namespace, updater: CreateModuleScope): NewModuleUserExtension public fun upgradeSchema(oldModule: Module<OldModuleUserExtension>, rootNs: Namespace, upgrader: CreateModuleScope): NewModuleUserExtension
public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {} public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {}
} }

View File

@ -1,53 +1,42 @@
package ru.landgrafhomyak.serdha.api.v0.ddl.module 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.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.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]. * Scope methods for upgrading [module template][ModuleTemplate].
* *
* @see ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate * @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. * 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 [TableNewUserExtension]'s constructor with the same or similar signature.
* *
* @param TableNewUserExtension User's type with table's descriptors from the previous table version. * @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 UpgradeModuleScope.upgradeTable
* @see UpdateModuleScope.renameTable * @see UpgradeModuleScope.renameTable
* @see UpdateModuleScope.updateAndRenameTable * @see UpgradeModuleScope.upgradeAndRenameTable
* @see UpdateModuleScope.CreateTable * @see UpgradeModuleScope.CreateTable
*/ */
public interface UpdateTable<TableNewUserExtension : Any, TableOldUserExtension : Any> { public interface TableUpgrade<TableNewUserExtension : Any, TableOldUserExtension : Any> {
/** /**
* 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 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 upgrader Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access. * @return User's object with upgraded descriptors for future access.
* *
* @see UpdateModuleScope.updateTable * @see UpgradeModuleScope.upgradeTable
* @see UpdateModuleScope.renameTable * @see UpgradeModuleScope.renameTable
* @see UpdateModuleScope.updateAndRenameTable * @see UpgradeModuleScope.upgradeAndRenameTable
* @see UpdateModuleScope.CreateTable * @see UpgradeModuleScope.CreateTable
*/ */
public fun updateTable(oldTable: Table<TableOldUserExtension, *>, updater: TableUpdater<TableNewUserExtension, TableOldUserExtension>): TableNewUserExtension public fun upgradeTable(oldTable: Table<TableOldUserExtension, *>, upgrader: TableUpdater<TableNewUserExtension, TableOldUserExtension>): TableNewUserExtension
} }
@ -79,37 +68,37 @@ public interface UpdateModuleScope : CreateModuleScope {
): Table<TableUserExtension, *> ): Table<TableUserExtension, *>
/** /**
* 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 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 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. * @return New table descriptor.
*/ */
public fun <TableNewUserExtension : Any, TableOldUserExtension : Any> updateTable( public fun <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeTable(
oldTable: Table<TableOldUserExtension, *>, oldTable: Table<TableOldUserExtension, *>,
updater: UpdateTable<TableNewUserExtension, TableOldUserExtension> upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension>
): Table<TableNewUserExtension, TableOldUserExtension> ): Table<TableNewUserExtension, TableOldUserExtension>
/** /**
* 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 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 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.
* @param updater Object with descriptor providers and factories. * @param upgrade Object with descriptor providers and factories.
* @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> updateAndRenameTable( public fun <TableNewUserExtension : Any, TableOldUserExtension : Any> upgradeAndRenameTable(
oldTable: Table<TableNewUserExtension, TableOldUserExtension>, oldTable: Table<TableNewUserExtension, TableOldUserExtension>,
newNamespace: Namespace? = null, newNamespace: Namespace? = null,
newName: String? = null, newName: String? = null,
updater: UpdateTable<TableNewUserExtension, TableOldUserExtension> upgrade: TableUpgrade<TableNewUserExtension, TableOldUserExtension>
): Table<TableNewUserExtension, TableOldUserExtension> ): Table<TableNewUserExtension, TableOldUserExtension>
/** /**
@ -117,23 +106,23 @@ public interface UpdateModuleScope : CreateModuleScope {
* *
* @param table Descriptor of table which should be deleted. * @param table Descriptor of table which should be deleted.
* *
* @see UpdateModuleScope.deleteTableAfterModuleUpgraded * @see UpgradeModuleScope.deleteTableAfterModuleUpgraded
*/ */
public fun deleteTable(table: Table<*, *>) 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. * [Table's][table] name become free and can be used for another table.
* *
* @param table Descriptor of table which should be deleted. * @param table Descriptor of table which should be deleted.
* *
* @see UpdateModuleScope.deleteTable * @see UpgradeModuleScope.deleteTable
*/ */
public fun deleteTableAfterModuleUpgraded(table: Table<*, *>) 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 TableUserExtension 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.
@ -141,7 +130,7 @@ public interface UpdateModuleScope : CreateModuleScope {
* @param initializer Table-related descriptors initializer. * @param initializer Table-related descriptors initializer.
* @return Table descriptor. * @return Table descriptor.
* *
* @see UpdateModuleScope.deleteTableAfterModuleUpgraded * @see UpgradeModuleScope.deleteTableAfterModuleUpgraded
* @see CreateModuleScope.createTable * @see CreateModuleScope.createTable
* @see CreateModuleScope.createSessionScopeTemporaryTable * @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable * @see CreateModuleScope.createTransactionScopeTemporaryTable