Review issues: add KDoc to the FunctionProvider::merge(), FunctionPro…

…vider::mergeSelect() functions; rename MergeBaseStatement to MergeStatement
JetBrains · May 14, 2024 · 97904ef · 97904ef
1 parent 4f6dce3
commit 97904ef
Show file tree

Hide file tree

Showing 7 changed files with 70 additions and 50 deletions.
diff --git a/exposed-core/api/exposed-core.api b/exposed-core/api/exposed-core.api
@@ -3007,55 +3007,55 @@ public class org/jetbrains/exposed/sql/statements/InsertStatement : org/jetbrain
 	public static synthetic fun valuesAndDefaults$default (Lorg/jetbrains/exposed/sql/statements/InsertStatement;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/Map;
 }
 
-public abstract class org/jetbrains/exposed/sql/statements/MergeBaseStatement : org/jetbrains/exposed/sql/statements/Statement {
+public final class org/jetbrains/exposed/sql/statements/MergeSelectStatement : org/jetbrains/exposed/sql/statements/MergeStatement {
+	public fun <init> (Lorg/jetbrains/exposed/sql/Table;Lorg/jetbrains/exposed/sql/QueryAlias;Lorg/jetbrains/exposed/sql/Op;)V
+	public final fun getOn ()Lorg/jetbrains/exposed/sql/Op;
+	public fun prepareSQL (Lorg/jetbrains/exposed/sql/Transaction;Z)Ljava/lang/String;
+}
+
+public abstract class org/jetbrains/exposed/sql/statements/MergeStatement : org/jetbrains/exposed/sql/statements/Statement {
 	public fun <init> (Lorg/jetbrains/exposed/sql/Table;)V
 	public fun arguments ()Ljava/lang/Iterable;
 	public fun executeInternal (Lorg/jetbrains/exposed/sql/statements/api/PreparedStatementApi;Lorg/jetbrains/exposed/sql/Transaction;)Ljava/lang/Integer;
 	public synthetic fun executeInternal (Lorg/jetbrains/exposed/sql/statements/api/PreparedStatementApi;Lorg/jetbrains/exposed/sql/Transaction;)Ljava/lang/Object;
 	public final fun getTable ()Lorg/jetbrains/exposed/sql/Table;
 	protected final fun getWhenBranches ()Ljava/util/List;
 	public final fun whenMatchedDelete (Lorg/jetbrains/exposed/sql/Op;)V
-	public static synthetic fun whenMatchedDelete$default (Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement;Lorg/jetbrains/exposed/sql/Op;ILjava/lang/Object;)V
+	public static synthetic fun whenMatchedDelete$default (Lorg/jetbrains/exposed/sql/statements/MergeStatement;Lorg/jetbrains/exposed/sql/Op;ILjava/lang/Object;)V
 	public final fun whenMatchedUpdate (Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;)V
-	public static synthetic fun whenMatchedUpdate$default (Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
+	public static synthetic fun whenMatchedUpdate$default (Lorg/jetbrains/exposed/sql/statements/MergeStatement;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public final fun whenNotMatchedInsert (Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;)V
-	public static synthetic fun whenNotMatchedInsert$default (Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement;Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
+	public static synthetic fun whenNotMatchedInsert$default (Lorg/jetbrains/exposed/sql/statements/MergeStatement;Lorg/jetbrains/exposed/sql/Op;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 }
 
-public final class org/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction : java/lang/Enum {
-	public static final field DELETE Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
-	public static final field INSERT Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
-	public static final field UPDATE Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
+public final class org/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction : java/lang/Enum {
+	public static final field DELETE Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
+	public static final field INSERT Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
+	public static final field UPDATE Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
 	public static fun getEntries ()Lkotlin/enums/EnumEntries;
-	public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
-	public static fun values ()[Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
+	public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
+	public static fun values ()[Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
 }
 
-public final class org/jetbrains/exposed/sql/statements/MergeBaseStatement$WhenBranchData {
-	public fun <init> (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;)V
-	public synthetic fun <init> (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+public final class org/jetbrains/exposed/sql/statements/MergeStatement$WhenBranchData {
+	public fun <init> (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;)V
+	public synthetic fun <init> (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/util/List;
-	public final fun component2 ()Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
+	public final fun component2 ()Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
 	public final fun component3 ()Lorg/jetbrains/exposed/sql/Op;
 	public final fun component4 ()Lorg/jetbrains/exposed/sql/Op;
-	public final fun copy (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;)Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$WhenBranchData;
-	public static synthetic fun copy$default (Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$WhenBranchData;Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;ILjava/lang/Object;)Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$WhenBranchData;
+	public final fun copy (Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;)Lorg/jetbrains/exposed/sql/statements/MergeStatement$WhenBranchData;
+	public static synthetic fun copy$default (Lorg/jetbrains/exposed/sql/statements/MergeStatement$WhenBranchData;Ljava/util/List;Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;Lorg/jetbrains/exposed/sql/Op;Lorg/jetbrains/exposed/sql/Op;ILjava/lang/Object;)Lorg/jetbrains/exposed/sql/statements/MergeStatement$WhenBranchData;
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getAction ()Lorg/jetbrains/exposed/sql/statements/MergeBaseStatement$MergeWhenAction;
+	public final fun getAction ()Lorg/jetbrains/exposed/sql/statements/MergeStatement$MergeWhenAction;
 	public final fun getAnd ()Lorg/jetbrains/exposed/sql/Op;
 	public final fun getArguments ()Ljava/util/List;
 	public final fun getDeleteWhere ()Lorg/jetbrains/exposed/sql/Op;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class org/jetbrains/exposed/sql/statements/MergeSelectStatement : org/jetbrains/exposed/sql/statements/MergeBaseStatement {
-	public fun <init> (Lorg/jetbrains/exposed/sql/Table;Lorg/jetbrains/exposed/sql/QueryAlias;Lorg/jetbrains/exposed/sql/Op;)V
-	public final fun getOn ()Lorg/jetbrains/exposed/sql/Op;
-	public fun prepareSQL (Lorg/jetbrains/exposed/sql/Transaction;Z)Ljava/lang/String;
-}
-
-public class org/jetbrains/exposed/sql/statements/MergeTableStatement : org/jetbrains/exposed/sql/statements/MergeBaseStatement {
+public class org/jetbrains/exposed/sql/statements/MergeTableStatement : org/jetbrains/exposed/sql/statements/MergeStatement {
 	public fun <init> (Lorg/jetbrains/exposed/sql/Table;Lorg/jetbrains/exposed/sql/Table;Lorg/jetbrains/exposed/sql/Op;)V
 	public fun prepareSQL (Lorg/jetbrains/exposed/sql/Transaction;Z)Ljava/lang/String;
 }

diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/statements/MergeSelectStatement.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/statements/MergeSelectStatement.kt
@@ -10,7 +10,7 @@ import org.jetbrains.exposed.sql.Transaction
  * or deletions.
  *
  * Here is only the part specific for the Query as a source implementation.
- * Look into [MergeBaseStatement] to find the base implementation of that command.
+ * Look into [MergeStatement] to find the base implementation of that command.
  *
  * @property dest The destination [Table] where records will be merged into.
  * @property selectQuery The source [QueryAlias] from which records are taken to compare with `dest`.
@@ -20,7 +20,7 @@ class MergeSelectStatement(
     dest: Table,
     private val selectQuery: QueryAlias,
     val on: Op<Boolean>
-) : MergeBaseStatement(dest) {
+) : MergeStatement(dest) {
     override fun prepareSQL(transaction: Transaction, prepared: Boolean): String {
         return transaction.db.dialect.functionProvider.mergeSelect(table, selectQuery, transaction, whenBranches, on, prepared)
     }

diff --git a/...osed/sql/statements/MergeBaseStatement.kt → .../exposed/sql/statements/MergeStatement.kt b/...osed/sql/statements/MergeBaseStatement.kt → .../exposed/sql/statements/MergeStatement.kt
@@ -8,7 +8,7 @@ import org.jetbrains.exposed.sql.statements.api.PreparedStatementApi
  *
  * @property table The destination [Table] where records will be merged into.
  */
-abstract class MergeBaseStatement(val table: Table) : Statement<Int>(
+abstract class MergeStatement(val table: Table) : Statement<Int>(
     StatementType.MERGE, listOf(table)
 ) {
     protected val whenBranches = mutableListOf<WhenBranchData>()

diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/statements/MergeTableStatement.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/statements/MergeTableStatement.kt
@@ -9,7 +9,7 @@ import org.jetbrains.exposed.sql.Transaction
  * or deletions.
  *
  * Here is only the part specific for the Table as a source implementation.
- * Look into [MergeBaseStatement] to find the base implementation of that command.
+ * Look into [MergeStatement] to find the base implementation of that command.
  *
  * @property dest The destination [Table] where records will be merged into.
  * @property source The source [Table] from which records are taken to compare with `dest`.
@@ -19,7 +19,7 @@ open class MergeTableStatement(
     dest: Table,
     private val source: Table,
     private val on: Op<Boolean>?
-) : MergeBaseStatement(dest) {
+) : MergeStatement(dest) {
     override fun prepareSQL(transaction: Transaction, prepared: Boolean): String {
         val result = transaction.db.dialect.functionProvider.merge(table, source, transaction, whenBranches, on)
         return result

diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/FunctionProvider.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/FunctionProvider.kt
@@ -3,7 +3,7 @@ package org.jetbrains.exposed.sql.vendors
 import org.jetbrains.exposed.exceptions.UnsupportedByDialectException
 import org.jetbrains.exposed.exceptions.throwUnsupportedException
 import org.jetbrains.exposed.sql.*
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement
+import org.jetbrains.exposed.sql.statements.MergeStatement
 
 /**
  * Provides definitions for all the supported SQL functions.
@@ -439,11 +439,21 @@ abstract class FunctionProvider {
         return "INSERT INTO ${transaction.identity(table)} $columnsExpr $valuesExpr"
     }
 
+    /**
+     * Generates the SQL MERGE command which synchronizes two datasets by inserting new rows,
+     * or updating/deleting existing ones in the target table based on data from another table.
+     *
+     * @param dest The table that will be modified.
+     * @param source The table providing the data for modification.
+     * @param transaction The transaction in which the operation will be executed.
+     * @param whenBranches A list of `MergeStatement.WhenBranchData` instances describing the `when` clauses of the SQL command.
+     * @param on The condition that determines whether to apply insertions or updates/deletions.
+     */
     open fun merge(
         dest: Table,
         source: Table,
         transaction: Transaction,
-        whenBranches: List<MergeBaseStatement.WhenBranchData>,
+        whenBranches: List<MergeStatement.WhenBranchData>,
         on: Op<Boolean>?
     ): String {
         if (whenBranches.any { it.deleteWhere != null } && currentDialect !is OracleDialect) {
@@ -472,11 +482,21 @@ abstract class FunctionProvider {
         }
     }
 
+    /**
+     * Generates the SQL MERGE command which synchronizes two datasets by inserting new rows,
+     * or updating/deleting existing ones in the target table based on data from subquery.
+     *
+     * @param dest The table that will be modified.
+     * @param source The query providing the data for modification.
+     * @param transaction The transaction in which the operation will be executed.
+     * @param whenBranches A list of `MergeStatement.WhenBranchData` instances describing the `when` clauses of the SQL command.
+     * @param on The condition that determines whether to apply insertions or updates/deletions.
+     */
     open fun mergeSelect(
         dest: Table,
         source: QueryAlias,
         transaction: Transaction,
-        whenBranches: List<MergeBaseStatement.WhenBranchData>,
+        whenBranches: List<MergeStatement.WhenBranchData>,
         on: Op<Boolean>,
         prepared: Boolean
     ): String {
@@ -820,7 +840,7 @@ abstract class FunctionProvider {
 }
 
 @Suppress("NestedBlockDepth")
-private fun QueryBuilder.addWhenBranchesToMergeStatement(transaction: Transaction, table: Table, whenBranches: List<MergeBaseStatement.WhenBranchData>) {
+private fun QueryBuilder.addWhenBranchesToMergeStatement(transaction: Transaction, table: Table, whenBranches: List<MergeStatement.WhenBranchData>) {
     fun QueryBuilder.appendValueAlias(column: Column<*>, value: Any?) {
         when (value) {
             is Column<*> -> {
@@ -841,7 +861,7 @@ private fun QueryBuilder.addWhenBranchesToMergeStatement(transaction: Transactio
 
     whenBranches.forEach { (arguments, action, condition, deleteWhere) ->
         when (action) {
-            MergeBaseStatement.MergeWhenAction.INSERT -> {
+            MergeStatement.MergeWhenAction.INSERT -> {
                 val nextValExpression = autoIncColumn?.autoIncColumnType?.nextValExpression?.takeIf { autoIncColumn !in arguments.map { it.first } }
 
                 val extraArg = if (nextValExpression != null) listOf(autoIncColumn to nextValExpression) else emptyList()
@@ -863,7 +883,7 @@ private fun QueryBuilder.addWhenBranchesToMergeStatement(transaction: Transactio
                 }
             }
 
-            MergeBaseStatement.MergeWhenAction.UPDATE -> {
+            MergeStatement.MergeWhenAction.UPDATE -> {
                 +"WHEN MATCHED "
                 if (currentDialect !is OracleDialect) {
                     condition?.let { append("AND ($condition) ") }
@@ -881,7 +901,7 @@ private fun QueryBuilder.addWhenBranchesToMergeStatement(transaction: Transactio
                 }
             }
 
-            MergeBaseStatement.MergeWhenAction.DELETE -> {
+            MergeStatement.MergeWhenAction.DELETE -> {
                 +"WHEN MATCHED "
                 condition?.let { append("AND ($condition) ") }
                 +"THEN DELETE "

diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/OracleDialect.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/OracleDialect.kt
@@ -2,10 +2,10 @@ package org.jetbrains.exposed.sql.vendors
 
 import org.jetbrains.exposed.exceptions.throwUnsupportedException
 import org.jetbrains.exposed.sql.*
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.DELETE
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.INSERT
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.UPDATE
+import org.jetbrains.exposed.sql.statements.MergeStatement
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.DELETE
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.INSERT
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.UPDATE
 import org.jetbrains.exposed.sql.transactions.TransactionManager
 import java.sql.DatabaseMetaData
 import java.util.*
@@ -311,7 +311,7 @@ internal object OracleFunctionProvider : FunctionProvider() {
         )
     }
 
-    override fun merge(dest: Table, source: Table, transaction: Transaction, whenBranches: List<MergeBaseStatement.WhenBranchData>, on: Op<Boolean>?): String {
+    override fun merge(dest: Table, source: Table, transaction: Transaction, whenBranches: List<MergeStatement.WhenBranchData>, on: Op<Boolean>?): String {
         validateMergeCommandWhenBranches(transaction, whenBranches)
         return super.merge(dest, source, transaction, whenBranches, on)
     }
@@ -320,7 +320,7 @@ internal object OracleFunctionProvider : FunctionProvider() {
         dest: Table,
         source: QueryAlias,
         transaction: Transaction,
-        whenBranches: List<MergeBaseStatement.WhenBranchData>,
+        whenBranches: List<MergeStatement.WhenBranchData>,
         on: Op<Boolean>,
         prepared: Boolean
     ): String {
@@ -329,7 +329,7 @@ internal object OracleFunctionProvider : FunctionProvider() {
     }
 }
 
-private fun validateMergeCommandWhenBranches(transaction: Transaction, whenBranches: List<MergeBaseStatement.WhenBranchData>) {
+private fun validateMergeCommandWhenBranches(transaction: Transaction, whenBranches: List<MergeStatement.WhenBranchData>) {
     when {
         whenBranches.count { it.action == INSERT } > 1 ->
             transaction.throwUnsupportedException("Multiple insert clauses are not supported by DB.")

diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/SQLServerDialect.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/vendors/SQLServerDialect.kt
@@ -2,10 +2,10 @@ package org.jetbrains.exposed.sql.vendors
 
 import org.jetbrains.exposed.exceptions.throwUnsupportedException
 import org.jetbrains.exposed.sql.*
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.DELETE
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.INSERT
-import org.jetbrains.exposed.sql.statements.MergeBaseStatement.MergeWhenAction.UPDATE
+import org.jetbrains.exposed.sql.statements.MergeStatement
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.DELETE
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.INSERT
+import org.jetbrains.exposed.sql.statements.MergeStatement.MergeWhenAction.UPDATE
 import org.jetbrains.exposed.sql.transactions.TransactionManager
 import java.util.*
 
@@ -251,7 +251,7 @@ internal object SQLServerFunctionProvider : FunctionProvider() {
         )
     }
 
-    override fun merge(dest: Table, source: Table, transaction: Transaction, whenBranches: List<MergeBaseStatement.WhenBranchData>, on: Op<Boolean>?): String {
+    override fun merge(dest: Table, source: Table, transaction: Transaction, whenBranches: List<MergeStatement.WhenBranchData>, on: Op<Boolean>?): String {
         validateMergeCommandWhenBranches(transaction, whenBranches)
         return super.merge(dest, source, transaction, whenBranches, on) + ";"
     }
@@ -260,7 +260,7 @@ internal object SQLServerFunctionProvider : FunctionProvider() {
         dest: Table,
         source: QueryAlias,
         transaction: Transaction,
-        whenBranches: List<MergeBaseStatement.WhenBranchData>,
+        whenBranches: List<MergeStatement.WhenBranchData>,
         on: Op<Boolean>,
         prepared: Boolean
     ): String {
@@ -269,7 +269,7 @@ internal object SQLServerFunctionProvider : FunctionProvider() {
     }
 }
 
-private fun validateMergeCommandWhenBranches(transaction: Transaction, whenBranches: List<MergeBaseStatement.WhenBranchData>) {
+private fun validateMergeCommandWhenBranches(transaction: Transaction, whenBranches: List<MergeStatement.WhenBranchData>) {
     when {
         whenBranches.count { it.action == INSERT } > 1 ->
             transaction.throwUnsupportedException("Multiple insert clauses are not supported by DB")