Purpose

The Context Propagation library contains the following abstractions:

  • ThreadLocalAccessor - contract to assist with access to a ThreadLocal value.

  • ContextAccessor - contract to assist with access to a Map-like context.

  • ContextRegistry - registry for instances of ThreadLocalAccessor and ContextAccessor.

  • ContextSnapshot - holder of contextual values that provides methods to capture and to propagate.

The Context Propagation library enables several usage scenarios, including:

  • In imperative code, such as Spring MVC controller, you can capture ThreadLocal values into a ContextSnapshot. After that, use the snapshot to populate a Reactor Context with the captured values or to wrap a task (such as Runnable, Callable, and others) or an Executor with a decorator that restores ThreadLocal values when the task runs.

  • In reactive code, such as Spring WebFlux controller, you can create a ContextSnapshot from Reactor Context values. After that, use the snapshot to restore ThreadLocal values within a specific stage (operator) of the reactive chain.

Context values can originate from any context mechanism and propagate to any other, any number of times. For example, a value in a Reactor context may originate as a ThreadLocal, become a ThreadLocal again, and so on.

Generally, imperative code should interact with ThreadLocal values as usual. Likewise, Reactor code should interact with the Reactor Context as usual. The Context Propagation library is not intended to replace those but to assist with propagation when crossing from one type of context to another, such as when imperative code invokes a Reactor chain, or when a Reactor chain invokes an imperative component that expects ThreadLocal values.

The library is not limited to context propagation from imperative to reactive. It can assist in asynchronous scenarios to propagate ThreadLocal values from one thread to another. It can also propagate to any other type of context for which there is a registered ContextAccesor instance.