Issue #27 define defaults for context propagation

Signed-off-by: Nathan Rauh <nathan.rauh@us.ibm.com>
eclipse · Oct 24, 2018 · 9a8676f · 9a8676f
1 parent 908c7ee
commit 9a8676f
Show file tree

Hide file tree

Showing 5 changed files with 51 additions and 12 deletions.
diff --git a/api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorBuilder.java b/api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorBuilder.java
@@ -61,8 +61,12 @@ public interface ManagedExecutorBuilder {
      * <p>This set replaces the set that was previously specified on the
      * builder instance.</p>
      *
-     * <p>The default set of thread context types is those required by the
-     * EE Concurrency spec, plus CDI.</p>
+     * <p>The default set of thread context types is
+     * {@link ThreadContext#DEFAULTS}, which includes all available
+     * thread context types that support capture and propagation to other
+     * threads, except for {@link ThreadContext#TRANSACTION} context, which
+     * is instead cleared (suspended) from the thread that runs the action or
+     * task.</p>
      *
      * <p>Constants for specifying some of the core context types are provided
      * on {@link ThreadContext}. Other thread context types must be defined

diff --git a/api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorConfig.java b/api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorConfig.java
@@ -50,8 +50,12 @@
      * that creates a dependent stage (or that submits a task) and which to
      * propagate to the thread where the action or task executes.</p>
      *
-     * <p>The default set of thread context types is those required by the
-     * EE Concurrency spec, plus CDI.</p>
+     * <p>The default set of thread context types is
+     * {@link ThreadContext#DEFAULTS}, which includes all available
+     * thread context types that support capture and propagation to other
+     * threads, except for {@link ThreadContext#TRANSACTION} context, which
+     * is instead cleared (suspended) from the thread that runs the action or
+     * task.</p>
      *
      * <p>Constants for specifying some of the core context types are provided
      * on {@link ThreadContext}. Other thread context types must be defined
@@ -65,7 +69,7 @@
      * are cleared from the thread of execution for the duration of the
      * action or task.</p>
      */
-    String[] propagated() default { ThreadContext.APPLICATION, ThreadContext.CDI, ThreadContext.SECURITY };
+    String[] propagated() default { ThreadContext.DEFAULTS };
 
     /**
      * <p>Establishes an upper bound on the number of async completion stage

diff --git a/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContext.java b/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContext.java
@@ -48,8 +48,12 @@
  */
 public interface ThreadContext {
     /**
-     * Identifier for all available thread context types that support capture
-     * and propagation to other threads.
+     * <p>Identifier for all available thread context types that support
+     * capture and propagation to other threads.</p>
+     *
+     * <p>When using this constant, be aware that bringing in a new
+     * context provider or updating levels of an existing context provider
+     * might change the set of available thread context types.</p>
      * 
      * @see ManagedExecutorConfig#propagated
      * @see ThreadContextConfig#value
@@ -80,6 +84,25 @@ public interface ThreadContext {
      */
     static final String CDI = "CDI";
 
+    /**
+     * <p>Identifier for the default set of thread context types, which is
+     * defined as all available thread context types that support capture and
+     * propagation to other threads except for {@link #TRANSACTION} context,
+     * which is instead cleared (suspended) from the thread that runs the
+     * action or task. This enables the action or task to choose whether, and
+     * if so, how, it participates in transactional work and is consistent
+     * with the generally established practice that transactions do not
+     * span threads.</p>
+     *
+     * <p>When using this constant, be aware that bringing in a new
+     * context provider or updating levels of an existing context provider
+     * might change the set of available thread context types.</p>
+     *
+     * @see ManagedExecutorConfig#propagated
+     * @see ThreadContextConfig
+     */
+    static final String DEFAULTS = "Defaults";
+
     /**
      * Identifier for security context. Security context controls the credentials
      * that are associated with the thread. An empty/default security context

diff --git a/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextBuilder.java b/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextBuilder.java
@@ -73,8 +73,12 @@ public static ThreadContextBuilder instance() {
      * <p>This set replaces the 'propagated' set that was previously specified
      * on the builder instance.</p>
      *
-     * <p>The default set of thread context types is those required by the
-     * EE Concurrency spec, plus CDI.</p>
+     * <p>The default set of thread context types is
+     * {@link ThreadContext#DEFAULTS}, which includes all available
+     * thread context types that support capture and propagation to other
+     * threads, except for {@link ThreadContext#TRANSACTION} context, which
+     * is instead cleared (suspended) from the thread that runs the action or
+     * task.</p>
      *
      * <p>Constants for specifying some of the core context types are provided
      * on {@link ThreadContext}. Other thread context types must be defined

diff --git a/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextConfig.java b/api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextConfig.java
@@ -50,8 +50,12 @@
      * that contextualizes an action or task. This context is later
      * re-established on the thread(s) where the action or task executes.</p>
      *
-     * <p>The default set of thread context types is those required by the
-     * EE Concurrency spec, plus CDI.</p>
+     * <p>The default set of thread context types is
+     * {@link ThreadContext#DEFAULTS}, which includes all available
+     * thread context types that support capture and propagation to other
+     * threads, except for {@link ThreadContext#TRANSACTION} context, which
+     * is instead cleared (suspended) from the thread that runs the action or
+     * task.</p>
      *
      * <p>Constants for specifying some of the core context types are provided
      * on {@link ThreadContext}. Other thread context types must be defined
@@ -70,7 +74,7 @@
      * context type is included in this set as well as in the {@link #unchanged}
      * set.</p>
      */
-    String[] value() default { ThreadContext.APPLICATION, ThreadContext.CDI, ThreadContext.SECURITY };
+    String[] value() default { ThreadContext.DEFAULTS };
 
     /**
      * <p>Defines a set of thread context types that are essentially ignored,