Use scoped values to share request-scoped context across modern Java concurrency without the lifetime problems of ThreadLocal.
Scoped values let a caller bind read-only context for a bounded execution scope. Code inside that scope can read the value, but the binding ends when the scope ends.
That sounds simple, but it is a significant design improvement over long-lived ThreadLocal usage. As of JDK 25, scoped values are a permanent Java feature.
Many systems need contextual data that should follow a request through several layers:
Passing that data explicitly through every method is often best. But sometimes it creates plumbing noise that obscures the business logic. Older Java commonly solved that problem with ThreadLocal, which introduced a different risk: the data lived on the thread rather than on the logical operation.
Scoped values move the focus back to operation lifetime.
1import java.lang.ScopedValue;
2
3public class AuditContext {
4 private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
5
6 static void handleRequest(String requestId) {
7 ScopedValue.where(REQUEST_ID, requestId).run(() -> {
8 serviceLayer();
9 });
10 }
11
12 static void serviceLayer() {
13 logger.info("request={}", REQUEST_ID.get());
14 }
15}
The important design property is not just access. It is bounded lifetime. Once the scope exits, the binding is gone.
ThreadLocal| Concern | ThreadLocal | scoped values |
|---|---|---|
| lifetime | attached to the thread until cleared | attached to an explicit dynamic scope |
| mutability | usually mutable state by convention | designed for read-only contextual sharing |
| leakage risk | easy to forget cleanup in pooled threads | lower because the binding ends with the scope |
| fit with virtual threads | works, but can still blur ownership | better matches request-style lifetime |
This is why scoped values are especially relevant in the Loom era. Cheap threads are helpful, but clear lifetime is what makes concurrent code easier to reason about.
Scoped values fit best for metadata that is:
Good examples:
Do not use scoped values as an excuse to hide core business inputs.
Bad examples:
If a value is important to understanding what a method does, passing it explicitly is often still better.
Scoped values and structured concurrency complement each other:
That combination makes it easier to review request-scoped concurrency without relying on ambient mutable state.
Scoped values matter because they let Java share contextual data with explicit lifetime. They are not a replacement for normal parameters, but they are often a better replacement for ThreadLocal in modern concurrent Java systems.