add documentation, update to current version

Signed-off-by: Adam Ratzman <[email protected]>

Author: adamint

README.md

@@ -391,9 +391,36 @@ APIs available only in `SpotifyClientApi` and `SpotifyImplicitGrantApi` instance
 ## Platform-specific wrappers and information
 
 ### Java
-This library has first-class support for Java! You have 
-
+This library has first-class support for Java! You have two choices when using this library: async-only with Kotlin
+suspend functions (using SpotifyContinuation), or by using the `SpotifyRestAction` class. Using `SpotifyRestAction`s are 
+recommended.
+
+#### What is the SpotifyRestAction class and how do I use it?
+Abstracting requests into a `SpotifyRestAction` class allows for a lot of flexibility in sending and receiving requests.
+This class includes options for asynchronous and blocking execution in all endpoints. However,
+due to this, you **must** call one of the provided methods in order for the call
+to execute! The `SpotifyRestAction` provides many methods and fields for use, including blocking and asynchronous ones. For example,
+- `hasRun()` tells you whether the rest action has been *started*
+- `hasCompleted()` tells you whether this rest action has been fully executed and *completed*
+- `complete()` blocks the current thread and returns the result
+- `suspendComplete(context: CoroutineContext = Dispatchers.Default)` switches to given context, invokes the supplier, and synchronously retrieves the result.
+- `suspendQueue()` suspends the coroutine, invokes the supplier asynchronously, and resumes with the result
+- `queue()` executes and immediately returns
+- `queue(consumer: (T) -> Unit)` executes the provided callback as soon as the request
+  is asynchronously evaluated
+- `queueAfter(quantity: Int, timeUnit: TimeUnit, consumer: (T) -> Unit)` executes the
+  provided callback after the provided time. As long as supplier execution is less than the provided
+  time, this will likely be accurate within a few milliseconds.
+- `asFuture()` transforms the supplier into a `CompletableFuture` (only JVM)
+
+Here's an example of how easy it is to use `spotify-web-api-kotlin` with a `SpotifyRestAction`:
+```java
+var api = SpotifyApiBuilderKt.spotifyAppApi(Const.clientId, Const.clientSecret).buildRestAction(true).complete();
+var album = api.getAlbums().getAlbumRestAction("spotify:album:0b23AHutIA1BOW0u1dZ6wM", null).complete();
+System.out.println("Album name is: " + album.getName());
+```
 
+#### Integrating with Kotlin suspend functions via Java `Continuation`s
 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.
 

publish_all.sh

@@ -0,0 +1 @@
+gradle publishMacosX64PublicationToNexusRepository publishLinuxX64PublicationToNexusRepository publishKotlinMultiplatformPublicationToNexusRepository publishTvosX64PublicationToNexusRepository publishTvosArm64PublicationToNexusRepository publishIosX64PublicationToNexusRepository publishIosArm64PublicationToNexusRepository publishJsPublicationToNexusRepository publishJvmPublicationToNexusRepository publishAndroidPublicationToNexusRepository

src/androidMain/kotlin/com/adamratzman/spotify/utils/PlatformUtils.kt

@@ -5,8 +5,8 @@ import android.app.Activity
 import android.content.Context
 import android.util.Log
 import android.widget.Toast
-import com.soywiz.korio.async.runBlockingNoJs
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.runBlocking
 import java.net.URLEncoder
 
 internal actual fun String.encodeUrl() = URLEncoder.encode(this, "UTF-8")!!
@@ -36,6 +36,6 @@ internal fun logToConsole(message: String) {
     Log.i("spotify-web-api-kotlin", message)
 }
 
-public actual fun <T> runBlockingOnJvmAndNative(block: suspend CoroutineScope.() -> T): T {
-    return runBlockingNoJs { block() }
+public actual fun <T> runBlockingOnJvmAndNative(block: suspend () -> T): T {
+    return runBlocking { block() }
 }

src/androidTest/kotlin/com/adamratzman/spotify/CommonImpl.kt

@@ -31,4 +31,4 @@ public actual fun Exception.stackTrace() {
 public actual val testCoroutineContext: CoroutineContext =
         Executors.newSingleThreadExecutor().asCoroutineDispatcher()
 
-public actual fun runBlockingTest(block: suspend CoroutineScope.() -> Unit): Unit = runBlocking(testCoroutineContext) { this.block() }
+public actual fun runBlockingTest(block: suspend () -> Unit): Unit = runBlocking(testCoroutineContext) { this.block() }

src/commonMain/kotlin/com.adamratzman.spotify/endpoints/client/ClientFollowingApi.kt

@@ -89,7 +89,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws [BadRequestException] if the playlist is not found
      * @return Whether the current user is following [playlistId]
      */
-    public fun isFollowingPlaylistRestAction(playlistId: String) =
+    public fun isFollowingPlaylistRestAction(playlistId: String): SpotifyRestAction<Boolean> =
         SpotifyRestAction { isFollowingPlaylist(playlistId) }
 
     /**

src/commonMain/kotlin/com.adamratzman.spotify/utils/Utils.kt

@@ -35,4 +35,4 @@ internal fun formatDate(date: Long): String {
     return Instant.fromEpochMilliseconds(date).toString()
 }
 
-public expect fun <T> runBlockingOnJvmAndNative(block: suspend CoroutineScope.() -> T): T
+public expect fun <T> runBlockingOnJvmAndNative(block: suspend () -> T): T

src/commonTest/kotlin/com.adamratzman/spotify/Common.kt

@@ -12,7 +12,7 @@ val redirectUri = getEnvironmentVariable("SPOTIFY_REDIRECT_URI")
 val tokenString = getEnvironmentVariable("SPOTIFY_TOKEN_STRING")
 
 // https://github.com/Kotlin/kotlinx.coroutines/issues/1996#issuecomment-728562784
-expect fun runBlockingTest(block: suspend CoroutineScope.() -> Unit)
+expect fun runBlockingTest(block: suspend () -> Unit)
 expect val testCoroutineContext: CoroutineContext
 
 @ThreadLocal

src/desktopMain/kotlin/com/adamratzman/spotify/utils/PlatformUtils.kt

@@ -1,9 +1,7 @@
 /* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2021; Original author: Adam Ratzman */
 package com.adamratzman.spotify.utils
 
-import com.soywiz.korio.async.runBlockingNoJs
 import io.ktor.http.encodeURLQueryComponent
-import kotlinx.coroutines.CoroutineScope
 
 internal actual fun String.encodeUrl() = encodeURLQueryComponent()
 
@@ -14,8 +12,4 @@ public actual val currentApiPlatform: Platform = Platform.NATIVE
 
 public actual typealias ConcurrentHashMap<K, V> = HashMap<K, V>
 
-public actual fun <K, V> ConcurrentHashMap<K, V>.asList(): List<Pair<K, V>> = toList()
-
-public actual fun <T> runBlockingOnJvmAndNative(block: suspend CoroutineScope.() -> T): T {
-    return runBlockingNoJs { block() }
-}
+public actual fun <K, V> ConcurrentHashMap<K, V>.asList(): List<Pair<K, V>> = toList()

src/desktopTest/kotlin/com.adamratzman.spotify/CommonImpl.kt

@@ -15,5 +15,5 @@ actual fun getEnvironmentVariable(name: String): String? {
 actual fun Exception.stackTrace() = printStackTrace()
 
 actual val testCoroutineContext: CoroutineContext = MainScope().coroutineContext
-actual fun runBlockingTest(block: suspend CoroutineScope.() -> Unit) =
-    runBlocking { this.block() }
+actual fun runBlockingTest(block: suspend () -> Unit) =
+    runBlocking { block() }

src/iosMain/kotlin/com.adamratzman.spotify.utils/PlatformUtils.kt

@@ -0,0 +1,7 @@
+package com.adamratzman.spotify.utils
+
+import kotlinx.coroutines.runBlocking
+
+public actual fun <T> runBlockingOnJvmAndNative(block: suspend () -> T): T {
+    return runBlocking { block() }
+}