kotlin: add Query class to support timeout and cancellation (#368)

There's now a `sqlc.runtime` package containing a few abstract classes implemented by the each query method. The query methods now return these intermediate classes rather than executing the query directly. You have to now explicitly call `.execute()` on the return value. I don't really like this level of indirection, but it now makes it possible to set timeouts at the per-query level, and allows queries to be canceled. It also opens up the possibility of "interceptors" for query objects that can be used to apply additional common code.

Co-authored-by: Kyle Conroy <kyle@conroy.org>

Author: mightyguava

examples/kotlin/README.md

@@ -5,6 +5,7 @@ This is a Kotlin gradle project configured to compile and test all examples. Cur
 To run tests:
 
 ```shell script
+docker run --name dinosql-postgres -d -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=postgres -p 5432:5432 postgres:11
 ./gradlew clean test
 ```
 

examples/kotlin/build.gradle

@@ -12,8 +12,8 @@ repositories {
 dependencies {
     implementation 'org.postgresql:postgresql:42.2.9'
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
-    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.3.1'
-    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.3.1'
+    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.0'
+    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.6.0'
 }
 
 test {

examples/kotlin/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 #Sat Jan 25 10:45:34 EST 2020
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.2.1-all.zip
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStorePath=wrapper/dists

examples/kotlin/src/main/kotlin/com/example/authors/Queries.kt

@@ -5,18 +5,22 @@ package com.example.authors
 import java.sql.Connection
 import java.sql.SQLException
 
+import sqlc.runtime.ExecuteQuery
+import sqlc.runtime.ListQuery
+import sqlc.runtime.RowQuery
+
 interface Queries {
   @Throws(SQLException::class)
-  fun createAuthor(name: String, bio: String?): Author
+  fun createAuthor(name: String, bio: String?): RowQuery<Author>
 
   @Throws(SQLException::class)
-  fun deleteAuthor(id: Long)
+  fun deleteAuthor(id: Long): ExecuteQuery
 
   @Throws(SQLException::class)
-  fun getAuthor(id: Long): Author
+  fun getAuthor(id: Long): RowQuery<Author>
 
   @Throws(SQLException::class)
-  fun listAuthors(): List<Author>
+  fun listAuthors(): ListQuery<Author>
 
 }
 

examples/kotlin/src/main/kotlin/com/example/authors/QueriesImpl.kt

@@ -5,6 +5,10 @@ package com.example.authors
 import java.sql.Connection
 import java.sql.SQLException
 
+import sqlc.runtime.ExecuteQuery
+import sqlc.runtime.ListQuery
+import sqlc.runtime.RowQuery
+
 const val createAuthor = """-- name: createAuthor :one
 INSERT INTO authors (
           name, bio
@@ -32,71 +36,91 @@ ORDER BY name
 class QueriesImpl(private val conn: Connection) : Queries {
 
   @Throws(SQLException::class)
-  override fun createAuthor(name: String, bio: String?): Author {
-    return conn.prepareStatement(createAuthor).use { stmt ->
-      stmt.setString(1, name)
-      stmt.setString(2, bio)
-
-      val results = stmt.executeQuery()
-      if (!results.next()) {
-        throw SQLException("no rows in result set")
-      }
-      val ret = Author(
-            results.getLong(1),
-            results.getString(2),
-            results.getString(3)
-        )
-      if (results.next()) {
-          throw SQLException("expected one row in result set, but got many")
+  override fun createAuthor(name: String, bio: String?): RowQuery<Author> {
+    return object : RowQuery<Author>() {
+      override fun execute(): Author {
+        return conn.prepareStatement(createAuthor).use { stmt ->
+          this.statement = stmt
+          stmt.setString(1, name)
+          stmt.setString(2, bio)
+
+          val results = stmt.executeQuery()
+          if (!results.next()) {
+            throw SQLException("no rows in result set")
+          }
+          val ret = Author(
+                results.getLong(1),
+                results.getString(2),
+                results.getString(3)
+            )
+          if (results.next()) {
+              throw SQLException("expected one row in result set, but got many")
+          }
+          ret
+        }
       }
-      ret
     }
   }
 
   @Throws(SQLException::class)
-  override fun deleteAuthor(id: Long) {
-    conn.prepareStatement(deleteAuthor).use { stmt ->
-      stmt.setLong(1, id)
-
-      stmt.execute()
+  override fun deleteAuthor(id: Long): ExecuteQuery {
+    return object : ExecuteQuery() {
+      override fun execute() {
+        conn.prepareStatement(deleteAuthor).use { stmt ->
+          this.statement = stmt
+          stmt.setLong(1, id)
+
+          stmt.execute()
+        }
+      }
     }
   }
 
   @Throws(SQLException::class)
-  override fun getAuthor(id: Long): Author {
-    return conn.prepareStatement(getAuthor).use { stmt ->
-      stmt.setLong(1, id)
-
-      val results = stmt.executeQuery()
-      if (!results.next()) {
-        throw SQLException("no rows in result set")
-      }
-      val ret = Author(
-            results.getLong(1),
-            results.getString(2),
-            results.getString(3)
-        )
-      if (results.next()) {
-          throw SQLException("expected one row in result set, but got many")
+  override fun getAuthor(id: Long): RowQuery<Author> {
+    return object : RowQuery<Author>() {
+      override fun execute(): Author {
+        return conn.prepareStatement(getAuthor).use { stmt ->
+          this.statement = stmt
+          stmt.setLong(1, id)
+
+          val results = stmt.executeQuery()
+          if (!results.next()) {
+            throw SQLException("no rows in result set")
+          }
+          val ret = Author(
+                results.getLong(1),
+                results.getString(2),
+                results.getString(3)
+            )
+          if (results.next()) {
+              throw SQLException("expected one row in result set, but got many")
+          }
+          ret
+        }
       }
-      ret
     }
   }
 
   @Throws(SQLException::class)
-  override fun listAuthors(): List<Author> {
-    return conn.prepareStatement(listAuthors).use { stmt ->
-      
-      val results = stmt.executeQuery()
-      val ret = mutableListOf<Author>()
-      while (results.next()) {
-          ret.add(Author(
-            results.getLong(1),
-            results.getString(2),
-            results.getString(3)
-        ))
+  override fun listAuthors(): ListQuery<Author> {
+    return object : ListQuery<Author>() {
+      override fun execute(): List<Author> {
+        return conn.prepareStatement(listAuthors).use { stmt ->
+          this.statement = stmt
+          
+          val results = stmt.executeQuery()
+          val ret = mutableListOf<Author>()
+          while (results.next()) {
+              ret.add(Author(
+                results.getLong(1),
+                results.getString(2),
+                results.getString(3)
+            ))
+          }
+          ret
+        }
       }
-      ret
     }
   }
 

examples/kotlin/src/main/kotlin/com/example/booktest/postgresql/Queries.kt

@@ -7,15 +7,19 @@ import java.sql.SQLException
 import java.sql.Types
 import java.time.OffsetDateTime
 
+import sqlc.runtime.ExecuteQuery
+import sqlc.runtime.ListQuery
+import sqlc.runtime.RowQuery
+
 interface Queries {
   @Throws(SQLException::class)
-  fun booksByTags(dollar1: List<String>): List<BooksByTagsRow>
+  fun booksByTags(dollar1: List<String>): ListQuery<BooksByTagsRow>
 
   @Throws(SQLException::class)
-  fun booksByTitleYear(title: String, year: Int): List<Book>
+  fun booksByTitleYear(title: String, year: Int): ListQuery<Book>
 
   @Throws(SQLException::class)
-  fun createAuthor(name: String): Author
+  fun createAuthor(name: String): RowQuery<Author>
 
   @Throws(SQLException::class)
   fun createBook(
@@ -25,29 +29,29 @@ interface Queries {
       title: String,
       year: Int,
       available: OffsetDateTime,
-      tags: List<String>): Book
+      tags: List<String>): RowQuery<Book>
 
   @Throws(SQLException::class)
-  fun deleteBook(bookId: Int)
+  fun deleteBook(bookId: Int): ExecuteQuery
 
   @Throws(SQLException::class)
-  fun getAuthor(authorId: Int): Author
+  fun getAuthor(authorId: Int): RowQuery<Author>
 
   @Throws(SQLException::class)
-  fun getBook(bookId: Int): Book
+  fun getBook(bookId: Int): RowQuery<Book>
 
   @Throws(SQLException::class)
   fun updateBook(
       title: String,
       tags: List<String>,
-      bookId: Int)
+      bookId: Int): ExecuteQuery
 
   @Throws(SQLException::class)
   fun updateBookISBN(
       title: String,
       tags: List<String>,
       isbn: String,
-      bookId: Int)
+      bookId: Int): ExecuteQuery
 
 }