Class Lazy<T>

java.lang.Object
cloud.opencode.base.functional.monad.Lazy<T>
Type Parameters:
T - value type - 值类型
All Implemented Interfaces:
Supplier<T>
public final class Lazy<T> extends Object implements Supplier<T>
Lazy - Lazy evaluation container Lazy - 惰性求值容器

A container that delays computation until the value is actually needed. The computation is performed at most once, and the result is cached.

延迟计算直到实际需要值的容器。计算最多执行一次，结果会被缓存。

Features | 主要功能:

  • Deferred computation - 延迟计算
  • Single evaluation (memoization) - 单次求值（记忆化）
  • Thread-safe (double-checked locking) - 线程安全（双重检查锁）
  • Monadic operations (map, flatMap, filter) - Monad 操作

Usage Examples | 使用示例:

// Deferred computation
Lazy<ExpensiveObject> lazy = Lazy.of(() -> createExpensiveObject());

// Value not computed yet
assertFalse(lazy.isEvaluated());

// Computed on first access
ExpensiveObject obj = lazy.get();
assertTrue(lazy.isEvaluated());

// Cached on subsequent access
ExpensiveObject same = lazy.get();  // No recomputation

// Chained lazy operations
Lazy<String> result = Lazy.of(() -> fetchData())
    .map(this::process)
    .map(this::format);
// Nothing computed until result.get()

Performance | 性能特性:

  • First get(): O(computation time) - 首次 get(): O(计算时间)
  • Subsequent get(): O(1) - 后续 get(): O(1)
  • Memory: Holds supplier until evaluated - 内存: 保持 supplier 直到求值

Security | 安全性:

  • Thread-safe: Yes (DCL) - 线程安全: 是 (双重检查锁)
  • Null-safe: Allows null results - 空值安全: 允许 null 结果
Since:
JDK 25, opencode-base-functional V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Lazy<T>
    filter(Predicate<? super T> predicate)
    Filter the value lazily 惰性过滤值
    <U> Lazy<U>
    flatMap(Function<? super T, Lazy<U>> mapper)
    Transform to another Lazy lazily 惰性转换为另一个 Lazy
    T
    get()
    Get the value, computing if necessary 获取值，必要时进行计算
    T
    getOrElse(Supplier<? extends T> supplier)
    Get value or compute default if evaluation throws 获取值或计算默认值（如果求值抛出异常）
    T
    getOrElse(T defaultValue)
    Get value or default if evaluation throws 获取值或默认值（如果求值抛出异常）
    boolean
    isEvaluated()
    Check if the value has been evaluated 检查值是否已被求值
    <U> Lazy<U>
    map(Function<? super T, ? extends U> mapper)
    Transform the value lazily 惰性转换值
    static <T> Lazy<T>
    of(Supplier<T> supplier)
    Create a Lazy from supplier 从供应商创建 Lazy
    Option<T>
    toOption()
    Convert to Option 转换为 Option
    String
    toString()
     
    Try<T>
    toTry()
    Convert to Try 转换为 Try
    static <T> Lazy<T>
    value(T value)
    Create an already-evaluated Lazy with value 创建已求值的 Lazy

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static <T> Lazy<T> of(Supplier<T> supplier)
      Create a Lazy from supplier 从供应商创建 Lazy
      Type Parameters:
      T - value type - 值类型
      Parameters:
      supplier - value supplier (evaluated lazily) - 值供应商（惰性求值）
      Returns:
      Lazy container

    • value

      public static <T> Lazy<T> value(T value)
      Create an already-evaluated Lazy with value 创建已求值的 Lazy
      Type Parameters:
      T - value type - 值类型
      Parameters:
      value - the value - 值
      Returns:
      already-evaluated Lazy

    • get

      public T get()
      Get the value, computing if necessary 获取值，必要时进行计算

      Thread-safe with double-checked locking.

      使用双重检查锁保证线程安全。

      Specified by:
      get in interface Supplier<T>
      Returns:
      the computed value - 计算后的值

    • isEvaluated

      public boolean isEvaluated()
      Check if the value has been evaluated 检查值是否已被求值
      Returns:
      true if evaluated - 如果已求值返回 true

    • map

      public <U> Lazy<U> map(Function<? super T, ? extends U> mapper)
      Transform the value lazily 惰性转换值

      The mapper is not applied until the result's get() is called.

      映射函数在结果的 get() 被调用前不会执行。

      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      lazy transformed value

    • flatMap

      public <U> Lazy<U> flatMap(Function<? super T, Lazy<U>> mapper)
      Transform to another Lazy lazily 惰性转换为另一个 Lazy
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function returning Lazy - 返回 Lazy 的转换函数
      Returns:
      lazy result

    • filter

      public Lazy<T> filter(Predicate<? super T> predicate)
      Filter the value lazily 惰性过滤值

      If the predicate is not satisfied, get() throws NoSuchElementException.

      如果谓词不满足，get() 抛出 NoSuchElementException。

      Parameters:
      predicate - filter condition - 过滤条件
      Returns:
      filtered Lazy

    • getOrElse

      public T getOrElse(T defaultValue)
      Get value or default if evaluation throws 获取值或默认值（如果求值抛出异常）
      Parameters:
      defaultValue - default value on error - 错误时的默认值
      Returns:
      value or default

    • getOrElse

      public T getOrElse(Supplier<? extends T> supplier)
      Get value or compute default if evaluation throws 获取值或计算默认值（如果求值抛出异常）
      Parameters:
      supplier - default value supplier - 默认值供应商
      Returns:
      value or computed default

    • toTry

      public Try<T> toTry()
      Convert to Try 转换为 Try
      Returns:
      Try containing the result or exception

    • toOption

      public Option<T> toOption()
      Convert to Option 转换为 Option
      Returns:
      Option (None if evaluation throws or returns null)

    • toString

      public String toString()
      Overrides:
      toString in class Object