MicroProfile Context Propagation

• Status: new

• Decision Notes: Discussion thread topic with background and covering the design

Introduction

The proposal introduces APIs for obtaining CompletableFutures that are backed by managed threads (threads that are managed by the container), with the ability to capture context from the thread that creates the CompletableFuture and apply it when running the CompletionStage action.

Documentation

For links to the latest Javadoc and specification document, see the latest release.

Motivation

When using a reactive model with dependent stages which execute upon completion of prior stages, the context under which dependent stages execute is unpredictable. Dependent stages might run with the context of a thread that awaits completion, or the context of a previous stage that completed and triggered the dependent stage, or with no/undefined context at all. Existing solutions for transferring thread context, such as the EE Concurrency Utilities ContextService, are difficult to use and require a lot of boilerplate code. This spec makes it possible for thread context propagation to easily be done in a type-safe way, keeping boilerplate code to a minimum, as well as allowing for thread context propagation to be done automatically when using a CompletableFuture.

It is also important that CompletableFutures and their dependent stages, and dependent stages created by those stages, and so on, all run on threads that are known by the container and properly managed by it. This spec makes it possible to do so by providing an API by which the user obtains managed CompletableFuture instances from a managed executor.

The above are proposed to be addressed within EE Concurrency under EE Concurrency Issue 40, however, it will be a while before Jakarta EE specs are able to make progress, leading us to address this first in MicroProfile.

Goals

• Proper management of CompletableFuture threads by the container.

• Mechanism for thread context propagation to CompletableFuture actions that reduces the need for boilerplate code.

• Full compatibility with EE Concurrency spec, such that proposed interfaces can eventually be seamlessly merged into EE Concurrency.

Proposed solution

This spec introduces two interfaces that contain methods that we hope will eventually be added to Jakarta EE Concurrency.

The interface, org.eclipse.microprofile.concurrent.ManagedExecutor, provides methods for obtaining managed instances of CompletableFuture which are backed by the managed executor as the default asynchronous execution facility and the default mechanism of defining thread context propagation. Similar to EE Concurrency’s ManagedExecutorService, the MicroProfile ManagedExecutor also implements the Java SE java.util.concurrent.ExecutorService interface, using managed threads when asynchronous invocation is required and disallowing the same life cycle methods as ManagedExecutorService. It is intended that ManagedExecutor methods will one day be added to ManagedExecutorService, and for a single implementation to be capable of simultaneously implementing both interfaces, both currently as well as after adoption into Jakarta EE.

A second interface, org.eclipse.microprofile.concurrent.ThreadContext, provides methods for individually contextualizing dependent stage actions. This gives the user more fine-grained control over the capture and propagation of thread context. It is intended that ThreadContext methods will one day be added to EE Concurrency’s ContextService and for a single implementation to be capable of simultaneously implementing both interfaces, both currently as well as after adoption into Jakarta EE.

Builders

It shall be possible to build instances of ManagedExecutor and ThreadContext via a fluent builder pattern, for example:

  ManagedExecutor executor = ManagedExecutor.builder()
                                            .maxAsync(5)
                                            .propagated(ThreadContext.CDI, ThreadContext.APPLICATION)
                                            .build();

  ThreadContext threadContext = ThreadContext.builder()
                                             .propagated(ThreadContext.SECURITY)
                                             .build();
  ...
  CompletableFuture<Integer> stage = executor
      .supplyAsync(supplier1)
      .thenApplyAsync(function1)
      .thenApply(function2)
      .thenApply(threadContext.contextualFunction(function3));

Injection

The builders can be used in combination with standard CDI producers and injection to define and manage single instances across an application:

  @Produces @ApplicationScoped @MyQualifier
  createExecutor() {
      return ManagedExecutor.builder()
                            .propagated(ThreadContext.SECURITY)
                            .cleared(ThreadContext.ALL_REMAINING)
                            .build();
  }

  disposeExecutor(@Disposes @MyQualifier exec) {
      exec.shutdownNow();
  }

  ... // CDI injection point, possibly in another bean,

  @Inject @MyQualifier ManagedExecutor executor;

Context Propagation Defaults

The MicroProfile Context Propagation specification does not define a default set of context types that must be propagated in the absence of explicit configuration. Implementations of MicroProfile Context Propagation are encouraged to default to propagating all available context types unless doing so would cause unexpected behavior. For consistency with the Jakarta/Java EE Concurrency programming model, transaction context may be cleared by default, rather than propagated by default, by implementations that are also Jakarta/Java EE application servers.

You can define your own defaults for context propagation via MicroProfile Config properties. For example,

mp.context.ManagedExecutor.cleared=Transaction
mp.context.ManagedExecutor.propagated=Remaining
mp.context.ThreadContext.cleared=Transaction
mp.context.ThreadContext.propagated=Remaining

SPI for Thread Context Providers

The initial release of EE Concurrency assumed single monolithic implementations of all specifications together that could rely on vendor-specific internals to achieve context propagation. However, in practice, open source implementations of various specs are often pieced together into a comprehensive solution.

The thread context provider SPI is defined to bridge the gap, allowing any provider of thread context to publish and make available the type of thread context it supports, following a standard and predictable pattern that can be relied upon by a MicroProfile Context Propagation implementation, enabling it to facilitate the inclusion of any generic thread context alongside the spec defined thread context types that it captures and propagates.

With this model, the provider of thread context implements the org.eclipse.microprofile.concurrent.spi.ThreadContextProvider interface and packages it in a way that makes it available to the ServiceLoader. ThreadContextProvider identifies the thread context type and provides a way to capture snapshots of thread context as well as for applying empty/cleared context to threads.

Contributing

Do you want to contribute to this project? Find out how you can help here.