From 35d43abc4b2cd14b8b5c9352efb7ff43c58a0444 Mon Sep 17 00:00:00 2001
From: Fabrice Lecomte <fabrice.lecomte.be@gmail.com>
Date: Sat, 17 Jul 2021 23:42:55 +0200
Subject: [PATCH] Add documentation on methods

---
 .../kotlin/fr/postgresjson/connexion/Connection.kt   | 10 +++++++++-
 .../fr/postgresjson/connexion/EmbedExecutable.kt     | 11 ++++++++++-
 .../kotlin/fr/postgresjson/connexion/Executable.kt   | 12 ++++++++++++
 .../kotlin/fr/postgresjson/connexion/Function.kt     |  6 ++++++
 src/main/kotlin/fr/postgresjson/connexion/Query.kt   |  6 ++++++
 5 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/main/kotlin/fr/postgresjson/connexion/Connection.kt b/src/main/kotlin/fr/postgresjson/connexion/Connection.kt
index fdb4bb1..c716ecb 100644
--- a/src/main/kotlin/fr/postgresjson/connexion/Connection.kt
+++ b/src/main/kotlin/fr/postgresjson/connexion/Connection.kt
@@ -182,6 +182,9 @@ class Connection(
         }
     }
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(sql: String, values: List<Any?>): Int {
         val compiledValues = compileArgs(values)
         return stopwatchQuery(sql, compiledValues) {
@@ -191,6 +194,9 @@ class Connection(
         }
     }
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(sql: String, values: Map<String, Any?>): Int {
         return replaceArgs(sql, values) {
             sendQuery(this.sql, this.parameters)
@@ -224,9 +230,11 @@ class Connection(
     }
 
     private fun <T> replaceArgsIntoSql(sql: String, values: List<Any?>, block: (String) -> T): T {
-        val paramRegex = "(?<!\\?)(\\?)(?!\\?)".toRegex(RegexOption.IGNORE_CASE)
+        /* The regular expression matches a question mark "?" alone, not preceded or followed by another question mark */
+        val paramRegex = """(?<!\?)(\?)(?!\?)""".toRegex(RegexOption.IGNORE_CASE)
         var i = 0
         if (values.isNotEmpty()) {
+            /* for each question mark, replace by the value */
             val newSql = paramRegex.replace(sql) {
                 values[i] ?: queryError("Parameter $i missing", sql, values)
                 val valToReplace = values[i].toString()
diff --git a/src/main/kotlin/fr/postgresjson/connexion/EmbedExecutable.kt b/src/main/kotlin/fr/postgresjson/connexion/EmbedExecutable.kt
index c34cdd4..6ec42b2 100644
--- a/src/main/kotlin/fr/postgresjson/connexion/EmbedExecutable.kt
+++ b/src/main/kotlin/fr/postgresjson/connexion/EmbedExecutable.kt
@@ -104,7 +104,7 @@ sealed interface EmbedExecutable {
     ): Paginated<R> =
         select(page, limit, typeReference, values.toMap(), block)
 
-    fun exec(values: List<Any?> = emptyList()): QueryResult
+    fun exec(values: List<Any?>): QueryResult
     fun exec(values: Map<String, Any?>): QueryResult
     fun exec(vararg values: Pair<String, Any?>): QueryResult = exec(values.toMap())
 
@@ -112,7 +112,16 @@ sealed interface EmbedExecutable {
     fun perform(values: Map<String, Any?>) { exec(values) }
     fun perform(vararg values: Pair<String, Any?>) = perform(values.toMap())
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(values: List<Any?>): Int
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(values: Map<String, Any?>): Int
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(vararg values: Pair<String, Any?>): Int = sendQuery(values.toMap())
 }
diff --git a/src/main/kotlin/fr/postgresjson/connexion/Executable.kt b/src/main/kotlin/fr/postgresjson/connexion/Executable.kt
index b7488db..9114661 100644
--- a/src/main/kotlin/fr/postgresjson/connexion/Executable.kt
+++ b/src/main/kotlin/fr/postgresjson/connexion/Executable.kt
@@ -122,8 +122,20 @@ interface Executable {
     fun perform(sql: String, values: Map<String, Any?>) { exec(sql, values) }
     fun perform(sql: String, vararg values: Pair<String, Any?>) = perform(sql, values.toMap())
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun <R : EntityI> sendQuery(sql: String, value: R): Int = sendQuery(sql, listOf(value))
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(sql: String, values: List<Any?> = emptyList()): Int
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(sql: String, values: Map<String, Any?>): Int
+    /**
+     * Warning: this method not use prepared statement
+     */
     fun sendQuery(sql: String, vararg values: Pair<String, Any?>): Int = sendQuery(sql, values.toMap())
 }
diff --git a/src/main/kotlin/fr/postgresjson/connexion/Function.kt b/src/main/kotlin/fr/postgresjson/connexion/Function.kt
index 867091e..d110c67 100644
--- a/src/main/kotlin/fr/postgresjson/connexion/Function.kt
+++ b/src/main/kotlin/fr/postgresjson/connexion/Function.kt
@@ -82,11 +82,17 @@ class Function(val definition: Function, override val connection: Connection) :
 
     override fun exec(values: Map<String, Any?>): QueryResult = connection.exec(compileSql(values), values)
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(values: List<Any?>): Int {
         exec(values)
         return 0
     }
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(values: Map<String, Any?>): Int {
         exec(values)
         return 0
diff --git a/src/main/kotlin/fr/postgresjson/connexion/Query.kt b/src/main/kotlin/fr/postgresjson/connexion/Query.kt
index fc3e1ae..b4a246f 100644
--- a/src/main/kotlin/fr/postgresjson/connexion/Query.kt
+++ b/src/main/kotlin/fr/postgresjson/connexion/Query.kt
@@ -73,7 +73,13 @@ class Query(override val name: String, private val sql: String, override val con
 
     override fun exec(values: Map<String, Any?>): QueryResult = connection.exec(sql, values)
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(values: List<Any?>): Int = connection.sendQuery(sql, values)
 
+    /**
+     * Warning: this method not use prepared statement
+     */
     override fun sendQuery(values: Map<String, Any?>): Int = connection.sendQuery(sql, values)
 }