From f27ef307f9ad33b6d1c458f5ff66091412b9017f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20=C3=89pardaud?= Date: Mon, 15 Jul 2019 17:33:55 +0200 Subject: [PATCH] Added link to spec, removed contents that is in spec and out of date --- README.adoc | 159 +--------------------------------------------------- 1 file changed, 1 insertion(+), 158 deletions(-) diff --git a/README.adoc b/README.adoc index c8fb7ca..b00f09f 100644 --- a/README.adoc +++ b/README.adoc @@ -18,6 +18,7 @@ // image:https://img.shields.io/maven-central/v/org.eclipse.microprofile.context-propagation/microprofile-context-propagation-api.svg[link="http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.microprofile.context-propagation%22%20AND%20a%3A%22microprofile-context-propagation-api%22"] image:https://javadoc.io/badge/org.eclipse.microprofile.context-propagation/microprofile-context-propagation-api.svg[ link="https://javadoc.io/doc/org.eclipse.microprofile.context-propagation/microprofile-context-propagation-api"] +image:https://img.shields.io/badge/Specification-1.0-blue.svg[link="https://download.eclipse.org/microprofile/microprofile-context-propagation-1.0/microprofile-context-propagation.html"] image:https://badges.gitter.im/eclipse/microprofile-concurrency.svg[link="https://gitter.im/eclipse/microprofile-concurrency"] [[microprofile-context-propagation]] @@ -25,164 +26,6 @@ image:https://badges.gitter.im/eclipse/microprofile-concurrency.svg[link="https: :toc: -* Status: *new* -* Decision Notes: -https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/microprofile/jKFu-IS_U90[Discussion -thread topic with background and covering the design] - -[[introduction]] -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. - -[[motivation]] -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 -https://github.com/eclipse-ee4j/concurrency-api/issues/40[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]] -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]] -Builders -^^^^^^^^^ - -It shall be possible to build instances of ManagedExecutor and -ThreadContext via a fluent builder pattern, for example: - -[source,java] ----- - ManagedExecutor executor = ManagedExecutor.builder() - .maxAsync(5) - .propagated(ThreadContext.CDI, ThreadContext.APPLICATION) - .build(); - - ThreadContext threadContext = ThreadContext.builder() - .propagated(ThreadContext.SECURITY) - .build(); - ... - CompletableFuture stage = executor - .supplyAsync(supplier1) - .thenApplyAsync(function1) - .thenApply(function2) - .thenApply(threadContext.contextualFunction(function3)); ----- - -[[injection]] -Injection -^^^^^^^^^ - -The builders can be used in combination with standard CDI producers and injection -to define and manage single instances across an application: - -[source,java] ----- - @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; ----- - -[[spi-for-context-providers]] -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]] Contributing ~~~~~~~~~~~~