- Enclosing class:
ScopedValuePREVIEW<T>
Carrier
is a preview API of the Java platform.
A Carrier
is used to accumulate mappings so that an operation (a
Runnable
or Callable
) can be executed with all scoped values in the
mapping bound to values. The following example runs an operation with k1
bound (or rebound) to v1
, and k2
bound (or rebound) to v2
.
A Carrier
is immutable and thread-safe. The where
method returns a new Carrier
object,
it does not mutate an existing mapping.
Unless otherwise specified, passing a null
argument to a method in
this class will cause a NullPointerException
to be thrown.
- Since:
- 21
-
Method Summary
Modifier and TypeMethodDescription<R> R
Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread.<T> T
get
(ScopedValuePREVIEW<T> key) Returns the value of aScopedValue
PREVIEW in this mapping.<R> R
Invokes a supplier of results with each scoped value in this mapping bound to its value in the current thread.void
Runs an operation with each scoped value in this mapping bound to its value in the current thread.where
(ScopedValuePREVIEW<T> key, T value) Returns a newCarrier
with the mappings from this carrier plus a new mapping fromkey
tovalue
.
-
Method Details
-
where
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
keyvalue
- the value, can benull
- Returns:
- a new
Carrier
with the mappings from this carrier plus the new mapping
-
get
Returns the value of aScopedValue
PREVIEW 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
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 a structured manner. If code invoked directly or indirectly by the operation creates a
StructuredTaskScope
PREVIEW but does not closePREVIEW it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of theStructuredTaskScope
is closed andStructureViolationException
PREVIEW is thrown.- Type Parameters:
R
- the type of the result of the operation- Parameters:
op
- the operation to run- Returns:
- the result
- Throws:
StructureViolationExceptionPREVIEW
- if a structure violation is detectedException
- ifop
completes with an exception- See Also:
-
get
Invokes a supplier of results 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 a structured manner. If code invoked directly or indirectly by the operation creates a
StructuredTaskScope
PREVIEW but does not closePREVIEW it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of theStructuredTaskScope
is closed andStructureViolationException
PREVIEW is thrown.- Type Parameters:
R
- the type of the result of the operation- Parameters:
op
- the operation to run- Returns:
- the result
- Throws:
StructureViolationExceptionPREVIEW
- if a structure violation is detected- See Also:
-
run
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 a structured manner. If code invoked directly or indirectly by the operation creates a
StructuredTaskScope
PREVIEW but does not closePREVIEW it, then it is detected as a structure violation when the operation completes (normally or with an exception). In that case, the underlying construct of theStructuredTaskScope
is closed andStructureViolationException
PREVIEW is thrown.- Parameters:
op
- the operation to run- Throws:
StructureViolationExceptionPREVIEW
- if a structure violation is detected- See Also:
-
Carrier
when preview features are enabled.