Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added link to spec, removed contents that is in spec and out of date #169

Closed
wants to merge 1 commit into from
Closed

Added link to spec, removed contents that is in spec and out of date #169

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 1 addition & 158 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,171 +18,14 @@
//
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]]
= MicroProfile Context Propagation

: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]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching the out-of-date material and removing it. I agree with removing the above, however, removing what follows after this would leave us with an empty doc on the main page, so I think it would be better to just update more specific out-of-date wording. I'll add some review comments below attempting to do that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that initially too, except we do have a link to the rendered spec so it's easy to get to the info, and whatever we duplicate here will always end up out-of-date.

I think this file should concentrate on things that are not in the spec.

A short intro of a single paragraph should be fine, though.


[[introduction]]
Introduction
~~~~~~~~~~~~

The proposal introduces APIs for obtaining CompletableFutures that are
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can change "The proposal" to "This specification"

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"It shall be possible to ..." can change to, "With MicroProfile Context Propagation, you can ..."

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<Integer> 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
~~~~~~~~~~~~
Expand Down