readme.md

Important

Main focus of the 'v2' version is simplification of this library. In the past, many features were added to the library. Some introduced more complexity than technically needed.
Due to semantic versioning we can't break functionality for the sake of simplicity. So for v2 we must redesign some api elements that allow simpler implementation, reducing complexity.

This is the development branch for the v2 version of this library. All breaking changes to the library must go in this branch.

• Java version bumped to Java8 minimum
• ContextManager.getActiveContext() replaced by getActiveContextValue().
• ContextManager.clear() will require an implementation.
• All @Deprecated(forRemoval=true) is to be removed.
• Add caveat about use vs. Scoped values and Structured Concurrency.

Context propagation library

Propagate a snapshot of one or more ThreadLocal values into another thread.

This library enables automatic propagation of several well-known ThreadLocal contexts by capturing a snapshot, reactivating it in another thread and ensuring proper cleanup after execution finishes:

• ContextAwareExecutorService wrapping any existing ExecutorService.
• ContextAwareCompletableFuture propagating context snapshots into each successive CompletionStage.

Terminology

Context

Abstraction containing a value in the context of a thread. The most common implementation in Java is a ThreadLocal value. The library provides an AbstractThreadLocalContext base class that features nesting values and predictable behaviour for out-of-order closing.

For each context type, there can only be one active context per thread at any time.

ContextManager

Manages a context. The ContextManager API can activate a new context value and provides access to the active context value.

ContextSnapshot

A snapshot contains the current value from all known context managers.
These values can be reactivated in another thread.
Reactivated snapshots must be closed to avoid leaking context.

All context aware utility classes in this library are tested to make sure they reactivate and close snapshots in a safe way.

How to use this library

Capturing a snapshot of ThreadLocal context values

Just before creating a new thread, capture a snapshot of all ThreadLocal context values:

ContextSnapshot snapshot = ContextSnapshot.capture();

In the code of your background thread, activate the snapshot to have all ThreadLocal context values set as they were captured:

try (ContextSnapshot.Reactivation reactivation = snapshot.reactivate()) {
    // All ThreadLocal values from the snapshot are available within this block
}

Threadpools and ExecutorService

If your background threads are managed by an ExecutorService, you can use our context aware ExecutorService instead of your usual threadpool.

When submitting new work, this automatically takes a context snapshot to reactivate in the background thread.
After the background thread finishes, the snapshot reactivation is closed, ensuring that no remaining ThreadLocal values leak into the thread pool.

The ContextAwareExecutorService can wrap any ExecutorService for the actual thread execution:

private static final ExecutorService THREADPOOL = 
        new ContextAwareExecutorService(Executors.newCachedThreadpool());

Supported contexts

The following ThreadLocal-based contexts are currently supported out of the box by this context-propagation library:

• SLF4J MDC (Mapped Diagnostic Context)
• Log4j 2 Thread Context
• OpenTelemetry Context
• OpenTracing Span contexts
• Spring Security Context
• Locale context
• ServletRequest contexts
• .. Yours? Feel free to create an issue or pull-request if you believe there's a general context that was forgotten.

Custom contexts

Adding your own Context type is possible by creating your own context manager.

Building jars with dependencies

When using a build tool or plugin to create an 'uber-jar', i.e. a jar file with all the classes of its dependencies included, you have to make sure that the service provider configuration files under META-INF/services are either preserved or merged. Otherwise Java's ServiceLoader will not be able to find the context implementations of this library.

In case you are using the Maven Shade Plugin, you can use the ServicesResourceTransformer for this task.

Performance metrics

No library is 'free' with regards to performance. Capturing a context snapshot and reactivating it in another thread is no different. For insight, the library tracks the overall time used creating and reactivating context snapshots along with time spent in each individual ContextManager.

Logging performance

On a development machine, you can get timing for each snapshot by turning on logging for nl.talsmasoftware.context.api.ContextTimer at FINEST or TRACE level (depending on your logger of choice). Please do not turn this on in production as the logging overhead will most likely have a noticeable impact on your application.

Metrics reporting

The context propagation metrics module uses the excellent dropwizard metrics library to instrument Timers for context propagation.

Similarly, the context propagation Micrometer module adds Micrometer instrumentation Timers for the context propagation.

Adding either of these modules to your classpath will automatically configure various timers in the global default metric registry of your application.

License

Apache 2.0 license