Overview

Scoped Values are a modern alternative to Thread-Local variables introduced in Java 20 (as a preview feature) and further refined in later versions. They provide a safer and more efficient way to share immutable data within and across threads.

Key Differences from Thread-Local

Basic Usage

1. Creating and Using Scoped Values

import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;
public class ScopedValuesBasic {
// 1. Define a ScopedValue
private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
private static final ScopedValue<Locale> USER_LOCALE = ScopedValue.newInstance();
private static final ScopedValue<RequestContext> REQUEST_CONTEXT = ScopedValue.newInstance();
public static void main(String[] args) {
// 2. Bind values and run code within that scope
User user = new User("john_doe", "John Doe", "en-US");
RequestContext context = new RequestContext("req-123", System.currentTimeMillis());
ScopedValue.where(CURRENT_USER, user)
.where(REQUEST_CONTEXT, context)
.run(() -> processRequest());
// Outside the scope, ScopedValue is unbound
System.out.println("Outside scope: " + 
(CURRENT_USER.isBound() ? "Bound" : "Unbound")); // Unbound
}
private static void processRequest() {
// 3. Access the bound value within the scope
User user = CURRENT_USER.get();
RequestContext context = REQUEST_CONTEXT.get();
System.out.println("Processing request for: " + user.username());
System.out.println("Request ID: " + context.requestId());
// Call methods that also need the context
performBusinessOperation();
}
private static void performBusinessOperation() {
// Scoped values are automatically available in called methods
User user = CURRENT_USER.get();
System.out.println("Business operation for: " + user.username());
}
// Record definitions
record User(String username, String fullName, String locale) {}
record RequestContext(String requestId, long timestamp) {}
}

2. Nested Scopes and Rebinding

public class ScopedValuesNested {
private static final ScopedValue<String> CURRENT_TENANT = ScopedValue.newInstance();
private static final ScopedValue<Integer> DEPTH = ScopedValue.newInstance();
public static void main(String[] args) {
// Outer scope
ScopedValue.where(CURRENT_TENANT, "acme-corp")
.where(DEPTH, 1)
.run(() -> {
System.out.println("Outer - Tenant: " + CURRENT_TENANT.get());
System.out.println("Outer - Depth: " + DEPTH.get());
// Nested scope - can rebind values
ScopedValue.where(CURRENT_TENANT, "another-tenant")
.where(DEPTH, 2)
.run(() -> {
System.out.println("Inner - Tenant: " + CURRENT_TENANT.get());
System.out.println("Inner - Depth: " + DEPTH.get());
});
// Back to outer scope values
System.out.println("Back to Outer - Tenant: " + CURRENT_TENANT.get());
System.out.println("Back to Outer - Depth: " + DEPTH.get());
});
}
}

Practical Examples

Example 1: Web Request Context Management

public class WebRequestScopedValues {
// Scoped values for request context
private static final ScopedValue<RequestContext> REQUEST = ScopedValue.newInstance();
private static final ScopedValue<UserPrincipal> USER = ScopedValue.newInstance();
private static final ScopedValue<Locale> LOCALE = ScopedValue.newInstance();
private static final ScopedValue<Map<String, String>> TRACING_HEADERS = ScopedValue.newInstance();
public static class RequestContext {
private final String requestId;
private final String sessionId;
private final String userAgent;
private final Instant startTime;
public RequestContext(String requestId, String sessionId, String userAgent) {
this.requestId = requestId;
this.sessionId = sessionId;
this.userAgent = userAgent;
this.startTime = Instant.now();
}
// Getters
public String getRequestId() { return requestId; }
public String getSessionId() { return sessionId; }
public String getUserAgent() { return userAgent; }
public Instant getStartTime() { return startTime; }
}
public static class UserPrincipal {
private final String userId;
private final String username;
private final Set<String> roles;
public UserPrincipal(String userId, String username, Set<String> roles) {
this.userId = userId;
this.username = username;
this.roles = Set.copyOf(roles);
}
// Getters
public String getUserId() { return userId; }
public String getUsername() { return username; }
public Set<String> getRoles() { return roles; }
public boolean hasRole(String role) {
return roles.contains(role);
}
}
// Simulated HTTP request handler
public static void handleHttpRequest(HttpServletRequest request, HttpServletResponse response) {
// Extract context from request
RequestContext context = extractRequestContext(request);
UserPrincipal user = authenticateUser(request);
Locale locale = extractLocale(request);
Map<String, String> tracingHeaders = extractTracingHeaders(request);
// Bind scoped values and process request
ScopedValue.where(REQUEST, context)
.where(USER, user)
.where(LOCALE, locale)
.where(TRACING_HEADERS, tracingHeaders)
.run(() -> processRequest(request, response));
}
private static void processRequest(HttpServletRequest request, HttpServletResponse response) {
try {
// Access scoped values anywhere in the call stack
RequestContext context = REQUEST.get();
UserPrincipal user = USER.get();
logRequestStart(context, user);
// Route to appropriate handler
String path = request.getPathInfo();
if (path.startsWith("/api/users")) {
handleUserApi(request, response);
} else if (path.startsWith("/api/products")) {
handleProductApi(request, response);
} else {
handleDefault(request, response);
}
logRequestEnd(context);
} catch (Exception e) {
handleError(e, response);
}
}
private static void handleUserApi(HttpServletRequest request, HttpServletResponse response) {
UserPrincipal currentUser = USER.get();
RequestContext context = REQUEST.get();
// Check permissions
if (!currentUser.hasRole("USER_READ")) {
throw new SecurityException("Insufficient permissions");
}
// Business logic that needs user context
UserService userService = new UserService();
userService.getUserProfile(currentUser.getUserId());
response.setStatus(200);
}
private static void handleProductApi(HttpServletRequest request, HttpServletResponse response) {
// Access tracing headers for distributed tracing
Map<String, String> tracing = TRACING_HEADERS.get();
String traceId = tracing.get("trace-id");
// Log with trace context
System.out.println("Processing product API with trace: " + traceId);
ProductService productService = new ProductService();
productService.listProducts();
response.setStatus(200);
}
// Utility methods
private static RequestContext extractRequestContext(HttpServletRequest request) {
return new RequestContext(
generateRequestId(),
request.getSession().getId(),
request.getHeader("User-Agent")
);
}
private static UserPrincipal authenticateUser(HttpServletRequest request) {
// Simulated authentication
String authHeader = request.getHeader("Authorization");
// ... authentication logic
return new UserPrincipal("user-123", "john_doe", Set.of("USER_READ", "PRODUCT_READ"));
}
private static Locale extractLocale(HttpServletRequest request) {
String langHeader = request.getHeader("Accept-Language");
return langHeader != null ? Locale.forLanguageTag(langHeader) : Locale.getDefault();
}
private static Map<String, String> extractTracingHeaders(HttpServletRequest request) {
Map<String, String> tracing = new HashMap<>();
tracing.put("trace-id", request.getHeader("X-Trace-Id"));
tracing.put("span-id", request.getHeader("X-Span-Id"));
return Map.copyOf(tracing);
}
private static void logRequestStart(RequestContext context, UserPrincipal user) {
System.out.printf("[%s] Request started for user %s%n", 
context.getRequestId(), user.getUsername());
}
private static void logRequestEnd(RequestContext context) {
Duration duration = Duration.between(context.getStartTime(), Instant.now());
System.out.printf("[%s] Request completed in %d ms%n", 
context.getRequestId(), duration.toMillis());
}
private static void handleError(Exception e, HttpServletResponse response) {
response.setStatus(500);
// Log error with request context
RequestContext context = REQUEST.get();
System.err.printf("[%s] Request failed: %s%n", context.getRequestId(), e.getMessage());
}
private static String generateRequestId() {
return "req-" + System.currentTimeMillis() + "-" + Math.abs(new Random().nextInt());
}
// Service classes that use scoped values
public static class UserService {
public UserProfile getUserProfile(String userId) {
// Access scoped values in service layer
UserPrincipal currentUser = USER.get();
RequestContext context = REQUEST.get();
// Authorization check
if (!currentUser.getUserId().equals(userId) && !currentUser.hasRole("ADMIN")) {
throw new SecurityException("Cannot access other user's profile");
}
// Business logic with context
System.out.printf("[%s] Fetching profile for user %s%n", 
context.getRequestId(), userId);
return new UserProfile(userId, currentUser.getUsername());
}
}
public static class ProductService {
public List<Product> listProducts() {
Locale locale = LOCALE.get();
Map<String, String> tracing = TRACING_HEADERS.get();
// Use locale for internationalization
System.out.println("Listing products for locale: " + locale);
System.out.println("Trace ID: " + tracing.get("trace-id"));
return List.of(new Product("prod-1", "Product 1"), new Product("prod-2", "Product 2"));
}
}
record UserProfile(String userId, String username) {}
record Product(String id, String name) {}
}

Example 2: Structured Concurrency with Scoped Values

public class StructuredConcurrencyScopedValues {
private static final ScopedValue<Project> CURRENT_PROJECT = ScopedValue.newInstance();
private static final ScopedValue<String> CORRELATION_ID = ScopedValue.newInstance();
public static class Project {
private final String id;
private final String name;
private final Set<String> permissions;
public Project(String id, String name, Set<String> permissions) {
this.id = id;
this.name = name;
this.permissions = Set.copyOf(permissions);
}
// Getters
public String getId() { return id; }
public String getName() { return name; }
public Set<String> getPermissions() { return permissions; }
}
public static class ProjectService {
public ProjectSummary getProjectSummary(String projectId) throws Exception {
Project project = loadProject(projectId);
String correlationId = generateCorrelationId();
return ScopedValue.where(CURRENT_PROJECT, project)
.where(CORRELATION_ID, correlationId)
.call(() -> fetchProjectSummary());
}
private ProjectSummary fetchProjectSummary() throws Exception {
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
// Launch concurrent subtasks - they inherit scoped values automatically
Subtask<List<TeamMember>> membersTask = scope.fork(this::fetchTeamMembers);
Subtask<ProjectStatistics> statsTask = scope.fork(this::fetchProjectStatistics);
Subtask<List<ProjectTask>> tasksTask = scope.fork(this::fetchRecentTasks);
// Wait for all subtasks to complete
scope.join();
scope.throwIfFailed();
// Combine results
return new ProjectSummary(
CURRENT_PROJECT.get(),
membersTask.get(),
statsTask.get(),
tasksTask.get()
);
}
}
private List<TeamMember> fetchTeamMembers() {
Project project = CURRENT_PROJECT.get();
String correlationId = CORRELATION_ID.get();
System.out.printf("[%s] Fetching team members for project %s%n", 
correlationId, project.getId());
// Simulate API call
try { Thread.sleep(100); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
return List.of(
new TeamMember("user1", "Alice", "Developer"),
new TeamMember("user2", "Bob", "Designer")
);
}
private ProjectStatistics fetchProjectStatistics() {
Project project = CURRENT_PROJECT.get();
String correlationId = CORRELATION_ID.get();
System.out.printf("[%s] Fetching statistics for project %s%n", 
correlationId, project.getId());
// Simulate database query
try { Thread.sleep(150); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
return new ProjectStatistics(85, 42, 1500000);
}
private List<ProjectTask> fetchRecentTasks() {
Project project = CURRENT_PROJECT.get();
String correlationId = CORRELATION_ID.get();
System.out.printf("[%s] Fetching recent tasks for project %s%n", 
correlationId, project.getId());
// Simulate external service call
try { Thread.sleep(200); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
return List.of(
new ProjectTask("task1", "Implement feature", "IN_PROGRESS"),
new ProjectTask("task2", "Write tests", "TODO")
);
}
private Project loadProject(String projectId) {
// Simulate project loading
return new Project(projectId, "Sample Project", Set.of("READ", "WRITE"));
}
private String generateCorrelationId() {
return "corr-" + System.currentTimeMillis();
}
}
// Record definitions
record ProjectSummary(Project project, List<TeamMember> teamMembers, 
ProjectStatistics statistics, List<ProjectTask> recentTasks) {}
record TeamMember(String id, String name, String role) {}
record ProjectStatistics(int completionPercentage, int openIssues, long budget) {}
record ProjectTask(String id, String description, String status) {}
public static void main(String[] args) throws Exception {
ProjectService service = new ProjectService();
ProjectSummary summary = service.getProjectSummary("proj-123");
System.out.println("Project: " + summary.project().getName());
System.out.println("Team members: " + summary.teamMembers().size());
System.out.println("Completion: " + summary.statistics().completionPercentage() + "%");
}
}

Example 3: Database Transaction Management

public class TransactionScopedValues {
private static final ScopedValue<Connection> DB_CONNECTION = ScopedValue.newInstance();
private static final ScopedValue<TransactionContext> TX_CONTEXT = ScopedValue.newInstance();
private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
public static class TransactionContext {
private final String transactionId;
private final IsolationLevel isolationLevel;
private final boolean readOnly;
private final Instant startTime;
public TransactionContext(String transactionId, IsolationLevel isolationLevel, boolean readOnly) {
this.transactionId = transactionId;
this.isolationLevel = isolationLevel;
this.readOnly = readOnly;
this.startTime = Instant.now();
}
// Getters
public String getTransactionId() { return transactionId; }
public IsolationLevel getIsolationLevel() { return isolationLevel; }
public boolean isReadOnly() { return readOnly; }
public Instant getStartTime() { return startTime; }
}
public enum IsolationLevel {
READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE
}
public static class TransactionalService {
public <T> T executeInTransaction(TransactionCallback<T> callback) {
return executeInTransaction(IsolationLevel.READ_COMMITTED, false, callback);
}
public <T> T executeInTransaction(IsolationLevel isolationLevel, 
boolean readOnly,
TransactionCallback<T> callback) {
String txId = generateTransactionId();
TransactionContext txContext = new TransactionContext(txId, isolationLevel, readOnly);
try (Connection connection = DataSource.getConnection()) {
// Set up transaction
connection.setAutoCommit(false);
connection.setTransactionIsolation(isolationLevel.ordinal() + 1);
return ScopedValue.where(DB_CONNECTION, connection)
.where(TX_CONTEXT, txContext)
.where(CURRENT_USER, getCurrentUser())
.call(() -> {
try {
T result = callback.doInTransaction();
connection.commit();
logTransactionSuccess(txContext);
return result;
} catch (Exception e) {
connection.rollback();
logTransactionFailure(txContext, e);
throw new TransactionException("Transaction failed", e);
}
});
} catch (SQLException e) {
throw new TransactionException("Failed to manage transaction", e);
}
}
public void updateUserProfile(String userId, UserProfile updates) {
executeInTransaction(() -> {
// All database operations in this scope use the same connection
UserDAO userDao = new UserDAO();
AuditDAO auditDao = new AuditDAO();
User user = userDao.findById(userId);
if (user == null) {
throw new IllegalArgumentException("User not found: " + userId);
}
// Update user
userDao.update(userId, updates);
// Audit the change
auditDao.logUserUpdate(userId, updates, CURRENT_USER.get());
return null;
});
}
public Order processOrder(OrderRequest request) {
return executeInTransaction(IsolationLevel.REPEATABLE_READ, false, () -> {
OrderDAO orderDao = new OrderDAO();
InventoryDAO inventoryDao = new InventoryDAO();
PaymentDAO paymentDao = new PaymentDAO();
// Check inventory
if (!inventoryDao.hasSufficientStock(request.productId(), request.quantity())) {
throw new InsufficientStockException("Not enough stock");
}
// Process payment
PaymentResult payment = paymentDao.processPayment(
request.paymentMethod(), request.amount());
if (!payment.isSuccess()) {
throw new PaymentException("Payment failed: " + payment.getErrorMessage());
}
// Create order
Order order = orderDao.createOrder(request, CURRENT_USER.get());
// Update inventory
inventoryDao.reduceStock(request.productId(), request.quantity());
// Log audit trail
auditOrderCreation(order);
return order;
});
}
private void auditOrderCreation(Order order) {
TransactionContext txContext = TX_CONTEXT.get();
User currentUser = CURRENT_USER.get();
AuditDAO auditDao = new AuditDAO();
auditDao.logOrderCreation(order, currentUser, txContext.getTransactionId());
}
private String generateTransactionId() {
return "tx-" + System.currentTimeMillis() + "-" + Math.abs(new Random().nextInt(1000));
}
private User getCurrentUser() {
// In real application, get from security context
return new User("current-user", "System User");
}
private void logTransactionSuccess(TransactionContext context) {
Duration duration = Duration.between(context.getStartTime(), Instant.now());
System.out.printf("[%s] Transaction completed successfully in %d ms%n",
context.getTransactionId(), duration.toMillis());
}
private void logTransactionFailure(TransactionContext context, Exception e) {
System.err.printf("[%s] Transaction failed: %s%n",
context.getTransactionId(), e.getMessage());
}
}
// DAO classes that use scoped connection
public static class UserDAO {
public User findById(String userId) {
Connection connection = DB_CONNECTION.get();
TransactionContext txContext = TX_CONTEXT.get();
try (PreparedStatement stmt = connection.prepareStatement(
"SELECT * FROM users WHERE id = ?")) {
stmt.setString(1, userId);
ResultSet rs = stmt.executeQuery();
if (rs.next()) {
return new User(rs.getString("id"), rs.getString("name"));
}
return null;
} catch (SQLException e) {
throw new DataAccessException("Failed to find user", e);
}
}
public void update(String userId, UserProfile updates) {
Connection connection = DB_CONNECTION.get();
try (PreparedStatement stmt = connection.prepareStatement(
"UPDATE users SET name = ?, email = ? WHERE id = ?")) {
stmt.setString(1, updates.name());
stmt.setString(2, updates.email());
stmt.setString(3, userId);
stmt.executeUpdate();
} catch (SQLException e) {
throw new DataAccessException("Failed to update user", e);
}
}
}
public static class AuditDAO {
public void logUserUpdate(String userId, UserProfile updates, User currentUser) {
Connection connection = DB_CONNECTION.get();
TransactionContext txContext = TX_CONTEXT.get();
try (PreparedStatement stmt = connection.prepareStatement(
"INSERT INTO audit_log (action, user_id, target_user, transaction_id) VALUES (?, ?, ?, ?)")) {
stmt.setString(1, "USER_UPDATE");
stmt.setString(2, currentUser.id());
stmt.setString(3, userId);
stmt.setString(4, txContext.getTransactionId());
stmt.executeUpdate();
} catch (SQLException e) {
throw new DataAccessException("Failed to log audit", e);
}
}
public void logOrderCreation(Order order, User currentUser, String transactionId) {
// Similar implementation...
}
}
// Other DAO classes (simplified)
public static class OrderDAO {
public Order createOrder(OrderRequest request, User user) {
// Implementation...
return new Order("order-123", request.productId(), request.quantity());
}
}
public static class InventoryDAO {
public boolean hasSufficientStock(String productId, int quantity) {
// Implementation...
return true;
}
public void reduceStock(String productId, int quantity) {
// Implementation...
}
}
public static class PaymentDAO {
public PaymentResult processPayment(String paymentMethod, double amount) {
// Implementation...
return new PaymentResult(true, null);
}
}
// Functional interface for transaction callbacks
@FunctionalInterface
public interface TransactionCallback<T> {
T doInTransaction();
}
// Record definitions
record User(String id, String name) {}
record UserProfile(String name, String email) {}
record OrderRequest(String productId, int quantity, String paymentMethod, double amount) {}
record Order(String id, String productId, int quantity) {}
record PaymentResult(boolean success, String errorMessage) {}
// Exception classes
public static class TransactionException extends RuntimeException {
public TransactionException(String message) { super(message); }
public TransactionException(String message, Throwable cause) { super(message, cause); }
}
public static class DataAccessException extends RuntimeException {
public DataAccessException(String message, Throwable cause) { super(message, cause); }
}
public static class InsufficientStockException extends RuntimeException {
public InsufficientStockException(String message) { super(message); }
}
public static class PaymentException extends RuntimeException {
public PaymentException(String message) { super(message); }
}
// Mock DataSource
public static class DataSource {
public static Connection getConnection() throws SQLException {
// In real application, return from connection pool
return null; // Simplified
}
}
}

Advanced Patterns

1. Scoped Value with Fallback

public class ScopedValueWithFallback {
private static final ScopedValue<Configuration> CONFIG = ScopedValue.newInstance();
private static final Configuration DEFAULT_CONFIG = new Configuration("default", "info");
public static Configuration getCurrentConfig() {
return CONFIG.orElse(DEFAULT_CONFIG);
}
public static void withConfig(Configuration config, Runnable task) {
ScopedValue.where(CONFIG, config).run(task);
}
public static <T> T withConfig(Configuration config, Supplier<T> task) {
return ScopedValue.where(CONFIG, config).call(task);
}
// Usage
public static void main(String[] args) {
// Use default config
System.out.println("Default config: " + getCurrentConfig());
// Use scoped config
Configuration customConfig = new Configuration("custom", "debug");
withConfig(customConfig, () -> {
System.out.println("Scoped config: " + getCurrentConfig());
// Nested with different config
withConfig(new Configuration("nested", "trace"), () -> {
System.out.println("Nested config: " + getCurrentConfig());
});
// Back to outer scoped config
System.out.println("Back to scoped config: " + getCurrentConfig());
});
// Back to default
System.out.println("Back to default: " + getCurrentConfig());
}
record Configuration(String name, String logLevel) {}
}

2. Scoped Value Validation

public class ScopedValueValidation {
private static final ScopedValue<UserSession> SESSION = ScopedValue.newInstance();
public static void requireAuthenticated() {
if (!SESSION.isBound()) {
throw new IllegalStateException("No user session bound");
}
UserSession session = SESSION.get();
if (!session.isValid()) {
throw new SecurityException("User session is invalid");
}
}
public static void requirePermission(String permission) {
requireAuthenticated();
UserSession session = SESSION.get();
if (!session.hasPermission(permission)) {
throw new SecurityException("Insufficient permissions: " + permission);
}
}
public static void withSession(UserSession session, Runnable task) {
if (!session.isValid()) {
throw new IllegalArgumentException("Invalid session");
}
ScopedValue.where(SESSION, session).run(task);
}
public static class UserSession {
private final String userId;
private final Set<String> permissions;
private final Instant expiry;
public UserSession(String userId, Set<String> permissions, Duration duration) {
this.userId = userId;
this.permissions = Set.copyOf(permissions);
this.expiry = Instant.now().plus(duration);
}
public boolean isValid() {
return Instant.now().isBefore(expiry);
}
public boolean hasPermission(String permission) {
return permissions.contains(permission);
}
// Getters
public String getUserId() { return userId; }
public Set<String> getPermissions() { return permissions; }
public Instant getExpiry() { return expiry; }
}
}

Migration from Thread-Local

1. Thread-Local to Scoped Value Migration

public class ThreadLocalMigration {
// OLD: Thread-Local approach
private static final ThreadLocal<UserContext> THREAD_LOCAL_CONTEXT = new ThreadLocal<>();
public static void oldApproach() {
// Setting value
THREAD_LOCAL_CONTEXT.set(new UserContext("user1"));
try {
// Using value
UserContext context = THREAD_LOCAL_CONTEXT.get();
processRequest(context);
} finally {
// Must remember to clean up!
THREAD_LOCAL_CONTEXT.remove();
}
}
// NEW: Scoped Value approach
private static final ScopedValue<UserContext> SCOPED_CONTEXT = ScopedValue.newInstance();
public static void newApproach() {
// Setting value with automatic cleanup
ScopedValue.where(SCOPED_CONTEXT, new UserContext("user1"))
.run(() -> {
// Using value
UserContext context = SCOPED_CONTEXT.get();
processRequest(context);
});
// Automatically cleaned up!
}
// Migrating InheritableThreadLocal
private static final InheritableThreadLocal<UserContext> INHERITABLE_CONTEXT = 
new InheritableThreadLocal<>();
private static final ScopedValue<UserContext> SCOPED_INHERITABLE_CONTEXT = 
ScopedValue.newInstance();
public static void migratInheritable() {
// OLD: Manual inheritance
INHERITABLE_CONTEXT.set(new UserContext("parent"));
Thread childThread = new Thread(() -> {
UserContext inherited = INHERITABLE_CONTEXT.get();
// Use inherited context
});
childThread.start();
// NEW: Automatic inheritance with StructuredTaskScope
ScopedValue.where(SCOPED_INHERITABLE_CONTEXT, new UserContext("parent"))
.run(() -> {
try (var scope = new StructuredTaskScope<String>()) {
scope.fork(() -> {
// Automatically inherits scoped values
UserContext inherited = SCOPED_INHERITABLE_CONTEXT.get();
return "done";
});
scope.join();
}
});
}
record UserContext(String userId) {}
private static void processRequest(UserContext context) {
// Processing logic
}
}

Best Practices

1. Use for Immutable Data: Scoped values work best with immutable objects
2. Keep Scope Small: Bind values for the minimal necessary scope
3. Prefer over ThreadLocal: Use scoped values for new code
4. Combine with Structured Concurrency: Perfect companion for structured task scopes
5. Validate Usage: Check if values are bound when required
6. Document Dependencies: Clearly document which scoped values your methods expect

Performance Benefits

• Faster access than ThreadLocal
• No memory leaks due to automatic cleanup
• Better optimizations by the JVM
• Automatic inheritance in structured concurrency

Scoped Values provide a modern, safe, and efficient alternative to Thread-Local variables, especially when combined with Java's structured concurrency features.