Merge pull request #124 from adamint/dev

Split dsl builder into two distinct builders, fix cache concurrency problems

Author: adamint

README.md

@@ -28,7 +28,7 @@ repositories {
     jcenter()
 }
 
-compile group: 'com.adamratzman', name: 'spotify-api-kotlin', version: '2.3.08'
+compile group: 'com.adamratzman', name: 'spotify-api-kotlin', version: '3.0.0'
 ```
 
 To use the latest snapshot instead, you must add the Jitpack repository as well
@@ -50,7 +50,7 @@ dependencies {
 <dependency>
     <groupId>com.adamratzman</groupId>
     <artifactId>spotify-api-kotlin</artifactId>
-    <version>2.3.08</version>
+    <version>3.0.0</version>
 </dependency>
 
 <repository>
@@ -79,12 +79,12 @@ To build a new `SpotifyAPI`, you must pass the application id and secret.
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.spotifyApi
 
-spotifyApi {
+val spotifyApi: SpotifyAPI = spotifyAppApi {
     credentials {
         clientId = "YOUR_CLIENT_ID"
         clientSecret = "YOUR_CLIENT_SECRET"
     }
-}.buildCredentialed()
+}.build()
 ```
 *Note:* You are **unable** to use any client endpoint without authenticating with the methods below. 
 
@@ -97,7 +97,7 @@ an authorization code or a `Token` object. Otherwise, it will expire `Token.expi
 You have two options when building the Client API.
 1. You can use [Implicit Grant access tokens](https://developer.spotify.com/web-api/authorization-guide/#implicit_grant_flow) by
 setting the value of `tokenString` in the builder `authentication` block. However, this is a one-time token that cannot be refreshed.
-2. You can use the [Authorization code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow) by 
+2. You can use the [Authorization   code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow) by 
 setting the value of `authorizationCode` in a builder. You may generate an authentication flow url allowing you to request specific 
 Spotify scopes using the `getAuthorizationUrl` method in any builder. This library does not provide a method to retrieve the code from your 
 callback URL; you must implement that with a web server.
@@ -156,18 +156,18 @@ the synchronous format is also shown.
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.spotifyApi
 
-val api = spotifyApi {
+val api: SpotifyAPI = spotifyAppApi {
     credentials {
         clientId = "YOUR_CLIENT_ID"
         clientSecret = "YOUR_CLIENT_SECRET"
     }
-}.buildCredentialed()
+}.build()
 
 // block and print out the names of the twenty most similar songs to the search
-println(api.search.searchTrack("Début de la Suite").complete().map { it.name }.joinToString())
+println(api.search.searchTrack("Début de la Suite").complete().joinToString { it.name })
 
 // now, let's do it asynchronously
-api.search.searchTrack("Début de la Suite").queue { println(it.map { it.name }.joinToString()) }
+api.search.searchTrack("Début de la Suite").queue { tracks -> println(tracks.joinToString { track -> track.name }) }
 
 // simple, right? what about if we want to print out the featured playlists message from the "Overview" tab?
 println(api.browse.getFeaturedPlaylists().complete().message)
@@ -176,6 +176,7 @@ println(api.browse.getFeaturedPlaylists().complete().message)
 // let's find out Bénabar's Spotify ID, find his top tracks, and print them out
 
 val benabarId = api.search.searchArtist("Bénabar").complete()[0].id
+// this works, but a better way would be: api.artists.getArtist("spotify:artist:6xoAWsIOZxJVPpo7Qvqaqv").complete().id
 
 println(api.artists.getArtistTopTracks(benabarId).complete().joinToString { it.name })
 ```
@@ -189,7 +190,7 @@ In both Track and SimpleTrack objects in an endpoint response, there is a nullab
 If the track is unable to be played in the specified market and there is an alternative that *is* playable, this 
 will be populated with the href, uri, and, most importantly, the id of the track.
 
-You can then use this track in `SpotifyClientAPI` actions such as playing or saving the track, knowing that it will be playable 
+You can then use this track in `SpotifyClientAPI` endpoints such as playing or saving the track, knowing that it will be playable 
 in your market!
 
 ### Contributing

build.gradle

@@ -1,7 +1,11 @@
 buildscript {
-    ext.kotlin_version = '1.3.41'
-    ext.dokka_version = '0.9.17'
+    ext.kotlin_version = '1.3.50'
+    ext.dokka_version = '0.10.0'
     ext.junit_version = '5.5.1'
+    ext.moshi_version = '1.8.0'
+    ext.json_version = '20190722'
+    ext.google_http_client_version = '1.32.1'
+    ext.spek_version = '2.0.8'
 
     repositories { jcenter() }
 
@@ -12,17 +16,17 @@ buildscript {
 }
 
 plugins {
-    id "com.diffplug.gradle.spotless" version "3.24.0"
+    id "com.diffplug.gradle.spotless" version "3.25.0"
     id "base"
-    id "io.codearte.nexus-staging" version "0.21.0"
+    id "io.codearte.nexus-staging" version "0.21.1"
     id "com.bmuschko.nexus" version "2.3.1"
 }
 
 apply plugin: 'kotlin'
 apply plugin: 'org.jetbrains.dokka'
 
 group 'com.adamratzman'
-version '2.3.08'
+version '3.0.0-rc.2'
 
 archivesBaseName = 'spotify-api-kotlin'
 
@@ -32,50 +36,58 @@ repositories {
 
 dependencies {
     // Actual library dependencies
-    compile 'com.neovisionaries:nv-i18n:1.25'
+    compile 'com.neovisionaries:nv-i18n:1.26'
 
-    compile "com.squareup.moshi:moshi:1.8.0"
-    compile "com.squareup.moshi:moshi-kotlin:1.8.0"
-    compile group: 'org.json', name: 'json', version: '20190722'
+    compile "com.squareup.moshi:moshi:$moshi_version"
+    compile "com.squareup.moshi:moshi-kotlin:$moshi_version"
+    compile "org.json:json:$json_version"
 
-    compile "com.google.http-client:google-http-client:1.31.0"
+    compile "com.google.http-client:google-http-client:$google_http_client_version"
 
     compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
     compile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
-    
+
     // Spek testing requirements
-    testCompile('org.spekframework.spek2:spek-dsl-jvm:2.0.0') {
+    testCompile("org.spekframework.spek2:spek-dsl-jvm:$spek_version") {
         exclude group: 'org.jetbrains.kotlin'
     }
-    testRuntimeOnly('org.spekframework.spek2:spek-runner-junit5:2.0.0') {
+
+    testRuntimeOnly("org.spekframework.spek2:spek-runner-junit5:$spek_version") {
         exclude group: 'org.junit.platform'
         exclude group: 'org.jetbrains.kotlin'
     }
-    
+
     testCompile "org.junit.jupiter:junit-jupiter-api:$junit_version"
-    testCompile "org.json:json:20180130"
+    testCompile "com.google.code.gson:gson:2.8.5"
     testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junit_version"
 }
 
 dokka {
     outputFormat = 'javadoc'
     outputDirectory = 'docs'
 
-    jdkVersion = 8
-    includeNonPublic = false
-    impliedPlatforms = ["JVM"]
+    configuration {
+        jdkVersion = 8
+        includeNonPublic = false
+        impliedPlatforms = ["JVM"]
 
-    linkMapping {
-        dir = "src/main/kotlin"
-        url = "https://github.com/adamint/spotify-web-api-kotlin/tree/master/src/main/kotlin"
-        suffix = "#L"
+        sourceLink {
+            path = "src/main/kotlin"
+            url = "https://github.com/adamint/spotify-web-api-kotlin/tree/master/src/main/kotlin"
+            lineSuffix = "#L"
+        }
+
+        externalDocumentationLink {
+            url = new URL("https://adamint.github.io/spotify-web-api-kotlin/")
+        }
     }
 }
 
 spotless {
     kotlin {
         ktlint()
-        licenseHeader '/* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */'    // License header
+        licenseHeader '/* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */'
+        // License header
     }
 }
 

docs/com/adamratzman/spotify/SpotifyApiBuilderDsl.html

@@ -189,7 +189,7 @@ <h3>Method Summary</h3>
 </tr>
 <tr id="i5" class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#config-block-">config</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#config-block-">config</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
@@ -208,13 +208,13 @@ <h3>Method Summary</h3>
 </tr>
 <tr id="i8" class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#options-block-">options</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#options-block-">options</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
 <tr id="i9" class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#utilities-block-">utilities</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#utilities-block-">utilities</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
@@ -288,7 +288,7 @@ <h4>authentication</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>utilities</h4>
-<pre>public&nbsp;void&nbsp;utilities(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;utilities(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>
@@ -298,7 +298,7 @@ <h4>utilities</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>config</h4>
-<pre>public&nbsp;void&nbsp;config(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;config(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>
@@ -308,7 +308,7 @@ <h4>config</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>options</h4>
-<pre>public&nbsp;void&nbsp;options(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;options(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>

docs/com/adamratzman/spotify/SpotifyUtilities.html

@@ -6,7 +6,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>SpotifyUtilities</title>
 <meta name="date" content="2019-08-13">
-<meta name="keywords" content="com.adamratzman.spotify.SpotifyUtilities class">
+<meta name="keywords" content="com.adamratzman.spotify.SpotifyApiOptions class">
 <meta name="keywords" content="getUseCache()">
 <meta name="keywords" content="getCacheLimit()">
 <meta name="keywords" content="getAutomaticRefresh()">
@@ -114,7 +114,7 @@ <h2 title="Class SpotifyUtilities" class="title">Class SpotifyUtilities</h2>
 </div>
 <div class="contentContainer">
 <ul class="inheritance">
-<li>com.adamratzman.spotify.SpotifyUtilities</li>
+<li>com.adamratzman.spotify.SpotifyApiOptions</li>
 </ul>
 <div class="description">
 <ul class="blockList">

docs/com/adamratzman/spotify/SpotifyUtilitiesBuilder.html

@@ -6,7 +6,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>SpotifyUtilitiesBuilder</title>
 <meta name="date" content="2019-08-13">
-<meta name="keywords" content="com.adamratzman.spotify.SpotifyUtilitiesBuilder class">
+<meta name="keywords" content="com.adamratzman.spotify.SpotifyApiOptionsBuilder class">
 <meta name="keywords" content="build()">
 <meta name="keywords" content="getUseCache()">
 <meta name="keywords" content="setUseCache()">
@@ -113,7 +113,7 @@ <h2 title="Class SpotifyUtilitiesBuilder" class="title">Class SpotifyUtilitiesBu
 </div>
 <div class="contentContainer">
 <ul class="inheritance">
-<li>com.adamratzman.spotify.SpotifyUtilitiesBuilder</li>
+<li>com.adamratzman.spotify.SpotifyApiOptionsBuilder</li>
 </ul>
 <div class="description">
 <ul class="blockList">