feat(LazyMaker): 新增 SupplierLazy 工具以及对应的测试单元

Author: Bkm016

common-util/src/main/kotlin/taboolib/common/util/LazyMaker.kt

@@ -2,6 +2,8 @@ package taboolib.common.util
 
 import com.google.common.cache.Cache
 import com.google.common.cache.CacheBuilder
+import java.util.Optional
+import java.util.concurrent.ConcurrentHashMap
 
 /**
  * 声明一个线程不安全的延迟加载对象
@@ -27,6 +29,52 @@ fun <T> resettableLazy(vararg groups: String, synchronized: Boolean = false, ini
     }
 }
 
+/**
+ * 声明一个需要传入上下文对象才能初始化的延迟加载对象
+ *
+ * @param C 上下文类型
+ * @param T 值类型
+ * @param typeIsolation 是否进行类型隔离，如果为 true，传入不同类型的 context 时会重新初始化
+ * @param initializer 初始化函数，接收上下文对象并返回值
+ */
+fun <C, T> supplierLazy(typeIsolation: Boolean = false, initializer: (C) -> T): SupplierLazy<C, T> {
+    return if (typeIsolation) {
+        SupplierLazyWithTypeIsolationImpl(initializer)
+    } else {
+        SupplierLazyImpl(initializer)
+    }
+}
+
+/**
+ * 包装上下文对象
+ * 在 [SupplierLazy] 中使用时，当需要携带额外数据时使用
+ */
+data class WrappedContext<C: Any, E: Any>(val context: C, val extra: E)
+
+/**
+ * 需要传入上下文对象的延迟加载接口
+ */
+interface SupplierLazy<C, T> {
+
+    /**
+     * 传入上下文对象获取值
+     *
+     * @param context 上下文对象
+     * @return 初始化后的值
+     */
+    operator fun get(context: C): T
+
+    /**
+     * 检查是否已初始化
+     */
+    fun isInitialized(): Boolean
+
+    /**
+     * 重置状态
+     */
+    fun reset()
+}
+
 abstract class ResettableLazy<T>(vararg val groups: String) : Lazy<T> {
 
     abstract fun reset()
@@ -106,4 +154,47 @@ private class ResettableSynchronizedLazyImpl<T>(vararg groups: String, initializ
     override fun toString() = if (isInitialized()) value.toString() else "Lazy(${groups.joinToString()}) value not initialized yet."
 }
 
+private class SupplierLazyImpl<C, T>(private val initializer: (C) -> T) : SupplierLazy<C, T> {
+
+    private var localValue: Any? = UninitializedValue
+
+    @Suppress("UNCHECKED_CAST")
+    override fun get(context: C): T {
+        if (localValue === UninitializedValue) {
+            localValue = initializer(context)
+        }
+        return localValue as T
+    }
+
+    override fun isInitialized() = localValue !== UninitializedValue
+
+    override fun reset() {
+        localValue = UninitializedValue
+    }
+
+    override fun toString() = if (isInitialized()) localValue.toString() else "SupplierLazy value not initialized yet."
+}
+
+private class SupplierLazyWithTypeIsolationImpl<C, T>(private val initializer: (C) -> T) : SupplierLazy<C, T> {
+
+    private val valueMap = ConcurrentHashMap<Class<*>, Optional<T>>()
+
+    @Suppress("UNCHECKED_CAST")
+    override fun get(context: C): T {
+        val contextClass = if (context is WrappedContext<*, *>) context.context::class.java else context!!::class.java
+        val optional = valueMap.computeIfAbsent(contextClass) {
+            Optional.ofNullable(initializer(context)) as Optional<T>
+        }
+        return optional.orElse(null as T)
+    }
+
+    override fun isInitialized() = valueMap.isNotEmpty()
+
+    override fun reset() {
+        valueMap.clear()
+    }
+
+    override fun toString() = if (isInitialized()) "SupplierLazy(typeIsolation) with ${valueMap.size} type(s) initialized" else "SupplierLazy(typeIsolation) value not initialized yet."
+}
+
 internal object UninitializedValue

common-util/src/test/kotlin/taboolib/common/util/SupplierLazy.kt

@@ -0,0 +1,285 @@
+package taboolib.common.util
+
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.Assertions.*
+
+class SupplierLazyTest {
+
+    @Test
+    fun `test basic supplier lazy initialization`() {
+        var initCount = 0
+        val lazy = supplierLazy<String, String> { context ->
+            initCount++
+            "Hello $context"
+        }
+
+        assertFalse(lazy.isInitialized())
+
+        val result1 = lazy["World"]
+        assertEquals("Hello World", result1)
+        assertEquals(1, initCount)
+        assertTrue(lazy.isInitialized())
+
+        // Should return cached value, not reinitialize
+        val result2 = lazy["Different"]
+        assertEquals("Hello World", result2)
+        assertEquals(1, initCount)
+    }
+
+    @Test
+    fun `test supplier lazy with null value`() {
+        val lazy = supplierLazy<String, String?> { null }
+
+        assertFalse(lazy.isInitialized())
+        val result = lazy["test"]
+        assertNull(result)
+        assertTrue(lazy.isInitialized())
+    }
+
+    @Test
+    fun `test supplier lazy reset`() {
+        var initCount = 0
+        val lazy = supplierLazy<Int, String> { context ->
+            initCount++
+            "Count: $context"
+        }
+
+        lazy[1]
+        assertEquals(1, initCount)
+        assertTrue(lazy.isInitialized())
+
+        lazy.reset()
+        assertFalse(lazy.isInitialized())
+
+        lazy[2]
+        assertEquals(2, initCount)
+        assertTrue(lazy.isInitialized())
+    }
+
+    @Test
+    fun `test supplier lazy with type isolation disabled`() {
+        var initCount = 0
+        val lazy = supplierLazy<Any, String>(typeIsolation = false) { context ->
+            initCount++
+            "Value: ${context::class.simpleName}"
+        }
+
+        val result1 = lazy["String"]
+        assertEquals("Value: String", result1)
+        assertEquals(1, initCount)
+
+        // Different type but should return cached value
+        val result2 = lazy[123]
+        assertEquals("Value: String", result2)
+        assertEquals(1, initCount)
+    }
+
+    @Test
+    fun `test supplier lazy with type isolation enabled`() {
+        var initCount = 0
+        val lazy = supplierLazy<Any, String>(typeIsolation = true) { context ->
+            initCount++
+            "Value: ${context::class.simpleName}-$context"
+        }
+
+        assertFalse(lazy.isInitialized())
+
+        val result1 = lazy["String"]
+        assertEquals("Value: String-String", result1)
+        assertEquals(1, initCount)
+        assertTrue(lazy.isInitialized())
+
+        // Different type should reinitialize
+        val result2 = lazy[123]
+        assertEquals("Value: Int-123", result2)
+        assertEquals(2, initCount)
+
+        // Same type as first should return cached value
+        val result3 = lazy["Different"]
+        assertEquals("Value: String-String", result3)
+        assertEquals(2, initCount)
+
+        // Same type as second should return cached value
+        val result4 = lazy[456]
+        assertEquals("Value: Int-123", result4)
+        assertEquals(2, initCount)
+    }
+
+    @Test
+    fun `test supplier lazy with type isolation and null values`() {
+        var initCount = 0
+        val lazy = supplierLazy<Any, String?>(typeIsolation = true) { context ->
+            initCount++
+            when (context) {
+                is String -> "String: $context"
+                is Int -> null
+                else -> "Other: $context"
+            }
+        }
+
+        val result1 = lazy["test"]
+        assertEquals("String: test", result1)
+        assertEquals(1, initCount)
+
+        val result2 = lazy[42]
+        assertNull(result2)
+        assertEquals(2, initCount)
+
+        val result3 = lazy[99]
+        assertNull(result3)
+        assertEquals(2, initCount) // Should use cached null value
+    }
+
+    @Test
+    fun `test supplier lazy with type isolation reset`() {
+        var initCount = 0
+        val lazy = supplierLazy<Any, String>(typeIsolation = true) { context ->
+            initCount++
+            "Init: $initCount"
+        }
+
+        lazy["String"]
+        lazy[123]
+        assertEquals(2, initCount)
+        assertTrue(lazy.isInitialized())
+
+        lazy.reset()
+        assertFalse(lazy.isInitialized())
+
+        lazy["NewString"]
+        lazy[456]
+        assertEquals(4, initCount)
+    }
+
+    @Test
+    fun `test supplier lazy with custom classes`() {
+        data class Person(val name: String)
+        data class Animal(val species: String)
+
+        val lazy = supplierLazy<Any, String>(typeIsolation = true) { context ->
+            when (context) {
+                is Person -> "Person: ${context.name}"
+                is Animal -> "Animal: ${context.species}"
+                else -> "Unknown"
+            }
+        }
+
+        val result1 = lazy[Person("Alice")]
+        assertEquals("Person: Alice", result1)
+
+        val result2 = lazy[Animal("Dog")]
+        assertEquals("Animal: Dog", result2)
+
+        // Same type should return cached
+        val result3 = lazy[Person("Bob")]
+        assertEquals("Person: Alice", result3)
+
+        val result4 = lazy[Animal("Cat")]
+        assertEquals("Animal: Dog", result4)
+    }
+
+    @Test
+    fun `test supplier lazy toString`() {
+        val lazy1 = supplierLazy<String, Int> { it.length }
+        assertTrue(lazy1.toString().contains("not initialized"))
+
+        lazy1["test"]
+        assertFalse(lazy1.toString().contains("not initialized"))
+
+        val lazy2 = supplierLazy<String, Int>(typeIsolation = true) { it.length }
+        assertTrue(lazy2.toString().contains("not initialized"))
+
+        lazy2["test"]
+        assertTrue(lazy2.toString().contains("typeIsolation"))
+        assertTrue(lazy2.toString().contains("1 type(s)"))
+    }
+
+    @Test
+    fun `test wrapped context basic isolation`() {
+        var initCount = 0
+        val lazy = supplierLazy<WrappedContext<Any, String>, String>(typeIsolation = true) { ctx ->
+            initCount++
+            "${ctx.context}:${ctx.extra}"
+        }
+
+        val c1: WrappedContext<Any, String> = WrappedContext("user" as Any, "a")
+        val c2: WrappedContext<Any, String> = WrappedContext("user" as Any, "b")
+        val c3: WrappedContext<Any, String> = WrappedContext(123 as Any, "x")
+
+        // 同一个 context 类型（String），虽然 extra 不同，但因为按 context.class 做隔离，只初始化一次
+        val r1 = lazy[c1]
+        val r2 = lazy[c2]
+        assertEquals("user:a", r1)
+        assertEquals("user:a", r2)
+        assertEquals(1, initCount)
+
+        // 不同 context 类型（Int），会使用另一份缓存
+        val r3 = lazy[c3]
+        assertEquals("123:x", r3)
+        assertEquals(2, initCount)
+    }
+
+    @Test
+    fun `test wrapped context mixed with plain context`() {
+        var initCount = 0
+        val lazy = supplierLazy<Any, String>(typeIsolation = true) { ctx ->
+            initCount++
+            when (ctx) {
+                is WrappedContext<*, *> -> "wrapped:${ctx.context}:${ctx.extra}"
+                else -> "plain:$ctx"
+            }
+        }
+
+        val plain: Any = "user"
+        val wrapped1: Any = WrappedContext("user", "a")
+        val wrapped2: Any = WrappedContext("user", "b")
+
+        // 第一次：普通 String 上下文
+        val rPlain1 = lazy[plain]
+        assertEquals("plain:user", rPlain1)
+        assertEquals(1, initCount)
+
+        // 第二次：WrappedContext，同样的 context 类型 String，但因为 SupplierLazyWithTypeIsolationImpl
+        // 对 WrappedContext 使用 context.context::class.java 作为 key，会与 plain 的 String 类型共用缓存
+        val rWrapped1 = lazy[wrapped1]
+        assertEquals("plain:user", rWrapped1)
+        assertEquals(1, initCount)
+
+        // 第三次：另一个 WrappedContext，仍然命中同一个 String 类型缓存
+        val rWrapped2 = lazy[wrapped2]
+        assertEquals("plain:user", rWrapped2)
+        assertEquals(1, initCount)
+
+        // 验证 Int 类型仍然是独立的缓存 key
+        val rInt1 = lazy[123 as Any]
+        assertEquals("plain:123", rInt1)
+        assertEquals(2, initCount)
+    }
+
+    @Test
+    fun `test wrapped context reset isolation map`() {
+        var initCount = 0
+        val lazy = supplierLazy<WrappedContext<Any, String>, String>(typeIsolation = true) { ctx ->
+            initCount++
+            "${ctx.context}:${ctx.extra}:$initCount"
+        }
+
+        val sCtx: WrappedContext<Any, String> = WrappedContext("user" as Any, "a")
+        val iCtx: WrappedContext<Any, String> = WrappedContext(1 as Any, "x")
+
+        val r1 = lazy[sCtx]
+        val r2 = lazy[iCtx]
+        assertEquals("user:a:1", r1)
+        assertEquals("1:x:2", r2)
+        assertEquals(2, initCount)
+
+        lazy.reset()
+        assertFalse(lazy.isInitialized())
+
+        val r3 = lazy[sCtx]
+        val r4 = lazy[iCtx]
+        assertEquals("user:a:3", r3)
+        assertEquals("1:x:4", r4)
+        assertEquals(4, initCount)
+    }
+}