Add async APIs for SDK 2.x

buildSrc/src/main/kotlin/Dependencies.kt

@@ -16,7 +16,9 @@ object Dependencies {
   val kotlinGradlePlugin = "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.10"
   val kotlinReflection = "org.jetbrains.kotlin:kotlin-reflect:1.4.10"
   val kotlinStdLib = "org.jetbrains.kotlin:kotlin-stdlib:1.4.10"
-  val kotlinxCoroutines = "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.5"
+  val kotlinxCoroutines = "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.3"
+  val kotlinxCoroutinesJdk8 = "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.4.3"
+  val kotlinxCoroutinesReactive = "org.jetbrains.kotlinx:kotlinx-coroutines-reactive:1.4.3"
   val ktlintVersion = "0.40.0"
   val loggingApi = "io.github.microutils:kotlin-logging:1.7.9"
   val mavenPublishGradlePlugin = "com.vanniktech:gradle-maven-publish-plugin:0.12.0"

docs/guide/asynchronous_programming.md

@@ -0,0 +1,136 @@
+## Nonblocking I/O
+The AWS SDK 2.x features [truly nonblocking asynchronous clients](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/asynchronous.html) that implement high 
+concurrency across a few threads.
+
+!!! warning "SDK 1.x uses blocking I/O"
+    The AWS SDK for Java 1.11.x has asynchronous clients that are wrappers around a thread pool and blocking synchronous clients that don’t provide the full benefit of nonblocking I/O.
+
+## Tempest Async APIs
+Tempest for SDK 2.x comes with async APIs that utilize Kotlin [coroutine](https://kotlinlang.org/docs/coroutines-overview.html) and Java [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html).
+
+Declare you DB and tables as `AsyncLogicalDb` and `AsyncLogicalTable`.
+
+=== "Kotlin - SDK 2.x"
+
+    ```kotlin
+    interface AsyncMusicDb : AsyncLogicalDb {
+       @TableName("music_items")
+       val music: AsyncMusicTable
+    }
+
+    interface AsyncMusicTable : AsyncLogicalTable<MusicItem> {
+      val albumInfo: AsyncInlineView<AlbumInfo.Key, AlbumInfo>
+      val albumTracks: AsyncInlineView<AlbumTrack.Key, AlbumTrack>
+
+      val playlistInfo: AsyncInlineView<PlaylistInfo.Key, PlaylistInfo>
+
+      // Global Secondary Indexes.
+      val albumInfoByGenre: AsyncSecondaryIndex<AlbumInfo.GenreIndexOffset, AlbumInfo>
+      val albumInfoByArtist: AsyncSecondaryIndex<AlbumInfo.ArtistIndexOffset, AlbumInfo>
+
+      // Local Secondary Indexes.
+      val albumTracksByTitle: AsyncSecondaryIndex<AlbumTrack.TitleIndexOffset, AlbumTrack>
+    }
+    ```
+
+=== "Java - SDK 2.x"
+
+    ```java
+    public interface AsyncMusicDb extends AsyncLogicalDb {
+      @TableName("music_items")
+      AsyncMusicTable music();
+    }
+
+    public interface AsyncMusicTable extends AsyncLogicalTable<MusicItem> {
+      AsyncInlineView<AlbumInfo.Key, AlbumInfo> albumInfo();
+      AsyncInlineView<AlbumTrack.Key, AlbumTrack> albumTracks();
+
+      AsyncInlineView<PlaylistInfo.Key, PlaylistInfo> playlistInfo();
+
+      // Global Secondary Indexes.
+      AsyncSecondaryIndex<AlbumInfo.GenreIndexOffset, AlbumInfo> albumInfoByGenre();
+      AsyncSecondaryIndex<AlbumInfo.ArtistIndexOffset, AlbumInfo> albumInfoByArtist();
+
+      // Local Secondary Indexes.
+      AsyncSecondaryIndex<AlbumTrack.TitleIndexOffset, AlbumTrack> albumTracksByTitle();
+    }
+    ```
+
+Write familiar code that is asynchronous under the hood. 
+
+=== "Kotlin - SDK 2.x"
+
+    ```kotlin
+    private val table: AsyncMusicTable
+
+    suspend fun changePlaylistName(playlistToken: String, newName: String) {
+      // Read.
+      val existing = checkNotNull(
+        table.playlistInfo.load(PlaylistInfo.Key(playlistToken)) // This is a suspend function.
+      ) { "Playlist does not exist: $playlistToken" }
+      // Modify.
+      val newPlaylist = existing.copy(
+        playlist_name = newName,
+        playlist_version = existing.playlist_version + 1
+      )
+      // Write.
+      table.playlistInfo.save( // This is a suspend function.
+        newPlaylist,
+        ifPlaylistVersionIs(existing.playlist_version)
+      )
+    }
+
+    private fun ifPlaylistVersionIs(playlist_version: Long): Expression {
+      return Expression.builder()
+        .expression("playlist_version = :playlist_version")
+        .expressionValues(mapOf(":playlist_version" to AttributeValue.builder().n("$playlist_version").build()))
+        .build()
+    }
+    ```
+
+=== "Java - SDK 2.x"
+
+    ```java
+    private final AsyncMusicTable table;
+
+    public CompletableFuture<Void> changePlaylistName(String playlistToken, String newName) {
+      // Read.
+      return table.playlistInfo()
+          .loadAsync(new PlaylistInfo.Key(playlistToken))
+          .thenCompose(existing -> {
+            if (existing == null) {
+              throw new IllegalStateException("Playlist does not exist: " + playlistToken);
+            }
+            // Modify.
+            PlaylistInfo newPlaylist = new PlaylistInfo(
+                existing.playlist_token,
+                newName,
+                existing.playlist_tracks,
+                // playlist_version.
+                existing.playlist_version + 1
+            );
+            // Write.
+            return table.playlistInfo()
+                .saveAsync(
+                    newPlaylist,
+                    ifPlaylistVersionIs(existing.playlist_version)
+                );
+          });
+    }
+
+    private Expression ifPlaylistVersionIs(Long playlist_version) {
+      return Expression.builder()
+        .expression("playlist_version = :playlist_version")
+        .expressionValues(
+            Map.of(":playlist_version", AttributeValue.builder().n("" + playlist_version).build()))
+        .build();
+    }
+    ```
+
+---
+
+Check out the code samples on Github:
+
+* Music Library - SDK 2.x ([.kt](https://github.com/cashapp/tempest/tree/master/samples/musiclibrary2/src/main/kotlin/app/cash/tempest2/musiclibrary), [.java](https://github.com/cashapp/tempest/tree/master/samples/musiclibrary2/src/main/java/app/cash/tempest2/musiclibrary/java))
+* Asynchronous Programing - SDK 2.x ([.kt](https://github.com/cashapp/tempest/blob/master/samples/guides2/src/main/kotlin/app/cash/tempest2/guides/AsynchronousProgramming.kt), [.java](https://github.com/cashapp/tempest/blob/master/samples/guides2/src/main/java/app/cash/tempest2/guides/java/AsynchronousProgramming.java))
+

mkdocs.yml

@@ -64,6 +64,7 @@ nav:
       - 'Query & Scan': guide/query_scan.md
       - 'Transaction': guide/transaction.md
       - 'Testing': guide/testing.md
+      - 'Asynchronous Programming': guide/asynchronous_programming.md
       - 'DynamoDB Resources': guide/dynamodb_resources.md
 
   - 'Reference':

samples/guides-junit4/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
   implementation(project(":samples:musiclibrary"))
   implementation(project(":samples:urlshortener"))
   implementation(Dependencies.kotlinStdLib)
-  implementation(Dependencies.kotlinxCoroutines)
 
   testImplementation(Dependencies.assertj)
   testImplementation(Dependencies.junit4Api)

samples/guides-junit5/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
   implementation(project(":samples:musiclibrary"))
   implementation(project(":samples:urlshortener"))
   implementation(Dependencies.kotlinStdLib)
-  implementation(Dependencies.kotlinxCoroutines)
 
   testImplementation(Dependencies.assertj)
   testImplementation(Dependencies.junitApi)

samples/guides2-junit4/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
   implementation(project(":samples:musiclibrary2"))
   implementation(project(":samples:urlshortener2"))
   implementation(Dependencies.kotlinStdLib)
-  implementation(Dependencies.kotlinxCoroutines)
 
   testImplementation(Dependencies.assertj)
   testImplementation(Dependencies.junit4Api)

samples/guides2-junit5/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
   implementation(project(":samples:musiclibrary2"))
   implementation(project(":samples:urlshortener2"))
   implementation(Dependencies.kotlinStdLib)
-  implementation(Dependencies.kotlinxCoroutines)
 
   testImplementation(Dependencies.assertj)
   testImplementation(Dependencies.junitApi)

samples/guides2/src/main/java/app/cash/tempest2/guides/java/AsynchronousProgramming.java

@@ -0,0 +1,50 @@
+package app.cash.tempest2.guides.java;
+
+import app.cash.tempest2.musiclibrary.java.AsyncMusicTable;
+import app.cash.tempest2.musiclibrary.java.PlaylistInfo;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import software.amazon.awssdk.enhanced.dynamodb.Expression;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+public class AsynchronousProgramming {
+
+  private final AsyncMusicTable table;
+
+  public AsynchronousProgramming(AsyncMusicTable table) {
+    this.table = table;
+  }
+
+  public CompletableFuture<Void> changePlaylistName(String playlistToken, String newName) {
+    // Read.
+    return table.playlistInfo()
+        .loadAsync(new PlaylistInfo.Key(playlistToken))
+        .thenCompose(existing -> {
+          if (existing == null) {
+            throw new IllegalStateException("Playlist does not exist: " + playlistToken);
+          }
+          // Modify.
+          PlaylistInfo newPlaylist = new PlaylistInfo(
+              existing.playlist_token,
+              newName,
+              existing.playlist_tracks,
+              // playlist_version.
+              existing.playlist_version + 1
+          );
+          // Write.
+          return table.playlistInfo()
+              .saveAsync(
+                  newPlaylist,
+                  ifPlaylistVersionIs(existing.playlist_version)
+              );
+        });
+  }
+
+  private Expression ifPlaylistVersionIs(Long playlist_version) {
+    return Expression.builder()
+        .expression("playlist_version = :playlist_version")
+        .expressionValues(
+            Map.of(":playlist_version", AttributeValue.builder().n("" + playlist_version).build()))
+        .build();
+  }
+}

samples/guides2/src/main/kotlin/app/cash/tempest2/guides/AsynchronousProgramming.kt

@@ -0,0 +1,35 @@
+package app.cash.tempest2.guides
+
+import app.cash.tempest2.musiclibrary.AsyncMusicTable
+import app.cash.tempest2.musiclibrary.PlaylistInfo
+import software.amazon.awssdk.enhanced.dynamodb.Expression
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue
+
+class AsynchronousProgramming(
+  private val table: AsyncMusicTable,
+) {
+
+  suspend fun changePlaylistName(playlistToken: String, newName: String) {
+    // Read.
+    val existing = checkNotNull(
+      table.playlistInfo.load(PlaylistInfo.Key(playlistToken)) // This is a suspend function.
+    ) { "Playlist does not exist: $playlistToken" }
+    // Modify.
+    val newPlaylist = existing.copy(
+      playlist_name = newName,
+      playlist_version = existing.playlist_version + 1
+    )
+    // Write.
+    table.playlistInfo.save( // This is a suspend function.
+      newPlaylist,
+      ifPlaylistVersionIs(existing.playlist_version)
+    )
+  }
+
+  private fun ifPlaylistVersionIs(playlist_version: Long): Expression {
+    return Expression.builder()
+      .expression("playlist_version = :playlist_version")
+      .expressionValues(mapOf(":playlist_version" to AttributeValue.builder().n("$playlist_version").build()))
+      .build()
+  }
+}

samples/musiclibrary2/src/main/java/app/cash/tempest2/musiclibrary/java/AsyncMusicDb.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2021 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package app.cash.tempest2.musiclibrary.java;
+
+import app.cash.tempest2.AsyncLogicalDb;
+import app.cash.tempest2.TableName;
+
+public interface AsyncMusicDb extends AsyncLogicalDb {
+  @TableName("j_music_items")
+  AsyncMusicTable music();
+}

samples/musiclibrary2/src/main/java/app/cash/tempest2/musiclibrary/java/AsyncMusicTable.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package app.cash.tempest2.musiclibrary.java;
+
+import app.cash.tempest2.AsyncInlineView;
+import app.cash.tempest2.AsyncLogicalTable;
+import app.cash.tempest2.AsyncSecondaryIndex;
+
+public interface AsyncMusicTable extends AsyncLogicalTable<MusicItem> {
+  AsyncInlineView<AlbumInfo.Key, AlbumInfo> albumInfo();
+  AsyncInlineView<AlbumTrack.Key, AlbumTrack> albumTracks();
+
+  AsyncInlineView<PlaylistInfo.Key, PlaylistInfo> playlistInfo();
+
+  // Global Secondary Indexes.
+  AsyncSecondaryIndex<AlbumInfo.GenreIndexOffset, AlbumInfo> albumInfoByGenre();
+  AsyncSecondaryIndex<AlbumInfo.ArtistIndexOffset, AlbumInfo> albumInfoByArtist();
+
+  // Local Secondary Indexes.
+  AsyncSecondaryIndex<AlbumTrack.TitleIndexOffset, AlbumTrack> albumTracksByTitle();
+}

samples/musiclibrary2/src/main/kotlin/app/cash/tempest2/musiclibrary/AsyncMusicDb.kt

@@ -0,0 +1,9 @@
+package app.cash.tempest2.musiclibrary
+
+import app.cash.tempest2.AsyncLogicalDb
+import app.cash.tempest2.TableName
+
+interface AsyncMusicDb : AsyncLogicalDb {
+  @TableName("music_items")
+  val music: AsyncMusicTable
+}

samples/musiclibrary2/src/main/kotlin/app/cash/tempest2/musiclibrary/AsyncMusicTable.kt

@@ -0,0 +1,19 @@
+package app.cash.tempest2.musiclibrary
+
+import app.cash.tempest2.AsyncInlineView
+import app.cash.tempest2.AsyncLogicalTable
+import app.cash.tempest2.AsyncSecondaryIndex
+
+interface AsyncMusicTable : AsyncLogicalTable<MusicItem> {
+  val albumInfo: AsyncInlineView<AlbumInfo.Key, AlbumInfo>
+  val albumTracks: AsyncInlineView<AlbumTrack.Key, AlbumTrack>
+
+  val playlistInfo: AsyncInlineView<PlaylistInfo.Key, PlaylistInfo>
+
+  // Global Secondary Indexes.
+  val albumInfoByGenre: AsyncSecondaryIndex<AlbumInfo.GenreIndexOffset, AlbumInfo>
+  val albumInfoByArtist: AsyncSecondaryIndex<AlbumInfo.ArtistIndexOffset, AlbumInfo>
+
+  // Local Secondary Indexes.
+  val albumTracksByTitle: AsyncSecondaryIndex<AlbumTrack.TitleIndexOffset, AlbumTrack>
+}

tempest-internal/src/main/kotlin/app/cash/tempest/internal/ProxyFactory.kt

@@ -22,7 +22,7 @@ import java.lang.reflect.Method
 import java.lang.reflect.Proxy
 import kotlin.reflect.KClass
 
-class ProxyFactory {
+object ProxyFactory {
 
   fun <T : Any> create(
     type: KClass<T>,