Merge pull request #265 from adamint/dev

bump kotlin version and add SpotifyContinuation for JVM

Author: adamint

README.md

@@ -31,6 +31,8 @@ supporting Kotlin/JS, Kotlin/Android, Kotlin/JVM, and Kotlin/Native
         * [API options](#api-options)
     + [Using the API](#using-the-api)
 * [Platform-specific wrappers and information](#platform-specific-wrappers-and-information)
+    + [Java](#java)
+    + [Android authentication](#android-authentication)
     + [JavaScript: Spotify Web Playback SDK wrapper](#js-spotify-web-playback-sdk-wrapper)
 * [Tips](#tips)
     + [Building the API](#building-the-api)
@@ -54,10 +56,10 @@ repositories {
 implementation("com.adamratzman:spotify-api-kotlin-core:VERSION")
 ```
 
+
 ### JS
 Please see the [JS Spotify Web Playback SDK wrapper](#js-spotify-web-playback-sdk-wrapper) to learn how to use Spotify's web playback SDK in a browser application.
 
-
 ### Android
 **Note**: For information on how to integrate implicit/PKCE authentication, Spotify app remote, and Spotify broadcast notifications into 
 your application, please see the [Android README](README_ANDROID.md).
@@ -383,6 +385,61 @@ APIs available only in `SpotifyClientApi` and `SpotifyImplicitGrantApi` instance
 
 ## Platform-specific wrappers and information
 
+### Java
+Unfortunately, coroutines don't play very nicely with Java code. Fortunately, however, we provide a wrapper around Kotlin's 
+`Continuation` class that allows you to directly implement `onSuccess` and `onFailure` handlers on API methods.
+
+Please see below for an example:
+
+```java
+import com.adamratzman.spotify.SpotifyApiBuilderKt;
+import com.adamratzman.spotify.SpotifyAppApi;
+import com.adamratzman.spotify.javainterop.SpotifyContinuation;
+import com.adamratzman.spotify.models.Album;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.concurrent.ExecutionException;
+
+public class SpotifyTestApp {
+    static SpotifyAppApi api;
+
+    public static void main(String[] args) throws ExecutionException, InterruptedException {
+        var id = "spotify-client-id";
+        var secret = "spotify-client-secret";
+        SpotifyApiBuilderKt.spotifyAppApi(id, secret).build(true, new SpotifyContinuation<>() {
+            @Override
+            public void onSuccess(SpotifyAppApi spotifyAppApi) {
+                api = spotifyAppApi;
+                runAlbumSearch();
+            }
+
+            @Override
+            public void onFailure(@NotNull Throwable throwable) {
+                throwable.printStackTrace();
+            }
+        });
+
+        Thread.sleep(1000000);
+    }
+
+    public static void runAlbumSearch() {
+        api.getAlbums().getAlbum("spotify:album:0b23AHutIA1BOW0u1dZ6wM", null, new SpotifyContinuation<>() {
+            @Override
+            public void onSuccess(Album album) {
+                System.out.println("Album name is: " + album.getName() + ". Exiting now..");
+
+                System.exit(0);
+            }
+
+            @Override
+            public void onFailure(@NotNull Throwable throwable) {
+                throwable.printStackTrace();
+            }
+        });
+    }
+}
+```
+
 ### Android authentication
 For information on how to integrate implicit/PKCE authentication, Spotify app remote, and Spotify broadcast notifications into 
 your application, please see the [Android README](README_ANDROID.md).

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
     signing
     id("io.codearte.nexus-staging") version "0.22.0"
     id("com.android.library")
-    kotlin("multiplatform") version "1.4.30"
+    kotlin("multiplatform") version "1.4.31"
     kotlin("plugin.serialization") version "1.4.30"
     id("com.diffplug.spotless") version "5.9.0"
     id("com.moowork.node") version "1.3.1"
@@ -27,7 +27,7 @@ buildscript {
     }
     dependencies {
         classpath("com.android.tools.build:gradle:3.5.4")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.30")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.31")
     }
 }
 
@@ -199,7 +199,12 @@ kotlin {
                 }
             }
 
+            val commonJvmLikeMain by creating {
+                dependsOn(commonMain)
+            }
+
             val jvmMain by getting {
+                dependsOn(commonJvmLikeMain)
                 repositories {
                     mavenCentral()
                     jcenter()
@@ -236,6 +241,8 @@ kotlin {
             }
 
             val androidMain by getting {
+                dependsOn(commonJvmLikeMain)
+
                 repositories {
                     mavenCentral()
                     jcenter()

src/commonJvmLikeMain/kotlin/com/adamratzman/spotify/javainterop/SpotifyContinuation.kt

@@ -0,0 +1,34 @@
+@file:JvmName("SpotifyContinuation")
+
+package com.adamratzman.spotify.javainterop
+
+import kotlin.coroutines.Continuation
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
+
+/**
+ * A [Continuation] wrapper to allow you to directly implement [onSuccess] and [onFailure], when exceptions are hidden
+ * on JVM via traditional continuations. **Please use this class as a callback anytime you are using Java code with this library.**
+ *
+ */
+abstract class SpotifyContinuation<in T> : Continuation<T> {
+    /**
+     * Invoke a function with the callback [value]
+     *
+     * @param value The value retrieved from the Spotify API.
+     */
+    abstract fun onSuccess(value: T)
+
+    /**
+     * Handle exceptions during this API call.
+     *
+     * @param exception The exception that was thrown during the call.
+     */
+    abstract fun onFailure(exception: Throwable)
+
+    override fun resumeWith(result: Result<T>) {
+        result.fold(::onSuccess, ::onFailure)
+    }
+
+    override val context: CoroutineContext = EmptyCoroutineContext
+}

src/commonMain/kotlin/com.adamratzman.spotify/Builder.kt renamed to src/commonMain/kotlin/com.adamratzman.spotify/SpotifyApiBuilder.kt

@@ -114,7 +114,29 @@ public fun getSpotifyPkceCodeChallenge(codeVerifier: String): String {
 public fun spotifyImplicitGrantApi(
     clientId: String?,
     token: Token,
-    block: SpotifyApiOptions.() -> Unit = { }
+): SpotifyImplicitGrantApi = SpotifyImplicitGrantApi(
+    clientId,
+    token,
+    SpotifyApiOptions()
+)
+
+
+/**
+ * Instantiate a new [SpotifyImplicitGrantApi] using a Spotify [clientId], and [token] retrieved from the implicit
+ * grant flow.
+ *
+ * Use case: I have a token obtained after implicit grant authorization.
+ *
+ * @param clientId Spotify [client id](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param token Token created from the hash response in the implicit grant callback
+ * @param block Block to set API options
+ *
+ * @return [SpotifyImplicitGrantApi] that can immediately begin making calls
+ */
+public fun spotifyImplicitGrantApi(
+    clientId: String?,
+    token: Token,
+    block: SpotifyApiOptions.() -> Unit
 ): SpotifyImplicitGrantApi = SpotifyImplicitGrantApi(
     clientId,
     token,
@@ -135,6 +157,28 @@ public fun spotifyImplicitGrantApi(
                 ||     ||
  */
 
+/**
+ * Instantiate a new [SpotifyAppApiBuilder] using a Spotify [clientId] and [clientSecret].
+ *
+ * Use case: I am using the client credentials flow.
+ * I only need access to public Spotify API endpoints, might have an existing token,
+ * and might want to deal with advanced configuration.
+ *
+ * @param clientId Spotify [client id](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param clientSecret Spotify [client secret](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ *
+ * @return Configurable [SpotifyAppApiBuilder] that, when built, creates a new [SpotifyAppApi]
+ */
+public fun spotifyAppApi(
+    clientId: String,
+    clientSecret: String
+): SpotifyAppApiBuilder = SpotifyAppApiBuilder().apply {
+    credentials {
+        this.clientId = clientId
+        this.clientSecret = clientSecret
+    }
+}
+
 /**
  * Instantiate a new [SpotifyAppApiBuilder] using a Spotify [clientId] and [clientSecret], with the ability to configure
  * the api settings by providing a builder initialization [block]
@@ -251,6 +295,35 @@ public fun spotifyAppApi(block: SpotifyAppApiBuilder.() -> Unit): SpotifyAppApiB
                 ||     ||
  */
 
+/**
+ * Instantiate a new [SpotifyClientApiBuilder] using a Spotify [clientId], [clientSecret], and [redirectUri].
+ *
+ * **Note**: If trying to build [SpotifyClientApi], you **must** provide client authorization in the [SpotifyClientApiBuilder.authorization]
+ * block
+ *
+ * Use case: I am using the client authorization flow.
+ * I want access to both public and client Spotify API endpoints, and I want
+ * to configure authorization and other settings myself.
+ *
+ * @param clientId Spotify [client id](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param clientSecret Spotify [client secret](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param redirectUri Spotify [redirect uri](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ *
+ * @return Configurable [SpotifyClientApiBuilder] that, when built, creates a new [SpotifyClientApi]
+ */
+public fun spotifyClientApi(
+    clientId: String,
+    clientSecret: String,
+    redirectUri: String
+): SpotifyClientApiBuilder = SpotifyClientApiBuilder().apply {
+    credentials {
+        this.clientId = clientId
+        this.clientSecret = clientSecret
+        this.redirectUri = redirectUri
+    }
+}
+
+
 /**
  * Instantiate a new [SpotifyClientApiBuilder] using a Spotify [clientId], [clientSecret], and [redirectUri], with the ability to configure
  * the api settings by providing a builder initialization [block]
@@ -273,7 +346,7 @@ public fun spotifyClientApi(
     clientId: String,
     clientSecret: String,
     redirectUri: String,
-    block: SpotifyClientApiBuilder.() -> Unit = {}
+    block: SpotifyClientApiBuilder.() -> Unit
 ): SpotifyClientApiBuilder = SpotifyClientApiBuilder().apply(block).apply {
     credentials {
         this.clientId = clientId
@@ -411,6 +484,37 @@ public fun spotifyClientPkceApi(
     usesPkceAuth = true
 }
 
+/**
+ * Instantiate a new [SpotifyClientApiBuilder]. This is for **PKCE authorization**.
+ *
+ * Use case: I am using the PKCE client authorization flow.
+ *
+ * @param clientId Spotify [client id](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param redirectUri Spotify [redirect uri](https://developer.spotify.com/documentation/general/guides/app-settings/)
+ * @param pkceCodeVerifier The code verifier generated that the client authenticated with (using its code challenge)
+ * @param authorizationCode Only available when building [SpotifyClientApi]. Spotify auth code
+ *
+ * @return Configurable [SpotifyClientApiBuilder] that, when built, creates a new [SpotifyClientApi]
+ */
+public fun spotifyClientPkceApi(
+    clientId: String?,
+    redirectUri: String?,
+    authorizationCode: String,
+    pkceCodeVerifier: String
+): SpotifyClientApiBuilder = SpotifyClientApiBuilder().apply {
+    credentials {
+        this.clientId = clientId
+        this.redirectUri = redirectUri
+    }
+
+    authorization {
+        this.authorizationCode = authorizationCode
+        this.pkceCodeVerifier = pkceCodeVerifier
+    }
+
+    usesPkceAuth = true
+}
+
 /**
  * Instantiate a new [SpotifyClientApiBuilder]. This is for **PKCE authorization**.
  *
@@ -429,7 +533,7 @@ public fun spotifyClientPkceApi(
     redirectUri: String?,
     authorizationCode: String,
     pkceCodeVerifier: String,
-    block: SpotifyApiOptions.() -> Unit = {}
+    block: SpotifyApiOptions.() -> Unit
 ): SpotifyClientApiBuilder = SpotifyClientApiBuilder().apply {
     credentials {
         this.clientId = clientId