Interface Either<L,R>

Type Parameters:
L - left type (typically error) - 左类型（通常为错误）
R - right type (typically success) - 右类型（通常为成功）
All Known Implementing Classes:
Either.Left, Either.Right
public sealed interface Either<L,R> permits Either.Left<L,R>, Either.Right<L,R>
Either Monad - Represents one of two possible values (Left or Right) Either Monad - 表示两种可能值之一（Left 或 Right）

A sealed type that contains either a Left value (typically for errors) or a Right value (typically for success). By convention, Right is the "happy path".

一个密封类型，包含 Left 值（通常表示错误）或 Right 值（通常表示成功）。 按照惯例，Right 是"正常路径"。

Features | 主要功能:

  • Type-safe error handling - 类型安全的错误处理
  • Right-biased operations - Right 倾向的操作
  • Monadic operations (map, flatMap) - Monad 操作
  • Folding/pattern matching - 折叠/模式匹配
  • Swap operation - 交换操作
  • Conversion to Result, Optional, Stream - 转换为 Result、Optional、Stream

Usage Examples | 使用示例:

// Creating Either values
Either<String, User> success = Either.right(user);
Either<String, User> error = Either.left("User not found");

// Returning from methods
public Either<String, User> findUser(Long id) {
    User user = userRepository.findById(id);
    return user == null
        ? Either.left("User not found: " + id)
        : Either.right(user);
}

// Using the result
findUser(1L)
    .map(User::getName)
    .fold(
        error -> log.error(error),
        name -> log.info("Found: " + name)
    );

// Pattern matching with switch (JDK 25)
switch (either) {
    case Either.Left(var err)  -> handleError(err);
    case Either.Right(var val) -> handleSuccess(val);
}

Security | 安全性:

  • Thread-safe: Yes (immutable records) - 线程安全: 是 (不可变记录)
  • Null-safe: Allows null values - 空值安全: 允许 null 值
Since:
JDK 25, opencode-base-core V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Either.Left<L,R>
    Left - Represents the left case (typically error) Left - 表示左情况（通常为错误）
    static final record 
    Either.Right<L,R>
    Right - Represents the right case (typically success) Right - 表示右情况（通常为成功）

  • Method Summary

    Modifier and Type
    Method
    Description
    <L2,R2> Either<L2,R2>
    bimap(Function<? super L, ? extends L2> leftMapper, Function<? super R, ? extends R2> rightMapper)
    Transform both sides 转换两侧的值
    <U> Either<L,U>
    flatMap(Function<? super R, Either<L,U>> mapper)
    Transform the Right value to another Either 将 Right 值转换为另一个 Either
    <T> T
    fold(Function<? super L, ? extends T> leftMapper, Function<? super R, ? extends T> rightMapper)
    Fold both cases to a single result 将两种情况折叠为单一结果
    Optional<L>
    getLeft()
    Get the Left value if present 获取 Left 值（如果存在）
    R
    getOrElse(R defaultValue)
    Get Right value or default if Left 获取 Right 值或默认值（如果是 Left）
    Optional<R>
    getRight()
    Get the Right value if present 获取 Right 值（如果存在）
    boolean
    isLeft()
    Check if this is a Left 检查是否为 Left
    boolean
    isRight()
    Check if this is a Right 检查是否为 Right
    static <L,R> Either<L,R>
    left(L value)
    Create a Left Either 创建 Left Either
    <U> Either<L,U>
    map(Function<? super R, ? extends U> mapper)
    Transform the Right value 转换 Right 值
    <U> Either<U,R>
    mapLeft(Function<? super L, ? extends U> mapper)
    Transform the Left value 转换 Left 值
    Either<L,R>
    orElse(Either<L,R> other)
    Return this or other Either if Left 返回本 Either 或其他 Either（如果是 Left）
    Either<L,R>
    peek(Consumer<? super R> action)
    Execute action on Right value 对 Right 值执行操作
    Either<L,R>
    peekLeft(Consumer<? super L> action)
    Execute action on Left value 对 Left 值执行操作
    static <L,R> Either<L,R>
    right(R value)
    Create a Right Either 创建 Right Either
    Stream<R>
    stream()
    Convert to Stream.
    Either<R,L>
    swap()
    Swap Left and Right 交换 Left 和 Right
    Optional<R>
    toOptional()
    Convert to Optional.
    Result<R>
    toResult()
    Convert to Result.
    <X extends Throwable>
    Result<R>
    toResult(Function<L,X> leftToThrowable)
    Convert to Result with a type-safe left-to-throwable conversion function.

  • Method Details

    • left

      static <L,R> Either<L,R> left(L value)
      Create a Left Either 创建 Left Either
      Type Parameters:
      L - left type - 左类型
      R - right type - 右类型
      Parameters:
      value - left value - 左值
      Returns:
      Left Either

    • right

      static <L,R> Either<L,R> right(R value)
      Create a Right Either 创建 Right Either
      Type Parameters:
      L - left type - 左类型
      R - right type - 右类型
      Parameters:
      value - right value - 右值
      Returns:
      Right Either

    • isLeft

      boolean isLeft()
      Check if this is a Left 检查是否为 Left
      Returns:
      true if Left - 如果是 Left 返回 true

    • isRight

      boolean isRight()
      Check if this is a Right 检查是否为 Right
      Returns:
      true if Right - 如果是 Right 返回 true

    • getLeft

      Optional<L> getLeft()
      Get the Left value if present 获取 Left 值（如果存在）
      Returns:
      Optional containing Left value

    • getRight

      Optional<R> getRight()
      Get the Right value if present 获取 Right 值（如果存在）
      Returns:
      Optional containing Right value

    • map

      <U> Either<L,U> map(Function<? super R, ? extends U> mapper)
      Transform the Right value 转换 Right 值
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      transformed Either

    • flatMap

      <U> Either<L,U> flatMap(Function<? super R, Either<L,U>> mapper)
      Transform the Right value to another Either 将 Right 值转换为另一个 Either
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function returning Either - 返回 Either 的转换函数
      Returns:
      resulting Either

    • mapLeft

      <U> Either<U,R> mapLeft(Function<? super L, ? extends U> mapper)
      Transform the Left value 转换 Left 值
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      transformed Either

    • bimap

      <L2,R2> Either<L2,R2> bimap(Function<? super L, ? extends L2> leftMapper, Function<? super R, ? extends R2> rightMapper)
      Transform both sides 转换两侧的值
      Type Parameters:
      L2 - new left type - 新的左类型
      R2 - new right type - 新的右类型
      Parameters:
      leftMapper - transformation for Left - Left 的转换函数
      rightMapper - transformation for Right - Right 的转换函数
      Returns:
      transformed Either

    • getOrElse

      R getOrElse(R defaultValue)
      Get Right value or default if Left 获取 Right 值或默认值（如果是 Left）
      Parameters:
      defaultValue - default value - 默认值
      Returns:
      Right value or default

    • orElse

      Either<L,R> orElse(Either<L,R> other)
      Return this or other Either if Left 返回本 Either 或其他 Either（如果是 Left）
      Parameters:
      other - alternative Either - 备选 Either
      Returns:
      this if Right, other if Left

    • fold

      <T> T fold(Function<? super L, ? extends T> leftMapper, Function<? super R, ? extends T> rightMapper)
      Fold both cases to a single result 将两种情况折叠为单一结果
      Type Parameters:
      T - result type - 结果类型
      Parameters:
      leftMapper - function for Left - Left 的函数
      rightMapper - function for Right - Right 的函数
      Returns:
      folded result

    • swap

      Either<R,L> swap()
      Swap Left and Right 交换 Left 和 Right
      Returns:
      swapped Either

    • peek

      Either<L,R> peek(Consumer<? super R> action)
      Execute action on Right value 对 Right 值执行操作
      Parameters:
      action - action to execute - 要执行的操作
      Returns:
      this Either for chaining

    • peekLeft

      Either<L,R> peekLeft(Consumer<? super L> action)
      Execute action on Left value 对 Left 值执行操作
      Parameters:
      action - action to execute - 要执行的操作
      Returns:
      this Either for chaining

    • toOptional

      Optional<R> toOptional()
      Convert to Optional. Right value becomes Optional.of(value), Left becomes Optional.empty(). 转换为 Optional。Right 值变为 Optional.of(value)，Left 变为 Optional.empty()。
      Returns:
      Optional containing the Right value, or empty if Left

    • stream

      Stream<R> stream()
      Convert to Stream. Right value becomes a single-element Stream, Left becomes an empty Stream. 转换为 Stream。Right 值变为单元素 Stream，Left 变为空 Stream。
      Returns:
      Stream containing the Right value, or empty if Left

    • toResult

      Result<R> toResult()
      Convert to Result. Right becomes Result.success, Left(Throwable) becomes Result.failure, Left(other) becomes Result.failure(new OpenException(L.toString())). 转换为 Result。Right 变为 Result.success，Left(Throwable) 变为 Result.failure， Left(其他) 变为 Result.failure(new OpenException(L.toString()))。
      Returns:
      Result representation of this Either

    • toResult

      <X extends Throwable> Result<R> toResult(Function<L,X> leftToThrowable)
      Convert to Result with a type-safe left-to-throwable conversion function. 使用类型安全的 left-to-throwable 转换函数转换为 Result。
      Type Parameters:
      X - the throwable type - 异常类型
      Parameters:
      leftToThrowable - function to convert Left value to a Throwable - 将 Left 值转换为 Throwable 的函数
      Returns:
      Result representation of this Either