trim cache when necessary, lazily

Author: adamint

src/main/kotlin/com/adamratzman/spotify/Builder.kt

@@ -23,6 +23,7 @@ class SpotifyApiBuilder(
     var tokenString: String? = null,
     var token: Token? = null,
     var useCache: Boolean = true,
+    var cacheLimit: Int? = 1000,
     var automaticRefresh: Boolean = true,
     var retryWhenRateLimited: Boolean = false,
     var enableLogger: Boolean = false
@@ -69,6 +70,11 @@ class SpotifyApiBuilder(
      */
     fun useCache(useCache: Boolean) = apply { this.useCache = useCache }
 
+    /**
+     *  Set the maximum allowed amount of cached requests at one time. Null means no limit
+     */
+    fun cacheLimit(cacheLimit: Int?) = apply { this.cacheLimit = cacheLimit }
+
     /**
      * Set the application [redirect uri](https://developer.spotify.com/documentation/general/guides/authorization-guide/)
      */
@@ -200,6 +206,7 @@ class SpotifyUserAuthorizationBuilder(
  * @property authentication A holder for authentication methods. At least one needs to be provided in order to create
  * a **client** api
  * @property useCache Set whether to cache requests. Default: true
+ * @property cacheLimit The maximum amount of cached requests allowed at one time. Null means no limit
  * @property automaticRefresh Enable or disable automatic refresh of the Spotify access token
  * @property retryWhenRateLimited Set whether to block the current thread and wait until the API can retry the request
  * @property enableLogger Set whether to enable to the exception logger
@@ -208,6 +215,7 @@ class SpotifyApiBuilderDsl {
     private var credentials: SpotifyCredentials = SpotifyCredentials(null, null, null)
     private var authentication = SpotifyUserAuthorizationBuilder()
     var useCache: Boolean = true
+    var cacheLimit: Int? = 1000
     var automaticRefresh: Boolean = true
     var retryWhenRateLimited: Boolean = false
     var enableLogger: Boolean = false

src/main/kotlin/com/adamratzman/spotify/SpotifyAPI.kt

@@ -46,6 +46,7 @@ internal val base = "https://api.spotify.com/v1"
  * @property token The access token associated with this API instance
  * @property useCache Whether to use the built-in cache to avoid making unnecessary calls to
  * the Spotify API
+ * @property cacheLimit The maximum amount of cached requests allowed at one time. Null means no limit
  *
  * @property search Provides access to the Spotify [search endpoint](https://developer.spotify.com/documentation/web-api/reference/search/search/)
  * @property albums Provides access to Spotify [album endpoints](https://developer.spotify.com/documentation/web-api/reference/albums/)
@@ -62,6 +63,7 @@ abstract class SpotifyAPI internal constructor(
     val clientSecret: String,
     var token: Token,
     useCache: Boolean,
+    var cacheLimit: Int?,
     var automaticRefresh: Boolean,
     var retryWhenRateLimited: Boolean,
     enableLogger: Boolean
@@ -73,6 +75,11 @@ abstract class SpotifyAPI internal constructor(
             field = value
         }
 
+    /**
+     * Obtain a map of all currently-cached requests
+     */
+    fun getCache() = endpoints.map { it.cache.cachedRequests.toList() }.flatten().toMap()
+
     val expireTime: Long get() = System.currentTimeMillis() + token.expiresIn * 1000
 
     val executor: ScheduledExecutorService = Executors.newScheduledThreadPool(0)
@@ -99,10 +106,15 @@ abstract class SpotifyAPI internal constructor(
      */
     abstract fun refreshToken(): Token
 
+    /**
+     * A list of all endpoints included in this api type
+     */
+    abstract val endpoints: List<SpotifyEndpoint>
+
     /**
      * If the cache is enabled, clear all stored queries in the cache
      */
-    abstract fun clearCache()
+    fun clearCache() = clearCaches(*endpoints.toTypedArray())
 
     /**
      * Return a new [SpotifyApiBuilder] with the parameters provided to this api instance
@@ -114,7 +126,7 @@ abstract class SpotifyAPI internal constructor(
      */
     abstract fun getApiBuilderDsl(): SpotifyApiBuilderDsl
 
-    internal fun clearAllCaches(vararg endpoints: SpotifyEndpoint) {
+    private fun clearCaches(vararg endpoints: SpotifyEndpoint) {
         endpoints.forEach { it.cache.clear() }
     }
 
@@ -150,10 +162,11 @@ class SpotifyAppAPI internal constructor(
     clientSecret: String,
     token: Token,
     useCache: Boolean,
+    cacheLimit: Int?,
     automaticRefresh: Boolean,
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean
-) : SpotifyAPI(clientId, clientSecret, token, useCache, automaticRefresh, retryWhenRateLimited, enableLogger) {
+) : SpotifyAPI(clientId, clientSecret, token, useCache, cacheLimit, automaticRefresh, retryWhenRateLimited, enableLogger) {
 
     override val search: SearchAPI = SearchAPI(this)
     override val albums: AlbumAPI = AlbumAPI(this)
@@ -189,16 +202,17 @@ class SpotifyAppAPI internal constructor(
         throw BadRequestException("Either the client id or the client secret is not set")
     }
 
-    override fun clearCache() = clearAllCaches(
-            search,
-            albums,
-            browse,
-            artists,
-            playlists,
-            users,
-            tracks,
-            following
-    )
+    override val endpoints: List<SpotifyEndpoint>
+        get() = listOf(
+                search,
+                albums,
+                browse,
+                artists,
+                playlists,
+                users,
+                tracks,
+                following
+        )
 
     override fun getApiBuilder() = SpotifyApiBuilder(clientId, clientSecret, useCache)
 
@@ -223,9 +237,10 @@ class SpotifyClientAPI internal constructor(
     automaticRefresh: Boolean,
     var redirectUri: String,
     useCache: Boolean,
+    cacheLimit: Int?,
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean
-) : SpotifyAPI(clientId, clientSecret, token, useCache, automaticRefresh, retryWhenRateLimited, enableLogger) {
+) : SpotifyAPI(clientId, clientSecret, token, useCache, cacheLimit, automaticRefresh, retryWhenRateLimited, enableLogger) {
     override val search: SearchAPI = SearchAPI(this)
     override val albums: AlbumAPI = AlbumAPI(this)
     override val browse: BrowseAPI = BrowseAPI(this)
@@ -316,19 +331,20 @@ class SpotifyClientAPI internal constructor(
         } else throw BadRequestException(response.body.toObject<AuthenticationError>(this))
     }
 
-    override fun clearCache() = clearAllCaches(
-            search,
-            albums,
-            browse,
-            artists,
-            playlists,
-            users,
-            tracks,
-            following,
-            personalization,
-            library,
-            player
-    )
+    override val endpoints: List<SpotifyEndpoint>
+        get() = listOf(
+                search,
+                albums,
+                browse,
+                artists,
+                playlists,
+                users,
+                tracks,
+                following,
+                personalization,
+                library,
+                player
+        )
 
     override fun getApiBuilder() = SpotifyApiBuilder(clientId, clientSecret, redirectUri, useCache = useCache)
 

src/main/kotlin/com/adamratzman/spotify/http/Endpoints.kt

@@ -15,9 +15,10 @@ import java.net.HttpURLConnection
 import java.net.URLEncoder
 import java.util.Base64
 import java.util.function.Supplier
+import kotlin.math.ceil
 
 abstract class SpotifyEndpoint(val api: SpotifyAPI) {
-    internal val cache = SpotifyCache()
+    val cache = SpotifyCache()
 
     internal fun get(url: String): String {
         return execute(url)
@@ -139,17 +140,18 @@ internal class EndpointBuilder(private val path: String) {
     override fun toString() = builder.toString()
 }
 
-internal class SpotifyCache {
-    private val cachedRequests = hashMapOf<SpotifyRequest, CacheState>()
+class SpotifyCache {
+    val cachedRequests = mutableMapOf<SpotifyRequest, CacheState>()
 
     internal operator fun get(request: SpotifyRequest): CacheState? {
         checkCache(request)
         return cachedRequests[request]
     }
 
     internal operator fun set(request: SpotifyRequest, state: CacheState) {
-        checkCache(request)
         if (request.api.useCache) cachedRequests[request] = state
+
+        checkCache(request)
     }
 
     internal operator fun minusAssign(request: SpotifyRequest) {
@@ -161,17 +163,34 @@ internal class SpotifyCache {
 
     private fun checkCache(request: SpotifyRequest) {
         if (!request.api.useCache) clear()
+        else {
+            cachedRequests.entries.removeIf { !it.value.isStillValid() }
+
+            val cacheLimit = request.api.cacheLimit
+            val cacheUse = request.api.endpoints.sumBy { it.cache.cachedRequests.size }
+
+            if (cacheLimit != null && cacheUse > cacheLimit) {
+                val amountRemoveFromEach = ceil((cacheUse - cacheLimit).toDouble() / request.api.endpoints.size).toInt()
+
+                request.api.endpoints.forEach { endpoint ->
+                    val entries = endpoint.cache.cachedRequests.entries
+                    val toRemove = entries.sortedBy { it.value.expireBy }.take(amountRemoveFromEach)
+
+                    if (toRemove.isNotEmpty()) entries.removeAll(toRemove)
+                }
+            }
+        }
     }
 }
 
-internal data class SpotifyRequest(
+data class SpotifyRequest(
     val url: String,
     val method: HttpRequestMethod,
     val body: String?,
     val api: SpotifyAPI
 )
 
-internal data class CacheState(val data: String, val eTag: String?, val expireBy: Long = 0) {
+data class CacheState(val data: String, val eTag: String?, val expireBy: Long = 0) {
     private val cacheRegex = "max-age=(\\d+)".toRegex()
     internal fun isStillValid(): Boolean = System.currentTimeMillis() <= this.expireBy
 

src/main/kotlin/com/adamratzman/spotify/http/HttpConnection.kt

@@ -8,8 +8,8 @@ import java.net.URL
 import java.util.concurrent.Executors
 import java.util.concurrent.TimeUnit
 
-internal enum class HttpRequestMethod { GET, POST, PUT, DELETE }
-internal data class HttpHeader(val key: String, val value: String)
+enum class HttpRequestMethod { GET, POST, PUT, DELETE }
+data class HttpHeader(val key: String, val value: String)
 
 internal class HttpConnection(
     private val url: String,