Scoped Values in Java

Scoped values were developed – together with Virtual Threads and Structured Concurrency – in Project Loom. They have been included in the JDK since Java 20 as an incubator feature (JEP 429) and since Java 21 as a preview feature (JEP 446).

In this article, you will learn:

• What is a scoped value?
• How to use ScopedValue?
• How are scoped values inherited?
• What is the difference between ScopedValue and ThreadLocal?

What is a Scoped Value?

Scoped values are a form of implicit method parameters that allow one or more values (i.e., arbitrary objects) to be passed to one or more remote methods without having to add them as explicit parameters to each method in the call chain.

Scoped values are usually created as public static fields, so they can be retrieved from any method.

If multiple threads use the same ScopedValue field, then it may contain a different value from the point of view of each thread.

If you are familiar with ThreadLocal variables, this will sound familiar. In fact, scoped values are a modern alternative for thread locals.

I can best explain scoped values with an example.

ScopedValue Example

A classic usage scenario is a web framework that authenticates the user on an incoming request and makes the logged-in user's data available to the code that processes the request.

That can be done, for example, using a method argument.

Now, in complex applications, the processing of a request can extend over hundreds of methods – but the information about the logged-in user may only be required in a few methods. Nevertheless, we would have to pass the user through all methods that eventually lead to invoking a method for which the logged-in user is relevant.

In the following example, the logged-in user is passed from the Server through the RestAdapter and UseCase to the Repository, where it is eventually evaluated:

class Server {
  private void serve(Request request) {
    // ...
    User user = authenticateUser(request);
    restAdapter.processRequest(request, user);
    // ...
  }
}

class RestAdapter {
  public void processRequest(Request request, User loggedInUser) { 
    // ...
    UUID id = extractId(request);
    useCase.invoke(id, loggedInUser);
    // ...
  }
}

class UseCase {
  public void invoke(UUID id, User loggedInUser) {
    // ...
    Data data = repository.getData(id, loggedInUser);
    // ...
  }
}

class Repository {
  public Data getData(UUID id, User loggedInUser) {
    Data data = findById(id);
    if (loggedInUser.isAdmin()) {
      enrichDataWithAdminInfos(data);
    }
  }
}Code language: Java (java)

The additional loggedInUser parameter makes our code noisy quite quickly. Most of the methods do not need the user at all – and there might even be methods that should not be able to access the user at all for security reasons.

And what if, at some point deep in the call stack, we also needed the user's IP address? Then we would have to pass another argument through countless methods.

The alternative is to store the user in a scoped value that can be accessed from anywhere.

This works as follows: We create a static field of type ScopedValue in a publicly accessible place. With ScopedValue.where(…), we bind the scoped value to the concrete user object; and to the run(…) method, we supply – in the form of a Runnable – the code for whose call duration the scoped value should be valid:

class Server {
  public final static ScopedValue<User> LOGGED_IN_USER = ScopedValue.newInstance();
 
  private void serve(Request request) {
    // ...
    User loggedInUser = authenticateUser(request);
    ScopedValue.where(LOGGED_IN_USER, loggedInUser)
               .run(() -> restAdapter.processRequest(request));
    // ...
  }
}Code language: Java (java)

Alternatively, the Runnable can be passed directly to the runWhere(…) method as the third parameter:

ScopedValue.runWhere(LOGGED_IN_USER, loggedInUser,
                     () -> restAdapter.processRequest(request));Code language: Java (java)

Instead of a Runnable, you can also pass a Callable or a Supplier (i.e., a method with a return value) – for this, you invoke call(…) or get(…) instead of run(…) or pass the Callable or Supplier as the third parameter to the callWhere(…) or getWhere(…) method. You can find an example further below.

We can then remove the loggedInUser parameter from all method signatures:

class RestAdapter {
  public void processRequest(Request request) { 
    // ...
    UUID id = extractId(request);
    useCase.invoke(id);
    // ...
  }
}

class UseCase {
  public void invoke(UUID id) {
    // ...
    Data data = repository.getData(id);
    // ...
  }
}Code language: Java (java)

And where we need the logged-in user, we can read it with ScopedValue.get():

class Repository {
  public Data getData(UUID id) {
    Data data = findById(id);
    User loggedInUser = Server.LOGGED_IN_USER.get();
    if (loggedInUser.isAdmin()) {
      enrichDataWithAdminInfos(data);
    }
  }
}Code language: Java (java)

That makes the code much more readable and maintainable, as we no longer have to pass the logged-in user from one method to the next but can access it exactly where we need it.

If you want to experiment with scoped values: Preview features have to be explicitly enabled. To do this, you need to download Java 21 and run the java and javac commands with the following parameters:

$ javac --enable-preview --source 21 *.java
$ java --enable-preview <class to execute>Code language: plaintext (plaintext)

Rebinding Scoped Values

ScopedValue has no set(…) method to change the stored value. This is intentional because the immutability of a value makes complex code much more readable and maintainable.

Instead, you can rebind the value for the invocation of a limited code section (e.g., for the invocation of a sub-method). That means that, for this limited code section, another value is visible … and as soon as that section is terminated, the original value is visible again.

For example, our RestAdapter method might want to hide the information about the logged-in user from the extractId method. To do this, we can call ScopedValue.where(…) again and set the logged-in user to null during the sub-method call:

class RestAdapter {
  public void processRequest(Request request) { 
    // ...
    UUID id = ScopedValue.where(LOGGED_IN_USER, null)
                         .call(() -> extractId(request));
    useCase.invoke(id);
    // ...
  }
}Code language: Java (java)

Here you can also see how we use call(…) instead of run(…) and pass a Callable (i.e., a method with a return value) instead of a Runnable.

Inheriting Scoped Values

Scoped values are automatically inherited by all child threads created via a Structured Task Scope.

Using StructuredTaskScope, our use case could, for example, call an external service in parallel to the repository method:

class UseCase {
  public void invoke(UUID id) {
    // ...
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
      Future<Data>    dataFuture    = scope.fork(() -> repository.getData(id));
      Future<ExtData> extDataFuture = scope.fork(() -> remoteService.getExtData(id));
 
      scope.join();
      scope.throwIfFailed();

      Data    data    = dataFuture.resultNow();
      ExtData extData = extDataFuture.resultNow();
      // ...
    }
  }
}Code language: Java (java)

This way, we can also access the logged-in user from the child threads created via fork(…) using LOGGED_IN_USER.get().

Since the StructuredTaskScope is not completed until all child threads are finished, it fits very well into the concept of scoped values.

Summary

With scoped values, we get a handy construct to provide a thread (and, if needed, a group of child threads) with a read-only, thread-specific value during their lifetime.

Please note that as of Java 20, scoped values are still in the incubator stage and, thus, may still be subject to fundamental changes.

If you still have questions, please ask them via the comment function. Do you want to be informed about new tutorials and articles? Then click here to sign up for the HappyCoders.eu newsletter.