Class ScopedValue.Carrier

java.lang.Object
java.lang.ScopedValue.Carrier
Enclosing class:
ScopedValuePREVIEW<T>
public static final classScopedValue.CarrierextendsObject
Carrier is a preview API of the Java platform.
Programs can only useCarrier when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A mapping of scoped values, askeys, to values.

ACarrier is used to accumulate mappings so that an operation (aRunnable orScopedValue.CallableOpPREVIEW) can be executed with all scoped values in the mapping bound to values. The following example runs an operation withk1 bound (or rebound) tov1, andk2 bound (or rebound) tov2.

    ScopedValue.where(k1, v1).where(k2, v2).run(() -> ... );

ACarrier is immutable and thread-safe. Thewhere method returns a newCarrier object, it does not mutate an existing mapping.

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

Since:
21

  • Method Details

    • where

      public <T> ScopedValue.CarrierPREVIEW where(ScopedValuePREVIEW<T> key, T value)
      Returns a newCarrier with the mappings from this carrier plus a new mapping fromkey tovalue. If this carrier already has a mapping for the scoped valuekey then it will map to the newvalue. The current carrier is immutable, so it is not changed by this method.
      Type Parameters:
      T - the type of the value
      Parameters:
      key - theScopedValue key
      value - the value, can benull
      Returns:
      a newCarrier with the mappings from this carrier plus the new mapping

    • get

      public <T> T get(ScopedValuePREVIEW<T> key)
      Returns the value of aScopedValuePREVIEW in this mapping.
      Type Parameters:
      T - the type of the value
      Parameters:
      key - theScopedValue key
      Returns:
      the value
      Throws:
      NoSuchElementException - if the key is not present in this mapping

    • call

      public <R, X extendsThrowable> R call(ScopedValue.CallableOpPREVIEW<? extends R, X> op) throwsX
      Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread. When the operation completes (normally or with an exception), each scoped value in the mapping will revert to being unbound, or revert to its previous value when previously bound, in the current thread. Ifop completes with an exception then it propagated by this method.

      Scoped values are intended to be used in astructured manner. If code invoked directly or indirectly by the operation creates aStructuredTaskScopePREVIEW but does notclosePREVIEW it, then it is detected as astructure violation when the operation completes (normally or with an exception). In that case, the underlying construct of theStructuredTaskScope is closed andStructureViolationExceptionPREVIEW is thrown.

      Type Parameters:
      R - the type of the result of the operation
      X - type of the exception thrown by the operation
      Parameters:
      op - the operation to run
      Returns:
      the result
      Throws:
      StructureViolationExceptionPREVIEW - if a structure violation is detected
      X - ifop completes with an exception
      Since:
      23

    • run

      public void run(Runnable op)
      Runs an operation with each scoped value in this mapping bound to its value in the current thread. When the operation completes (normally or with an exception), each scoped value in the mapping will revert to being unbound, or revert to its previous value when previously bound, in the current thread. Ifop completes with an exception then it propagated by this method.

      Scoped values are intended to be used in astructured manner. If code invoked directly or indirectly by the operation creates aStructuredTaskScopePREVIEW but does notclosePREVIEW it, then it is detected as astructure violation when the operation completes (normally or with an exception). In that case, the underlying construct of theStructuredTaskScope is closed andStructureViolationExceptionPREVIEW is thrown.

      Parameters:
      op - the operation to run
      Throws:
      StructureViolationExceptionPREVIEW - if a structure violation is detected