feat: add support of any ValueLoader for LazyCache

Now any type of ValueLoader can be used as a loader for LazyCache - default loaders, custom loaders, any value loaders including stateful ones.

Author: romychab

README.md

@@ -34,7 +34,7 @@ The full documentation is available [here](https://docs.uandcode.com/container).
 Add the following line to your `build.gradle` file:
 
 ```
-implementation "com.elveum:container:2.1.0-beta04"
+implementation "com.elveum:container:2.1.0-beta05"
 ```
 
 ## Core Concepts

container/src/main/java/com/elveum/container/cache/LazyCache.kt

@@ -8,6 +8,7 @@ import com.elveum.container.factory.DEFAULT_CACHE_TIMEOUT_MILLIS
 import com.elveum.container.factory.DEFAULT_RELOAD_DEPENDENCIES_PERIOD_MILLIS
 import com.elveum.container.subject.ContainerConfiguration
 import com.elveum.container.subject.LazyFlowSubject
+import com.elveum.container.subject.ValueLoader
 import com.elveum.container.subject.transformation.ContainerTransformation
 import com.elveum.container.subject.transformation.EmptyContainerTransformation
 import kotlinx.coroutines.flow.Flow
@@ -121,8 +122,38 @@ public interface LazyCache<Arg, T> {
                 reloadDependenciesPeriodMillis = reloadDependenciesPeriodMillis,
                 coroutineScopeFactory = coroutineScopeFactory,
                 transformation = transformation,
-                valueLoader = valueLoader,
+                valueLoaderFactory = ValueLoaderFactory { arg ->
+                    ValueLoader { valueLoader.invoke(this, arg) }
+                },
             )
         }
+
+        /**
+         * Create a new instance of [LazyCache] using [ValueLoaderFactory].
+         *
+         * @param Arg the type of the argument used to identify cached entries.
+         * @param T the type of values held in the cache.
+         * @param cacheTimeoutMillis how much time cached values remain in cache if there is no collectors
+         * @param reloadDependenciesPeriodMillis how often dependencies are checked for reload triggers
+         * @param coroutineScopeFactory factory used to create coroutine scopes for loading
+         * @param transformation optional transformation applied to loaded containers
+         * @param valueLoaderFactory function that creates a separate value loader for the specific argument
+         */
+        public fun <Arg, T> createFromFactory(
+            cacheTimeoutMillis: Long = DEFAULT_CACHE_TIMEOUT_MILLIS,
+            reloadDependenciesPeriodMillis: Long = DEFAULT_RELOAD_DEPENDENCIES_PERIOD_MILLIS,
+            coroutineScopeFactory: CoroutineScopeFactory = CoroutineScopeFactory,
+            transformation: ContainerTransformation<T> = EmptyContainerTransformation(),
+            valueLoaderFactory: ValueLoaderFactory<Arg, T>,
+        ): LazyCache<Arg, T> {
+            return LazyCacheImpl(
+                cacheTimeoutMillis = cacheTimeoutMillis,
+                reloadDependenciesPeriodMillis = reloadDependenciesPeriodMillis,
+                coroutineScopeFactory = coroutineScopeFactory,
+                transformation = transformation,
+                valueLoaderFactory = valueLoaderFactory,
+            )
+        }
+
     }
 }

container/src/main/java/com/elveum/container/cache/LazyCacheExtensions.kt

@@ -4,7 +4,9 @@ import com.elveum.container.Container
 import com.elveum.container.LoadConfig
 import com.elveum.container.SourceType
 import com.elveum.container.factory.DEFAULT_CACHE_TIMEOUT_MILLIS
+import com.elveum.container.subject.ContainerConfiguration
 import com.elveum.container.transform
+import kotlinx.coroutines.flow.Flow
 
 public typealias SimpleCacheValueLoader<Arg, T> = suspend (Arg) -> T
 
@@ -78,3 +80,23 @@ public inline fun <Arg, T> LazyCache<Arg, T>.updateIfSuccess(
         )
     }
 }
+
+/**
+ * Listen for values loaded by the cache for the specific [arg] and
+ * for each emitted container:
+ * - attach a valid reload function
+ * - re-emit background load indicator if data is being reloaded.
+ */
+public fun <Arg, T> LazyCache<Arg, T>.listenReloadable(
+    arg: Arg,
+    emitReloadFunction: Boolean = true,
+    emitBackgroundLoads: Boolean = true,
+): Flow<Container<T>> {
+    return listen(
+        arg = arg,
+        configuration = ContainerConfiguration(
+            emitBackgroundLoads = emitBackgroundLoads,
+            emitReloadFunction = emitReloadFunction,
+        )
+    )
+}

container/src/main/java/com/elveum/container/cache/LazyCacheImpl.kt

@@ -26,7 +26,7 @@ internal class LazyCacheImpl<Arg, T>(
     private val coroutineScopeFactory: CoroutineScopeFactory,
     private val reloadDependenciesPeriodMillis: Long = DEFAULT_RELOAD_DEPENDENCIES_PERIOD_MILLIS,
     transformation: ContainerTransformation<T> = EmptyContainerTransformation(),
-    private val valueLoader: CacheValueLoader<Arg, T>,
+    private val valueLoaderFactory: ValueLoaderFactory<Arg, T>,
     private val subjectFactory: LazyFlowSubjectFactory<T> = LazyFlowSubjectFactory.Default(
         cacheTimeoutMillis, reloadDependenciesPeriodMillis, coroutineScopeFactory, transformation,
     )
@@ -78,9 +78,9 @@ internal class LazyCacheImpl<Arg, T>(
 
     private fun registerRecord(arg: Arg): CacheRecord<T> = synchronized(this) {
         val record = cacheSlots.getOrPut(arg) {
-            val subject = subjectFactory.create {
-                valueLoader.invoke(this, arg)
-            }
+            val subject = subjectFactory.create(
+                valueLoader = valueLoaderFactory.create(arg)
+            )
             CacheRecord(subject)
         }
         record.count++

container/src/main/java/com/elveum/container/cache/ValueLoaderFactory.kt

@@ -0,0 +1,10 @@
+package com.elveum.container.cache
+
+import com.elveum.container.subject.ValueLoader
+
+/**
+ * Create a new [ValueLoader] instance for the specific input argument.
+ */
+public fun interface ValueLoaderFactory<Arg, T> {
+    public fun create(arg: Arg): ValueLoader<T>
+}

container/src/main/java/com/elveum/container/factory/DefaultSubjectFactory.kt

@@ -1,6 +1,7 @@
 package com.elveum.container.factory
 
 import com.elveum.container.cache.CacheValueLoader
+import com.elveum.container.cache.ValueLoaderFactory
 import com.elveum.container.cache.LazyCache
 import com.elveum.container.subject.LazyFlowSubject
 import com.elveum.container.subject.ValueLoader
@@ -45,4 +46,20 @@ public open class DefaultSubjectFactory(
         )
     }
 
+    override fun <Arg, T> createCacheFromFactory(
+        cacheTimeoutMillis: Long?,
+        reloadDependenciesPeriodMillis: Long?,
+        coroutineScopeFactory: CoroutineScopeFactory?,
+        transformation: ContainerTransformation<T>?,
+        valueLoaderFactory: ValueLoaderFactory<Arg, T>
+    ): LazyCache<Arg, T> {
+        return LazyCache.createFromFactory(
+            valueLoaderFactory = valueLoaderFactory,
+            cacheTimeoutMillis = cacheTimeoutMillis ?: this.cacheTimeoutMillis,
+            reloadDependenciesPeriodMillis = reloadDependenciesPeriodMillis ?: this.reloadDependenciesPeriodMillis,
+            coroutineScopeFactory = coroutineScopeFactory ?: this.coroutineScopeFactory,
+            transformation = transformation ?: transformationFactory.create(),
+        )
+    }
+
 }

container/src/main/java/com/elveum/container/factory/SubjectFactory.kt

@@ -1,6 +1,7 @@
 package com.elveum.container.factory
 
 import com.elveum.container.cache.CacheValueLoader
+import com.elveum.container.cache.ValueLoaderFactory
 import com.elveum.container.cache.LazyCache
 import com.elveum.container.subject.LazyFlowSubject
 import com.elveum.container.subject.ValueLoader
@@ -38,6 +39,18 @@ public interface SubjectFactory {
         valueLoader: CacheValueLoader<Arg, T>,
     ): LazyCache<Arg, T>
 
+    /**
+     * Create a new [LazyCache] instance which creates a separate
+     * value loader for every argument using [ValueLoaderFactory].
+     */
+    public fun <Arg, T> createCacheFromFactory(
+        cacheTimeoutMillis: Long? = null,
+        reloadDependenciesPeriodMillis: Long? = null,
+        coroutineScopeFactory: CoroutineScopeFactory? = null,
+        transformation: ContainerTransformation<T>? = null,
+        valueLoaderFactory: ValueLoaderFactory<Arg, T>,
+    ): LazyCache<Arg, T>
+
     public companion object : SubjectFactory {
 
         @Volatile
@@ -65,6 +78,17 @@ public interface SubjectFactory {
                 coroutineScopeFactory, transformation, valueLoader)
         }
 
+        override fun <Arg, T> createCacheFromFactory(
+            cacheTimeoutMillis: Long?,
+            reloadDependenciesPeriodMillis: Long?,
+            coroutineScopeFactory: CoroutineScopeFactory?,
+            transformation: ContainerTransformation<T>?,
+            valueLoaderFactory: ValueLoaderFactory<Arg, T>
+        ): LazyCache<Arg, T> {
+            return instance.createCacheFromFactory(cacheTimeoutMillis, reloadDependenciesPeriodMillis,
+                coroutineScopeFactory, transformation, valueLoaderFactory)
+        }
+
         /**
          * Replace the default factory by the custom one.
          */

container/src/test/java/com/elveum/container/cache/LazyCacheExtensionsTest.kt

@@ -5,6 +5,7 @@ import com.elveum.container.Emitter
 import com.elveum.container.LoadConfig
 import com.elveum.container.errorContainer
 import com.elveum.container.pendingContainer
+import com.elveum.container.subject.ContainerConfiguration
 import com.elveum.container.successContainer
 import io.mockk.MockKAnnotations
 import io.mockk.coVerify
@@ -15,6 +16,7 @@ import io.mockk.mockkObject
 import io.mockk.slot
 import io.mockk.unmockkObject
 import io.mockk.verify
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.emptyFlow
 import kotlinx.coroutines.test.runTest
 import org.junit.Assert.assertSame
@@ -132,4 +134,34 @@ class LazyCacheExtensionsTest {
         }
     }
 
-}
+    @Test
+    fun listenReloadable_withDefaultArgs_delegatesArgs() {
+        val expectedResult = MutableStateFlow(successContainer(""))
+        every { lazyCache.listen(any(), any()) } returns expectedResult
+
+        val result = lazyCache.listenReloadable(arg = "1")
+
+        assertSame(expectedResult, result)
+        verify(exactly = 1) {
+            lazyCache.listen("1", ContainerConfiguration(true, true))
+        }
+    }
+
+    @Test
+    fun listenReloadable_withCustomArgs_delegatesArgs() {
+        val expectedResult = MutableStateFlow(successContainer(""))
+        every { lazyCache.listen(any(), any()) } returns expectedResult
+
+        val result = lazyCache.listenReloadable(
+            arg = "1",
+            emitReloadFunction = false,
+            emitBackgroundLoads = false,
+        )
+
+        assertSame(expectedResult, result)
+        verify(exactly = 1) {
+            lazyCache.listen("1", ContainerConfiguration(false, false))
+        }
+    }
+
+}

container/src/test/java/com/elveum/container/cache/LazyCacheIntegrationTest.kt

@@ -4,6 +4,7 @@ import com.elveum.container.Container
 import com.elveum.container.Emitter
 import com.elveum.container.LoadConfig
 import com.elveum.container.factory.CoroutineScopeFactory
+import com.elveum.container.subject.ValueLoader
 import com.elveum.container.successContainer
 import com.elveum.container.utils.raw
 import com.uandcode.flowtest.CollectStatus
@@ -53,7 +54,11 @@ class LazyCacheIntegrationTest {
         lazyCache = LazyCacheImpl(
             cacheTimeoutMillis = timeoutMillis,
             coroutineScopeFactory = coroutineScopeFactory,
-            valueLoader = this.loader,
+            valueLoaderFactory = { arg ->
+                ValueLoader {
+                    loader(this, arg)
+                }
+            },
         )
     }
 

container/src/test/java/com/elveum/container/cache/LazyCacheTest.kt

@@ -60,7 +60,11 @@ class LazyCacheTest {
         lazyCache = LazyCacheImpl(
             cacheTimeoutMillis = timeoutMillis,
             coroutineScopeFactory = coroutineScopeFactory,
-            valueLoader = loader,
+            valueLoaderFactory = { arg ->
+                ValueLoader {
+                    loader(this, arg)
+                }
+            },
             subjectFactory = subjectFactory,
         )
     }