java.lang.Object

cloud.opencode.base.functional.optics.OptionalLens<S,A>

Type Parameters:: S - source/whole type - 源/整体类型; A - target/part type - 目标/部分类型

public final class OptionalLens<S,A> extends Object

OptionalLens - Functional lens for optional data access OptionalLens - 用于可选数据访问的函数式透镜

A lens variant that handles cases where the focused part might not exist. The getter returns Optional, and set/modify operations only apply if the target exists.

处理聚焦部分可能不存在的情况的透镜变体。getter 返回 Optional， set/modify 操作仅在目标存在时应用。

Features | 主要功能:

Optional get - 可选获取
Safe set/modify - 安全设置/修改
Composable with Lens - 可与 Lens 组合
Null-safe operations - 空值安全操作

Usage Examples | 使用示例:

// Define optional lens for nullable field
OptionalLens<User, Address> addressLens = OptionalLens.of(
    user -> Optional.ofNullable(user.address()),
    (user, addr) -> new User(user.name(), addr)
);

// Safe get
Optional<Address> address = addressLens.get(user);

// Set (always works)
User updated = addressLens.set(user, newAddress);

// Modify only if present
User modified = addressLens.modify(user, Address::normalize);

// Compose with regular lens
Lens<Address, String> cityLens = ...;
OptionalLens<User, String> userCityLens = addressLens.andThen(cityLens);

// For collections
OptionalLens<Team, Member> firstMember = OptionalLens.of(
    team -> team.members().stream().findFirst(),
    (team, member) -> team.withFirstMember(member)
);

Use Cases | 使用场景:

Nullable fields - 可空字段
Collection elements - 集合元素
Map values - Map 值
Conditional paths - 条件路径

Performance | 性能特性:

Get: O(1) + Optional wrapping - 获取: O(1) + Optional 包装
Set: O(1) - 设置: O(1)
Modify: O(1) with short-circuit - 修改: O(1) 带短路

Security | 安全性:

Thread-safe: Yes (immutable) - 线程安全: 是 (不可变)
Null-safe: Yes - 空值安全: 是

Since:

JDK 25, opencode-base-functional V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

<B> OptionalLens<S,B>

andThen(Lens<A,B> other)

Compose with a regular lens 与常规透镜组合

<B> OptionalLens<S,B>

andThen(OptionalLens<A,B> other)

Compose with another optional lens 与另一个可选透镜组合

<T> OptionalLens<T,A>

compose(Lens<T,S> other)

Compose with a regular lens (other first, then this) 与常规透镜组合（先其他，然后此）

<T> OptionalLens<T,A>

compose(OptionalLens<T,S> other)

Compose with this lens (other first, then this) 与此透镜组合（先其他，然后此）

static <S,A> OptionalLens<S,A>

fromLens(Lens<S,A> lens)

Create from a regular lens 从常规透镜创建

Optional<A>

get(S source)

Get the optional focused value 获取可选的聚焦值

A

getOrElse(S source, A defaultValue)

Get the focused value or default 获取聚焦值或默认值

Function<S, Optional<A>>

getter()

Get the getter function 获取 getter 函数

boolean

isPresent(S source)

Check if the focused value is present 检查聚焦值是否存在

S

modify(S source, UnaryOperator<A> modifier)

Modify the focused value if present 如果存在则修改聚焦值

S

modifyOrSet(S source, UnaryOperator<A> modifier, A defaultValue)

Modify the focused value, or set default if not present 修改聚焦值，如果不存在则设置默认值

static <S,A> OptionalLens<S,A>

of(Function<S, Optional<A>> getter, BiFunction<S,A,S> setter)

Create an optional lens from getter and setter 从 getter 和 setter 创建可选透镜

static <S,A> OptionalLens<S,A>

ofNullable(Function<S,A> getter, BiFunction<S,A,S> setter)

Create an optional lens from nullable getter 从可空 getter 创建可选透镜

S

set(S source, A value)

Set the focused value 设置聚焦值

S

setIfPresent(S source, Optional<A> value)

Set the focused value if present in Optional 如果 Optional 中存在则设置聚焦值

BiFunction<S,A,S>

setter()

Get the setter function 获取 setter 函数

String

toString()

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details
- of
  
  public static <S,A> OptionalLens<S,A> of(Function<S, Optional<A>> getter, BiFunction<S,A,S> setter)
  
  Create an optional lens from getter and setter 从 getter 和 setter 创建可选透镜
  
  Type Parameters:
  
  S - source type - 源类型
  
  A - target type - 目标类型
  
  Parameters:
  
  getter - function to get the optional part - 获取可选部分的函数
  
  setter - function to set the part - 设置部分的函数
  
  Returns:
  
  optional lens
- ofNullable
  
  public static <S,A> OptionalLens<S,A> ofNullable(Function<S,A> getter, BiFunction<S,A,S> setter)
  
  Create an optional lens from nullable getter 从可空 getter 创建可选透镜
  
  Type Parameters:
  
  S - source type - 源类型
  
  A - target type - 目标类型
  
  Parameters:
  
  getter - function to get nullable part - 获取可空部分的函数
  
  setter - function to set the part - 设置部分的函数
  
  Returns:
  
  optional lens
- fromLens
  
  public static <S,A> OptionalLens<S,A> fromLens(Lens<S,A> lens)
  
  Create from a regular lens 从常规透镜创建
  
  Type Parameters:
  
  S - source type - 源类型
  
  A - target type - 目标类型
  
  Parameters:
  
  lens - the lens - 透镜
  
  Returns:
  
  optional lens
- get
  
  public Optional<A> get(S source)
  
  Get the optional focused value 获取可选的聚焦值
  
  Parameters:
  
  source - the source structure - 源结构
  
  Returns:
  
  Optional containing the value if present
- getOrElse
  
  public A getOrElse(S source, A defaultValue)
  
  Get the focused value or default 获取聚焦值或默认值
  
  Parameters:
  
  source - the source structure - 源结构
  
  defaultValue - default if not present - 不存在时的默认值
  
  Returns:
  
  the value or default
- isPresent
  
  public boolean isPresent(S source)
  
  Check if the focused value is present 检查聚焦值是否存在
  
  Parameters:
  
  source - the source structure - 源结构
  
  Returns:
  
  true if present
- set
  
  public S set(S source, A value)
  
  Set the focused value 设置聚焦值
  
  Parameters:
  
  source - the source structure - 源结构
  
  value - the new value - 新值
  
  Returns:
  
  new source with updated part
- setIfPresent
  
  public S setIfPresent(S source, Optional<A> value)
  
  Set the focused value if present in Optional 如果 Optional 中存在则设置聚焦值
  
  Parameters:
  
  source - the source structure - 源结构
  
  value - optional new value - 可选的新值
  
  Returns:
  
  new source with updated part, or original if value empty
- modify
  
  public S modify(S source, UnaryOperator<A> modifier)
  
  Modify the focused value if present 如果存在则修改聚焦值
  
  Parameters:
  
  source - the source structure - 源结构
  
  modifier - function to modify the value - 修改值的函数
  
  Returns:
  
  new source with modified part, or original if not present
- modifyOrSet
  
  public S modifyOrSet(S source, UnaryOperator<A> modifier, A defaultValue)
  
  Modify the focused value, or set default if not present 修改聚焦值，如果不存在则设置默认值
  
  Parameters:
  
  source - the source structure - 源结构
  
  modifier - function to modify the value - 修改值的函数
  
  defaultValue - default to set if not present - 不存在时设置的默认值
  
  Returns:
  
  new source
- andThen
  
  public <B> OptionalLens<S,B> andThen(OptionalLens<A,B> other)
  
  Compose with another optional lens 与另一个可选透镜组合
  
  Type Parameters:
  
  B - deeper target type - 更深的目标类型
  
  Parameters:
  
  other - lens to compose with - 要组合的透镜
  
  Returns:
  
  composed optional lens
- andThen
  
  public <B> OptionalLens<S,B> andThen(Lens<A,B> other)
  
  Compose with a regular lens 与常规透镜组合
  
  Type Parameters:
  
  B - deeper target type - 更深的目标类型
  
  Parameters:
  
  other - lens to compose with - 要组合的透镜
  
  Returns:
  
  composed optional lens
- compose
  
  public <T> OptionalLens<T,A> compose(OptionalLens<T,S> other)
  
  Compose with this lens (other first, then this) 与此透镜组合（先其他，然后此）
  
  Type Parameters:
  
  T - outer source type - 外部源类型
  
  Parameters:
  
  other - lens to compose with - 要组合的透镜
  
  Returns:
  
  composed optional lens
- compose
  
  public <T> OptionalLens<T,A> compose(Lens<T,S> other)
  
  Compose with a regular lens (other first, then this) 与常规透镜组合（先其他，然后此）
  
  Type Parameters:
  
  T - outer source type - 外部源类型
  
  Parameters:
  
  other - lens to compose with - 要组合的透镜
  
  Returns:
  
  composed optional lens
- getter
  
  public Function<S, Optional<A>> getter()
  
  Get the getter function 获取 getter 函数
  
  Returns:
  
  getter function
- setter
  
  public BiFunction<S,A,S> setter()
  
  Get the setter function 获取 setter 函数
  
  Returns:
  
  setter function
- toString
  
  public String toString()
  
  Overrides:
  
  toString in class Object

Class OptionalLens<S,A>

Method Summary

Methods inherited from class Object

Method Details

of

ofNullable

fromLens

get

getOrElse

isPresent

set

setIfPresent

modify

modifyOrSet

andThen

andThen

compose

compose

getter

setter

toString