java.lang.Object

cloud.opencode.base.parallel.structured.ScopedContext

public final class ScopedContext extends Object

Scoped Context - Scoped Values Context Management (JDK 25 JEP 501) 作用域上下文 - 作用域值上下文管理 (JDK 25 JEP 501)

Provides scoped values for context propagation in structured concurrency. ScopedValue is a modern replacement for ThreadLocal with better performance and automatic cleanup.

为结构化并发中的上下文传播提供作用域值。ScopedValue 是 ThreadLocal 的现代替代，具有更好的性能和自动清理。

Features | 特性:

Immutable values within scope - 作用域内值不可变
Automatic inheritance by child virtual threads - 子虚拟线程自动继承
No memory leaks - scope ends, value is released - 无内存泄漏 - 作用域结束，值释放

Example | 示例:

// Bind trace ID and execute
ScopedContext.runWithTraceId("trace-123", () -> {
    String traceId = ScopedContext.getTraceId();
    // All child threads inherit the trace ID
});

// Multiple bindings
ScopedContext.run("trace-123", "user-456", () -> {
    // Both trace ID and user ID available
});

Security | 安全性:

Thread-safe: Yes (ScopedValue is inherently thread-safe) - 线程安全: 是（ScopedValue天然线程安全）

Since:

JDK 25, opencode-base-parallel V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final ScopedValue<String>

REQUEST_ID

Request ID scoped value - 请求 ID 作用域值

static final ScopedValue<String>

TENANT_ID

Tenant ID scoped value - 租户 ID 作用域值

static final ScopedValue<String>

TRACE_ID

Trace ID scoped value - 追踪 ID 作用域值

static final ScopedValue<String>

USER_ID

User ID scoped value - 用户 ID 作用域值
Method Summary

Modifier and Type

Method

Description

static <T> T

call(String traceId, String userId, Callable<T> task)

Calls a task with trace ID and user ID bound.

static <T,R> R

callWith(ScopedValue<T> scopedValue, T value, Callable<R> task)

Calls a task with a custom scoped value bound.

static <T> T

callWithTraceId(String traceId, Callable<T> task)

Calls a task with trace ID bound.

static <T> T

callWithUserId(String userId, Callable<T> task)

Calls a task with user ID bound.

static <T> T

getOrNull(ScopedValue<T> scopedValue)

Gets a scoped value or null.

static String

getRequestId()

Gets the current request ID.

static String

getTenantId()

Gets the current tenant ID.

static String

getTraceId()

Gets the current trace ID.

static String

getTraceIdOrDefault(String defaultValue)

Gets the current trace ID or default.

static String

getUserId()

Gets the current user ID.

static <T> boolean

isBound(ScopedValue<T> scopedValue)

Checks if a scoped value is bound.

static <T> ScopedValue<T>

newScopedValue()

Creates a new scoped value.

static void

run(String traceId, String userId, Runnable task)

Runs a task with trace ID and user ID bound.

static void

run(String traceId, String userId, String tenantId, Runnable task)

Runs a task with trace ID, user ID, and tenant ID bound.

static <T> void

runWith(ScopedValue<T> scopedValue, T value, Runnable task)

Runs a task with a custom scoped value bound.

static void

runWithRequestId(String requestId, Runnable task)

Runs a task with request ID bound.

static void

runWithTenantId(String tenantId, Runnable task)

Runs a task with tenant ID bound.

static void

runWithTraceId(String traceId, Runnable task)

Runs a task with trace ID bound.

static void

runWithUserId(String userId, Runnable task)

Runs a task with user ID bound.

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

Field Details
- TRACE_ID
  
  public static final ScopedValue<String> TRACE_ID
  
  Trace ID scoped value - 追踪 ID 作用域值
- USER_ID
  
  public static final ScopedValue<String> USER_ID
  
  User ID scoped value - 用户 ID 作用域值
- TENANT_ID
  
  public static final ScopedValue<String> TENANT_ID
  
  Tenant ID scoped value - 租户 ID 作用域值
- REQUEST_ID
  
  public static final ScopedValue<String> REQUEST_ID
  
  Request ID scoped value - 请求 ID 作用域值
Method Details
- runWithTraceId
  
  public static void runWithTraceId(String traceId, Runnable task)
  
  Runs a task with trace ID bound. 使用绑定的追踪 ID 运行任务。
  
  Parameters:
  
  traceId - the trace ID - 追踪 ID
  
  task - the task - 任务
- callWithTraceId
  
  public static <T> T callWithTraceId(String traceId, Callable<T> task)
  
  Calls a task with trace ID bound. 使用绑定的追踪 ID 调用任务。
  
  Type Parameters:
  
  T - the result type - 结果类型
  
  Parameters:
  
  traceId - the trace ID - 追踪 ID
  
  task - the task - 任务
  
  Returns:
  
  the result - 结果
- getTraceId
  
  public static String getTraceId()
  
  Gets the current trace ID. 获取当前追踪 ID。
  
  Returns:
  
  the trace ID or null - 追踪 ID 或 null
- getTraceIdOrDefault
  
  public static String getTraceIdOrDefault(String defaultValue)
  
  Gets the current trace ID or default. 获取当前追踪 ID 或默认值。
  
  Parameters:
  
  defaultValue - the default value - 默认值
  
  Returns:
  
  the trace ID or default - 追踪 ID 或默认值
- runWithUserId
  
  public static void runWithUserId(String userId, Runnable task)
  
  Runs a task with user ID bound. 使用绑定的用户 ID 运行任务。
  
  Parameters:
  
  userId - the user ID - 用户 ID
  
  task - the task - 任务
- callWithUserId
  
  public static <T> T callWithUserId(String userId, Callable<T> task)
  
  Calls a task with user ID bound. 使用绑定的用户 ID 调用任务。
  
  Type Parameters:
  
  T - the result type - 结果类型
  
  Parameters:
  
  userId - the user ID - 用户 ID
  
  task - the task - 任务
  
  Returns:
  
  the result - 结果
- getUserId
  
  public static String getUserId()
  
  Gets the current user ID. 获取当前用户 ID。
  
  Returns:
  
  the user ID or null - 用户 ID 或 null
- runWithTenantId
  
  public static void runWithTenantId(String tenantId, Runnable task)
  
  Runs a task with tenant ID bound. 使用绑定的租户 ID 运行任务。
  
  Parameters:
  
  tenantId - the tenant ID - 租户 ID
  
  task - the task - 任务
- getTenantId
  
  public static String getTenantId()
  
  Gets the current tenant ID. 获取当前租户 ID。
  
  Returns:
  
  the tenant ID or null - 租户 ID 或 null
- runWithRequestId
  
  public static void runWithRequestId(String requestId, Runnable task)
  
  Runs a task with request ID bound. 使用绑定的请求 ID 运行任务。
  
  Parameters:
  
  requestId - the request ID - 请求 ID
  
  task - the task - 任务
- getRequestId
  
  public static String getRequestId()
  
  Gets the current request ID. 获取当前请求 ID。
  
  Returns:
  
  the request ID or null - 请求 ID 或 null
- run
  
  public static void run(String traceId, String userId, Runnable task)
  
  Runs a task with trace ID and user ID bound. 使用绑定的追踪 ID 和用户 ID 运行任务。
  
  Parameters:
  
  traceId - the trace ID - 追踪 ID
  
  userId - the user ID - 用户 ID
  
  task - the task - 任务
- call
  
  public static <T> T call(String traceId, String userId, Callable<T> task)
  
  Calls a task with trace ID and user ID bound. 使用绑定的追踪 ID 和用户 ID 调用任务。
  
  Type Parameters:
  
  T - the result type - 结果类型
  
  Parameters:
  
  traceId - the trace ID - 追踪 ID
  
  userId - the user ID - 用户 ID
  
  task - the task - 任务
  
  Returns:
  
  the result - 结果
- run
  
  public static void run(String traceId, String userId, String tenantId, Runnable task)
  
  Runs a task with trace ID, user ID, and tenant ID bound. 使用绑定的追踪 ID、用户 ID 和租户 ID 运行任务。
  
  Parameters:
  
  traceId - the trace ID - 追踪 ID
  
  userId - the user ID - 用户 ID
  
  tenantId - the tenant ID - 租户 ID
  
  task - the task - 任务
- newScopedValue
  
  public static <T> ScopedValue<T> newScopedValue()
  
  Creates a new scoped value. 创建新的作用域值。
  
  Type Parameters:
  
  T - the value type - 值类型
  
  Returns:
  
  the scoped value - 作用域值
- runWith
  
  public static <T> void runWith(ScopedValue<T> scopedValue, T value, Runnable task)
  
  Runs a task with a custom scoped value bound. 使用绑定的自定义作用域值运行任务。
  
  Type Parameters:
  
  T - the value type - 值类型
  
  Parameters:
  
  scopedValue - the scoped value - 作用域值
  
  value - the value to bind - 要绑定的值
  
  task - the task - 任务
- callWith
  
  public static <T,R> R callWith(ScopedValue<T> scopedValue, T value, Callable<R> task)
  
  Calls a task with a custom scoped value bound. 使用绑定的自定义作用域值调用任务。
  
  Type Parameters:
  
  T - the value type - 值类型
  
  R - the result type - 结果类型
  
  Parameters:
  
  scopedValue - the scoped value - 作用域值
  
  value - the value to bind - 要绑定的值
  
  task - the task - 任务
  
  Returns:
  
  the result - 结果
- isBound
  
  public static <T> boolean isBound(ScopedValue<T> scopedValue)
  
  Checks if a scoped value is bound. 检查作用域值是否已绑定。
  
  Type Parameters:
  
  T - the value type - 值类型
  
  Parameters:
  
  scopedValue - the scoped value - 作用域值
  
  Returns:
  
  true if bound - 如果已绑定返回 true
- getOrNull
  
  public static <T> T getOrNull(ScopedValue<T> scopedValue)
  
  Gets a scoped value or null. 获取作用域值或 null。
  
  Type Parameters:
  
  T - the value type - 值类型
  
  Parameters:
  
  scopedValue - the scoped value - 作用域值
  
  Returns:
  
  the value or null - 值或 null

Class ScopedContext

Field Summary

Method Summary

Methods inherited from class Object

Field Details

TRACE_ID

USER_ID

TENANT_ID

REQUEST_ID

Method Details

runWithTraceId

callWithTraceId

getTraceId

getTraceIdOrDefault

runWithUserId

callWithUserId

getUserId

runWithTenantId

getTenantId

runWithRequestId

getRequestId

run

call

run

newScopedValue

runWith

callWith

isBound

getOrNull