From bb90e087360139edfd22a7475d74ccd2730bfbf6 Mon Sep 17 00:00:00 2001 From: Andrew Golovashevich Date: Thu, 2 Jan 2025 00:17:03 +0300 Subject: [PATCH] Docs and compatibility 1 --- .../serdha/api/v0/ddl/CheckConstraint.kt | 33 +- .../serdha/api/v0/ddl/Column.kt | 26 ++ .../serdha/api/v0/ddl/ColumnType.kt | 195 +++++++++++- .../serdha/api/v0/ddl/DefaultConstraint.kt | 31 ++ .../serdha/api/v0/ddl/ForeignKey.kt | 82 +++++ .../landgrafhomyak/serdha/api/v0/ddl/Index.kt | 24 ++ .../serdha/api/v0/ddl/Module.kt | 20 +- .../serdha/api/v0/ddl/ModuleCreator.kt | 283 +++++++++++++++++- .../landgrafhomyak/serdha/api/v0/ddl/Table.kt | 1 + 9 files changed, 685 insertions(+), 10 deletions(-) diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/CheckConstraint.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/CheckConstraint.kt index 43fe95d..f2688a7 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/CheckConstraint.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/CheckConstraint.kt @@ -1,10 +1,41 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName import ru.landgrafhomyak.serdha.api.v0.Expression +/** + * Descriptor of 'check' constraint on columns. Used for schema manipulations. + * + * @param TableUserExtension Type of [owner table's][CheckConstraint.table] user expression for static reporting errors when this descriptor passed to wrong table. + */ public interface CheckConstraint { + /** + * Name of constraint for debugging, errors and raw schema access. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("name") public val name: String + + /** + * Table that contains this constraint. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("table") public val table: Table - public val constraint: Expression + + + /** + * Expression used to check data. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("expression") + public val expression: Expression + + + /** + * Set of columns, checked by this constraint. Calculated from [CheckConstraint.expression]. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("affectedColumns") public val affectedColumns: List> } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Column.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Column.kt index c2689e3..681f8f1 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Column.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Column.kt @@ -1,9 +1,35 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName +import ru.landgrafhomyak.serdha.api.v0.dml.SelectedTable + +/** + * Descriptor of data column (of table or query). Used for schema manipulations and [access in queries builder][SelectedTable.selectColumn]. + * + * @param RuntimeType Type in programming language to which database type is converted. + * @param DatabaseType Descriptor of column type on database side. + * @param TableUserExtension Type of [owner's table][Column.table] user expression for static reporting errors when this descriptor passed to wrong table. + */ public interface Column, TableUserExtension : Any> { + /** + * Name of column for debugging, errors and raw schema access. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("name") public val name: String + + /** + * Descriptor of column type on database side. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("type") public val type: DatabaseType + /** + * Table, that contains this column. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("table") public val table: Table } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ColumnType.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ColumnType.kt index e340724..07fdea6 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ColumnType.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ColumnType.kt @@ -1,96 +1,281 @@ package ru.landgrafhomyak.serdha.api.v0.ddl import kotlin.jvm.JvmField +import kotlin.jvm.JvmName import kotlinx.datetime.Instant import kotlinx.datetime.LocalDate import kotlinx.datetime.LocalDateTime import kotlinx.datetime.LocalTime -@OptIn(ExperimentalUnsignedTypes::class) +/** + * Descriptor of a database type. + * + * @param RuntimeType Type in programming language to which database type is converted. + */ @Suppress("ClassName", "RemoveRedundantQualifierName") public interface ColumnType<@Suppress("unused") RuntimeType> { - public val typeName: String + /** + * Name of database type for debugging and errors. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("name") + public val name: String + /** + * Provider of database types descriptors. + */ @Suppress("FunctionName", "PropertyName") public interface Builder { - public fun ROW_ID(): ColumnType> + /** + * Type of internal row id. Can't be casted to types like integers or pointers. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @JvmName("ROW_ID") + public fun ROW_ID(table: Table): ColumnType> + /** + * Descriptor of a boolean type. Fields of this type can contain only 2 values: `true` and `false`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("BOOLEAN") public val BOOLEAN: ColumnType.BOOLEAN + /** + * Descriptor of a signed integer type with size at least 8 bits. Can contain values in range `-128..127`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_S8") public val INT_S8: ColumnType.INT_S8 + /** + * Descriptor of an unsigned integer type with size at least 8 bits. Can contain values in range `0..255`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_U8") public val INT_U8: ColumnType.INT_U8 + /** + * Descriptor of a signed integer type with size at least 16 bits. Can contain values in range `-32768..32767`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_S16") public val INT_S16: ColumnType.INT_S16 + /** + * Descriptor of an unsigned integer type with size at least 16 bits. Can contain values in range `0..65535`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_U16") public val INT_U16: ColumnType.INT_U16 + /** + * Descriptor of a signed integer type with size at least 32 bits. Can contain values in range `-2147483648..2147483647`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_S32") public val INT_S32: ColumnType.INT_S32 + /** + * Descriptor of an unsigned integer type with size at least 32 bits. Can contain values in range `0..4294967295`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_U32") public val INT_U32: ColumnType.INT_U32 + /** + * Descriptor of a signed integer type with size at least 64 bits. Can contain values in range `-9223372036854775808..9223372036854775807`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_S64") public val INT_S64: ColumnType.INT_S64 + /** + * Descriptor of an unsigned integer type with size at least 64 bits. Can contain values in range `0..18446744073709551615`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INT_U64") public val INT_U64: ColumnType.INT_U64 + /** + * Descriptor of a local date type in some format like `(year, month, day)`. Day component can contain values in `1..31`, month in `1..12` and year in `-32768..32767`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("LOCAL_DATE") public val LOCAL_DATE: ColumnType.LOCAL_DATE + /** + * Descriptor of a local time type in some format like `(hour, minute, second)`. Hour component can contain values in `0..23`, minute in `0..59` and second in `0..59`. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("LOCAL_TIME") public val LOCAL_TIME: ColumnType.LOCAL_TIME + /** + * Descriptor of union of types [LOCAL_DATE][ColumnType.Builder.LOCAL_DATE] and [LOCAL_TIME][ColumnType.Builder.LOCAL_TIME]. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("LOCAL_DATETIME") public val LOCAL_DATETIME: ColumnType.LOCAL_DATETIME + /** + * Descriptor of a timestamp type. Can contain values in `-9223372036854775808..9223372036854775807` + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("INSTANT") public val INSTANT: ColumnType.INSTANT + /** + * Descriptor of a single-precision floating-point number with size at least 32 bits. See [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754). + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("FLOAT_32") public val FLOAT_32: ColumnType.FLOAT_32 + /** + * Descriptor of a double-precision floating-point number with size at least 64 bits. See [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754). + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("FLOAT_64") public val FLOAT_64: ColumnType.FLOAT_64 + //todo public val STRING: ColumnType.STRING + + //todo public fun STRING(size: UInt): ColumnType.STRING + //todo public val BYTE_ARRAY: ColumnType.BYTE_ARRAY + + //todo public fun BYTE_ARRAY(size: UInt): ColumnType.BYTE_ARRAY - public fun > nullableOf(d: D): Nullable + + /** + * Returns descriptor of a new type, which can contain all values of [original type][notNullType] or `null` value. + * + * Descriptors of nullable types are returned without any modifications. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @JvmName("nullableOf") + public fun > nullableOf(notNullType: D): Nullable } + // todo public abstract class _VirtualType(@Suppress("MemberVisibilityCanBePrivate") @JvmField public val wraps: ColumnType) - public interface Nullable> : ColumnType + /** + * Descriptor of a nullable database type for static type-checking. + * @see ColumnType.Builder.nullableOf + */ + public interface Nullable> : ColumnType + /** + * Descriptor of an internal row id type for static type-checking. + * @see ColumnType.Builder.ROW_ID + */ public interface ROW_ID : ColumnType> + /** + * Descriptor of a boolean type for static type-checking. + * @see ColumnType.Builder.BOOLEAN + */ public interface BOOLEAN : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_S8 + */ public interface INT_S8 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_U8 + */ public interface INT_U8 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_S16 + */ public interface INT_S16 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_U16 + */ public interface INT_U16 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_S32 + */ public interface INT_S32 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_U32 + */ public interface INT_U32 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_S64 + */ public interface INT_S64 : ColumnType + /** + * Descriptor of an integer type for static type-checking. + * @see ColumnType.Builder.INT_U64 + */ public interface INT_U64 : ColumnType + /** + * Descriptor of a date type for static type-checking. + * @see ColumnType.Builder.LOCAL_DATE + */ public interface LOCAL_DATE : ColumnType + /** + * Descriptor of a time type for static type-checking. + * @see ColumnType.Builder.LOCAL_TIME + */ public interface LOCAL_TIME : ColumnType + /** + * Descriptor of a date-time type for static type-checking. + * @see ColumnType.Builder.LOCAL_DATETIME + */ public interface LOCAL_DATETIME : ColumnType + /** + * Descriptor of a date-time type for static type-checking. + * @see ColumnType.Builder.INSTANT + */ public interface INSTANT : ColumnType + /** + * Descriptor of a floating-point number type for static type-checking. + * @see ColumnType.Builder.FLOAT_32 + */ public interface FLOAT_32 : ColumnType + /** + * Descriptor of a floating-point number type for static type-checking. + * @see ColumnType.Builder.FLOAT_64 + */ public interface FLOAT_64 : ColumnType + /** + * Descriptor of a string type for static type-checking. + * @see ColumnType.Builder.STRING + */ public interface STRING : ColumnType + /** + * Descriptor of a raw binary data type for static type-checking. + * @see ColumnType.Builder.BYTE_ARRAY + */ + @OptIn(ExperimentalUnsignedTypes::class) public interface BYTE_ARRAY : ColumnType } diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/DefaultConstraint.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/DefaultConstraint.kt index 9d24ccb..56cec46 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/DefaultConstraint.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/DefaultConstraint.kt @@ -1,10 +1,41 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName import ru.landgrafhomyak.serdha.api.v0.Expression +/** + * Descriptor of default value attached to [column][Column]. Used for schema manipulations. + * + * @param RuntimeType Type in programming language to which database type is converted. + * @param DatabaseType Descriptor of column type on database side. + * @param TableUserExtension Type of [owner's table][Column.table] user expression for static reporting errors when this descriptor passed to wrong table. + */ public interface DefaultConstraint, TableUserExtension : Any> { + /** + * Name of constraint for debugging, errors and raw schema access. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("name") public val name: String + + /** + * Table, that contains this constraint. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("table") public val table: Table + + /** + * Column which will get value from this constraint if not initialized manually. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("attachedToColumn") public val attachedToColumn: Column + + /** + * Expression used to initialize cell. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("expression") public val expression: Expression } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ForeignKey.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ForeignKey.kt index 17b4ef2..ede502a 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ForeignKey.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ForeignKey.kt @@ -1,26 +1,108 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName import kotlin.jvm.JvmStatic +/** + * Descriptor of a foreign key. Used for schema manipulations. + * + * @param ContainerTableUserExtension Type of [owner table's][ForeignKey.fromTable] user expression for static reporting errors when this descriptor passed to wrong table. + * @param TargetTableUserExtension Type of [target table's][ForeignKey.toTable] user expression for static reporting errors when this descriptor passed to wrong table. + */ public interface ForeignKey { + /** + * Table that contains this foreign key. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("fromTable") public val fromTable: Table + + /** + * Columns in [ForeignKey.fromTable] which are used to reference row in [ForeignKey.toTable]. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("fromColumns") public val fromColumns: List> + + /** + * Table referenced by this foreign key. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("toTable") public val toTable: Table + + /** + * Columns in [ForeignKey.toTable] that are identifying row(s). For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("toColumns") public val toColumns: List> + /** + * Enum of actions to do when value in any of [ForeignKey.toColumns] in referenced row is changed. + */ public enum class OnUpdateAction { + /** + * Don't perform any actions in [ForeignKey.fromColumns]. May break reference. + */ NO_ACTION, + + /** + * Forbids changing values in [ForeignKey.toColumns] if there is at least one reference from [ForeignKey.fromTable]. + */ RESTRICT, + + /** + * Sets `null` value to all columns in [ForeignKey.fromColumns] if any cell in [ForeignKey.toColumns] in referenced row was changed. + * + * All of [ForeignKey.fromColumns] must be nullable. + */ SET_NULL, + + /** + * Sets default value to all columns in [ForeignKey.fromColumns] if any cell in [ForeignKey.toColumns] in referenced row was changed. + * + * All of [ForeignKey.fromColumns] must have [DefaultConstraint]. + */ SET_DEFAULT, + + /** + * Reflects all changes from [ForeignKey.toColumns] to [ForeignKey.fromColumns]. + */ CASCADE } + /** + * Enum of actions to do when referenced row in [ForeignKey.toTable] deleted. + */ public enum class OnDeleteAction { + /** + * Don't perform any actions in [ForeignKey.fromColumns]. Breaks reference. + */ NO_ACTION, + + /** + * Forbids deleting row in [ForeignKey.toTable] if there is at least one reference from [ForeignKey.fromTable]. + */ RESTRICT, + + /** + * Sets `null` value to all columns in [ForeignKey.fromColumns] if referenced row was deleted. + * + * All of [ForeignKey.fromColumns] must be nullable. + */ SET_NULL, + + /** + * Sets default value to all columns in [ForeignKey.fromColumns] if referenced row was deleted. + * + * All of [ForeignKey.fromColumns] must have [DefaultConstraint]. + */ SET_DEFAULT, + + /** + * Deletes all rows in [ForeignKey.fromTable] that are referencing deleted row in [ForeignKey.toTable]. + */ CASCADE } diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Index.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Index.kt index ecb5993..a71d336 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Index.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Index.kt @@ -1,7 +1,31 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName + +/** + * Descriptor of index. Used for schema manipulations. + * + * @param OwnerTableUserExtension Type of [owner table's][CheckConstraint.table] user expression for static reporting errors when this descriptor passed to wrong table. + */ public interface Index { + /** + * Name of index for debugging, errors and raw schema access. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("name") public val name: String + + /** + * Table that contains this index. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("table") public val table: Table + + /** + * Columns that are indexed by this index. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("table") public val columns: List> } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Module.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Module.kt index 60f6ad2..9b9fa12 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Module.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Module.kt @@ -1,11 +1,29 @@ package ru.landgrafhomyak.serdha.api.v0.ddl +import kotlin.jvm.JvmName import ru.landgrafhomyak.serdha.api.v0.runtime.SynchronizedDatabase +/** + * Descriptor of synchronized module. Used for schema manipulations. + */ public interface Module { + /** + * 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 - + /** + * Version key internally used for automatically [upgrading modules][ModuleTemplate.Creator.upgradeTemplate]. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("versionKey") public val versionKey: String + /** + * Database in which this module was synchronized. For debugging. + */ + @Suppress("INAPPLICABLE_JVM_NAME") + @get:JvmName("ownerDatabase") public val ownerDatabase: SynchronizedDatabase<*> } \ No newline at end of file diff --git a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ModuleCreator.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ModuleCreator.kt index 17cb361..b222e18 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ModuleCreator.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/ModuleCreator.kt @@ -8,81 +8,358 @@ 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 initializer Table-related descriptors initializer. + * @return Table descriptor. + */ + // todo name public fun createSessionScopeTemporaryTable(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 initializer Table-related descriptors initializer. + * @return Table descriptor. + */ + // todo name public fun createTransactionScopeTemporaryTable(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 } + // todo keep table + + /** + * Updates table's descriptors without changing its [name][Table.name] or [namespace][Table.namespacesFromModuleRoot]. + * + * @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 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, - initializer: UpdateTable + updater: UpdateTable ): Table + // todo collapse public fun renameTable( table: Table, newName: String ): Table + /** + * Renames or moves table without changing its schema. + * + * @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 table Descriptor to table which should be renamed. + * @param newNamespace New namespace of the table. Can be the same as old. + * @param newName New namespace of the table. Can be the same as old. + * @return New table descriptor. + */ public fun renameTable( table: Table, newNamespace: Namespace, newName: String ): Table + // todo collapse public fun updateAndRenameTable( table: Table, newName: String, initializer: UpdateTable ): Table + /** + * Both updates table schema and renames or moves table. + * + * @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 oldTable Descriptor to table which should be renamed. + * @param newNamespace New namespace of the table. Can be the same as old. + * @param newName New namespace of the table. Can be the same as old. + * @return New table descriptor. + */ public fun updateAndRenameTable( - table: Table, + oldTable: Table, newNamespace: Namespace, newName: String, - initializer: UpdateTable + updater: UpdateTable ): Table + // todo table deletion and remove `createTempTable` public fun createTempTable(namespace: Namespace, name: String, initializer: CreateTable): 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/Table.kt b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Table.kt index 9b7dbaa..29e0a5c 100644 --- a/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Table.kt +++ b/src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/Table.kt @@ -12,5 +12,6 @@ public interface Table { public val temporaryType: TemporaryType? + // todo make nullable for temp tables public val namespacesFromModuleRoot: List } \ No newline at end of file