Relocation (core, java-5)

Standardized context propagation in concurrent systems.

License

License

GroupId

GroupId

nl.talsmasoftware
ArtifactId

ArtifactId

context-propagation
Last Version

Last Version

1.0.9
Release Date

Release Date

Type

Type

pom
Description

Description

Relocation (core, java-5)
Standardized context propagation in concurrent systems.
Project Organization

Project Organization

Talsma ICT

Download context-propagation

How to add to project

<!-- https://jarcasting.com/artifacts/nl.talsmasoftware/context-propagation/ -->
<dependency>
    <groupId>nl.talsmasoftware</groupId>
    <artifactId>context-propagation</artifactId>
    <version>1.0.9</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/nl.talsmasoftware/context-propagation/
implementation 'nl.talsmasoftware:context-propagation:1.0.9'
// https://jarcasting.com/artifacts/nl.talsmasoftware/context-propagation/
implementation ("nl.talsmasoftware:context-propagation:1.0.9")
'nl.talsmasoftware:context-propagation:pom:1.0.9'
<dependency org="nl.talsmasoftware" name="context-propagation" rev="1.0.9">
  <artifact name="context-propagation" type="pom" />
</dependency>
@Grapes(
@Grab(group='nl.talsmasoftware', module='context-propagation', version='1.0.9')
)
libraryDependencies += "nl.talsmasoftware" % "context-propagation" % "1.0.9"
[nl.talsmasoftware/context-propagation "1.0.9"]

Dependencies

test (5)

Group / Artifact Type Version
org.junit.jupiter : junit-jupiter-engine jar 5.7.1
org.hamcrest : hamcrest jar 2.2
org.mockito : mockito-all jar 1.10.19
org.slf4j : jul-to-slf4j jar 1.7.30
ch.qos.logback : logback-classic jar 1.2.3

Project Modules

There are no modules declared in this project.

CI Build Coverage Status Maven Version Javadoc

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:

Terminology

Context

Abstraction containing a value in the context of a thread. The most common implementation in Java is a ThreadLocal value. The library provies 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 = ContextManagers.createContextSnapshot();

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

try (Context<Void> 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 is closed, ensuring no 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:

Custom contexts

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

Caching

By default the ContextManagers class caches the context manager instances it finds per classloader. Since the cache is per classloader, this should work satisfactory for applications with simple classloader hierarchies (e.g. dropwizard) and also for complex hierarchies (spring boot, JEE and the like).

Disable caching

If however, you wish to disable caching of the context manager instances, you can set either:

  • the java system property talsmasoftware.context.caching, or
  • the environment variable TALSMASOFTWARE_CONTEXT_CACHING

The values false or 0 will disable caching.

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 your 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.Timing 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 noticable 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

nl.talsmasoftware

Talsma ICT

Versions

Version
1.0.9
1.0.8
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.6.3
0.6.2
0.6.1
0.6.0
0.5.0
0.4.17
0.4.16
0.4.1
0.4.0
0.3.0
0.2.0