In the Java programming language, data is usually passed to a method by means of a method parameter. The data may need to be passed through a sequence of many methods to get to the method that makes use of the data. Every method in the sequence of calls needs to declare the parameter and every method has access to the data. ScopedValue provides a means to pass data to a faraway method (typically a callback) without using method parameters. In effect, a ScopedValue is an implicit method parameter. It is "as if" every method in a sequence of calls has an additional parameter. None of the methods declare the parameter and only the methods that have access to the ScopedValue object can access its value (the data). ScopedValue makes it possible to securely pass data from a caller to a faraway callee through a sequence of intermediate methods that do not declare a parameter for the data and have no access to the data.

The ScopedValue API works by executing a method with a ScopedValue object bound to some value for the bounded period of execution of a method. The method may invoke another method, which in turn may invoke another. The unfolding execution of the methods define a dynamic scope. Code in these methods with access to the ScopedValue object may read its value. The ScopedValue object reverts to being unbound when the original method completes normally or with an exception. The ScopedValue API supports executing a Runnable, or CallableOp with a ScopedValue bound to a value.

Consider the following example with a scoped value "NAME" bound to the value "duke" for the execution of a Runnable's run method. The run method, in turn, invokes a method doSomething.

private static final ScopedValue<String> NAME = ScopedValue.newInstance();

ScopedValue.where(NAME, "duke").run(() -> doSomething());

The example using run invokes a method that does not return a result. The call method can be used to invoke a method that returns a result. ScopedValue defines the where(ScopedValue, Object) method for cases where multiple mappings (of ScopedValue to value) are accumulated in advance of calling a method with all ScopedValues bound to their value.

Bindings are per-thread

In the example, if code executed by one thread invokes this:

ScopedValue.where(NAME, "duke1").run(() -> doSomething());

ScopedValue.where(NAME, "duke2").run(() -> doSomething());

Scoped values as capabilities

Rebinding

In the above example, suppose that code executed by doSomething binds NAME to a new value with:

ScopedValue.where(NAME, "duchess").run(() -> doMore());

Inheritance

A ScopedValue that is shared across threads requires that the value be an immutable object or for all access to the value to be appropriately synchronized.

In the following example, the ScopedValue NAME is bound to the value "duke" for the execution of a runnable operation. The code in the run method creates a StructuredTaskScope that forks three tasks. Code executed directly or indirectly by these threads running childTask1(), childTask2(), and childTask3() that invokes NAME.get() will read the value "duke".

private static final ScopedValue<String> NAME = ScopedValue.newInstance();

ScopedValue.where(NAME, "duke").run(() -> {
    try (var scope = StructuredTaskScope.open()) {

         scope.fork(() -> childTask1());
         scope.fork(() -> childTask2());
         scope.fork(() -> childTask3());

         scope.join();

         ..
     }
});

Unless otherwise specified, passing a null argument to a method in this class will cause a NullPointerException to be thrown.