Skip to content

Commit

Permalink
Issue #27 explicitly specify cleared=TRANSACTION
Browse files Browse the repository at this point in the history
  • Loading branch information
@njr-11
njr-11 committed Oct 24, 2018
1 parent 9a8676f commit 842fe13
Show file tree
Hide file tree
Showing 6 changed files with 191 additions and 61 deletions.
42 changes: 37 additions & 5 deletions api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorBuilder.java
View file
Expand Up @@ -44,6 +44,9 @@ public interface ManagedExecutorBuilder {
* instances.</p>
*
* @return new instance of <code>ManagedExecutor</code>.
* @throws IllegalArgumentException if the same thread context type is
* present in, or inferred by, both the {@link #cleared} set
* and the {@link #propagated} set.
* @throws IllegalStateException if the direct or indirect
* {@link org.eclipse.microprofile.concurrent.spi.ThreadContextProvider#getPrerequisites prerequisites}
* of a <code>ThreadContextProvider</code> are unsatisfied,
Expand All @@ -53,19 +56,48 @@ public interface ManagedExecutorBuilder {
*/
ManagedExecutor build();

/**
* <p>Defines the set of thread context types to clear from the thread
* where the action or task executes. The previous context is resumed
* on the thread after the action or task ends.</p>
*
* <p>This set replaces the <code>cleared</code> set that was previously
* specified on the builder instance, if any.</p>
*
* <p>The default set of cleared thread context types is
* {@link ThreadContext#TRANSACTION}, which means that a transaction
* is not active on the thread when the action or task runs, such
* that each action or task is able to independently start and end
* its own transactional work.</p>
*
* <p>Constants for specifying some of the core context types are provided
* on {@link ThreadContext}. Other thread context types must be defined
* by the specification that defines the context type or by a related
* MicroProfile specification.</p>
*
* <p>Inclusion of a thread context type with prerequisites implies
* inclusion of the prerequisites, even if not explicitly specified.</p>
*
* @param types types of thread context to clear from threads that run
* actions and tasks.
* @return the same builder instance upon which this method is invoked.
*/
ManagedExecutorBuilder cleared(String... types);

/**
* <p>Defines the set of thread context types to capture from the thread
* 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>This set replaces the set that was previously specified on the
* builder instance.</p>
* <p>This set replaces the <code>propagated</code> set that was
* previously specified on the builder instance, if any.</p>
*
* <p>The default set of thread context types is
* {@link ThreadContext#DEFAULTS}, which includes all available
* {@link ThreadContext#ALL_OTHER}, 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
* threads, except for those that are explicitly {@link cleared},
* which, by default is {@link ThreadContext#TRANSACTION} context,
* in which case is suspended from the thread that runs the action or
* task.</p>
*
* <p>Constants for specifying some of the core context types are provided
Expand Down
39 changes: 35 additions & 4 deletions api/src/main/java/org/eclipse/microprofile/concurrent/ManagedExecutorConfig.java
View file
Expand Up @@ -45,16 +45,42 @@
@Retention(RUNTIME)
@Target(FIELD)
public @interface ManagedExecutorConfig {
/**
* <p>Defines the set of thread context types to clear from the thread
* where the action or task executes. The previous context is resumed
* on the thread after the action or task ends.</p>
*
* <p>By default, the transaction context is cleared/suspended from
* the execution thread so that actions and tasks can start and
* end transactions of their choosing, to independently perform their
* own transactional work, as needed.</p>
*
* <p>Constants for specifying some of the core context types are provided
* on {@link ThreadContext}. Other thread context types must be defined
* by the specification that defines the context type or by a related
* MicroProfile specification.</p>
*
* <p>Inclusion of a thread context type with prerequisites implies
* inclusion of the prerequisites, even if not explicitly specified.</p>
*
* <p>A <code>ManagedExecutor</code> must fail to inject, raising
* <code>DefinitionException</code> on application startup, if the same
* context type is implicitly or explicitly included in this set
* as well as in the set specified by {@link #propagated}.</p>
*/
String[] cleared() default { ThreadContext.TRANSACTION };

/**
* <p>Defines the set of thread context types to capture from the thread
* 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
* {@link ThreadContext#DEFAULTS}, which includes all available
* {@link ThreadContext#ALL_OTHER}, 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
* threads, except for those that are explicitly {@link cleared},
* which, by default is {@link ThreadContext#TRANSACTION} context,
* in which case is suspended from the thread that runs the action or
* task.</p>
*
* <p>Constants for specifying some of the core context types are provided
Expand All @@ -68,8 +94,13 @@
* <p>Thread context types which are not otherwise included in this set
* are cleared from the thread of execution for the duration of the
* action or task.</p>
*
* <p>A <code>ManagedExecutor</code> must fail to inject, raising
* <code>DefinitionException</code> on application startup, if the same
* context type is implicitly or explicitly included in this set
* as well as in the set specified by {@link #cleared}.</p>
*/
String[] propagated() default { ThreadContext.DEFAULTS };
String[] propagated() default { ThreadContext.ALL_OTHER };

/**
* <p>Establishes an upper bound on the number of async completion stage
Expand Down
57 changes: 30 additions & 27 deletions api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContext.java
View file
Expand Up @@ -48,17 +48,22 @@
*/
public interface ThreadContext {
/**
* <p>Identifier for all available thread context types that support
* capture and propagation to other threads.</p>
* <p>Identifier for all available thread context types which are
* not specified individually under <code>cleared</code>,
* <code>propagated</code>, or <code>unchanged</code>.</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 ManagedExecutorBuilder#cleared
* @see ManagedExecutorBuilder#propagated
* @see ManagedExecutorConfig#cleared
* @see ManagedExecutorConfig#propagated
* @see ThreadContextConfig#value
* @see ThreadContextBuilder
* @see ThreadContextConfig
*/
static final String ALL = "All";
static final String ALL_OTHER = "All other";

/**
* Identifier for application context. Application context controls the
Expand All @@ -68,7 +73,11 @@ public interface ThreadContext {
* application context means that the thread is not associated with any
* application.
*
* @see ManagedExecutorBuilder#cleared
* @see ManagedExecutorBuilder#propagated
* @see ManagedExecutorConfig#cleared
* @see ManagedExecutorConfig#propagated
* @see ThreadContextBuilder
* @see ThreadContextConfig
*/
static final String APPLICATION = "Application";
Expand All @@ -79,36 +88,25 @@ public interface ThreadContext {
* access to the scope of the session, request, and so forth that created the
* contextualized action.
*
* @see ManagedExecutorBuilder#cleared
* @see ManagedExecutorBuilder#propagated
* @see ManagedExecutorConfig#cleared
* @see ManagedExecutorConfig#propagated
* @see ThreadContextBuilder
* @see ThreadContextConfig
*/
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
* means that the thread is unauthenticated.
*
* @see ManagedExecutorBuilder#cleared
* @see ManagedExecutorBuilder#propagated
* @see ManagedExecutorConfig#cleared
* @see ManagedExecutorConfig#propagated
* @see ThreadContextBuilder
* @see ThreadContextConfig
*/
static final String SECURITY = "Security";
Expand All @@ -118,15 +116,20 @@ public interface ThreadContext {
* active transaction scope that is associated with the thread.
* Implementations are not expected to propagate transaction context across
* threads. Instead, the concept of transaction context is provided for its
* empty/default context, which means the active transaction on the thread
* cleared context, which means the active transaction on the thread
* is suspended such that a new transaction can be started if so desired.
* In most cases, the most desirable behavior will be to leave transaction
* context unconfigured such that it is defaulted to empty (suspended),
* context defaulted to cleared (suspended),
* in order to prevent dependent actions and tasks from accidentally
* enlisting in transactions that are on the threads where they happen to
* run.
*
* @see ThreadContextConfig#unchanged
* @see ManagedExecutorBuilder#cleared
* @see ManagedExecutorBuilder#propagated
* @see ManagedExecutorConfig#cleared
* @see ManagedExecutorConfig#propagated
* @see ThreadContextBuilder
* @see ThreadContextConfig
*/
static final String TRANSACTION = "Transaction";

Expand Down
44 changes: 37 additions & 7 deletions api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextBuilder.java
View file
Expand Up @@ -44,8 +44,9 @@ public interface ThreadContextBuilder {
*
* @return new instance of <code>ThreadContext</code>.
* @throws IllegalArgumentException if the same thread context type is
* present in, or inferred by, both the {@link #propagated} set
* and the {@link #unchanged} set.
* present in, or inferred by, more than one of the
* following categories:
* ({@link #cleared}, {@link #propagated}, {@link #unchanged}).
* @throws IllegalStateException if the direct or indirect
* {@link org.eclipse.microprofile.concurrent.spi.ThreadContextProvider#getPrerequisites prerequisites}
* of a <code>ThreadContextProvider</code> are unsatisfied,
Expand All @@ -65,19 +66,48 @@ public static ThreadContextBuilder instance() {
return ConcurrencyProvider.instance().newThreadContextBuilder();
}

/**
* <p>Defines the set of thread context types to clear from the thread
* where the action or task executes. The previous context is resumed
* on the thread after the action or task ends.</p>
*
* <p>This set replaces the <code>cleared</code> set that was
* previously specified on the builder instance, if any.</p>
*
* <p>The default set of cleared thread context types is
* {@link ThreadContext#TRANSACTION}, which means that a transaction
* is not active on the thread when the action or task runs, such
* that each action or task is able to independently start and end
* its own transactional work.</p>
*
* <p>Constants for specifying some of the core context types are provided
* on {@link ThreadContext}. Other thread context types must be defined
* by the specification that defines the context type or by a related
* MicroProfile specification.</p>
*
* <p>Inclusion of a thread context type with prerequisites implies
* inclusion of the prerequisites, even if not explicitly specified.</p>
*
* @param types types of thread context to clear from threads that run
* actions and tasks.
* @return the same builder instance upon which this method is invoked.
*/
ThreadContextBuilder cleared(String... types);

/**
* <p>Defines the set of thread context types to capture from the thread
* that contextualizes an action or task. This context is later
* re-established on the thread(s) where the action or task executes.</p>
*
* <p>This set replaces the 'propagated' set that was previously specified
* on the builder instance.</p>
* <p>This set replaces the <code>propagated</code> set that was
* previously specified on the builder instance, if any.</p>
*
* <p>The default set of thread context types is
* {@link ThreadContext#DEFAULTS}, which includes all available
* {@link ThreadContext#ALL_OTHER}, 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
* threads, except for those that are explicitly {@link cleared},
* which, by default is {@link ThreadContext#TRANSACTION} context,
* in which case is suspended from the thread that runs the action or
* task.</p>
*
* <p>Constants for specifying some of the core context types are provided
Expand Down
52 changes: 40 additions & 12 deletions api/src/main/java/org/eclipse/microprofile/concurrent/ThreadContextConfig.java
View file
Expand Up @@ -45,16 +45,43 @@
@Retention(RUNTIME)
@Target(FIELD)
public @interface ThreadContextConfig {
/**
* <p>Defines the set of thread context types to clear from the thread
* where the action or task executes. The previous context is resumed
* on the thread after the action or task ends.</p>
*
* <p>By default, the transaction context is cleared/suspended from
* the execution thread so that actions and tasks can start and
* end transactions of their choosing, to independently perform their
* own transactional work, as needed.</p>
*
* <p>Constants for specifying some of the core context types are provided
* on {@link ThreadContext}. Other thread context types must be defined
* by the specification that defines the context type or by a related
* MicroProfile specification.</p>
*
* <p>Inclusion of a thread context type with prerequisites implies
* inclusion of the prerequisites, even if not explicitly specified.</p>
*
* <p>A <code>ThreadContext</code> must fail to inject, raising
* <code>DefinitionException</code> on application startup, if the same
* context type is implicitly or explicitly included in this set
* as well as in the set specified by {@link #propagated}
* or the set specified by {@link #unchanged}.</p>
*/
String[] cleared() default { ThreadContext.TRANSACTION };

/**
* <p>Defines the set of thread context types to capture from the thread
* 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
* {@link ThreadContext#DEFAULTS}, which includes all available
* {@link ThreadContext#ALL_OTHER}, 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
* threads, except for those that are explicitly {@link cleared},
* which, by default is {@link ThreadContext#TRANSACTION} context,
* in which case is suspended from the thread that runs the action or
* task.</p>
*
* <p>Constants for specifying some of the core context types are provided
Expand All @@ -71,10 +98,10 @@
*
* <p>A <code>ThreadContext</code> must fail to inject, raising
* <code>DefinitionException</code> on application startup, if the same
* context type is included in this set as well as in the {@link #unchanged}
* set.</p>
* context type is included in this set as well as in the {@link #cleared}
* set or the {@link #unchanged} set.</p>
*/
String[] value() default { ThreadContext.DEFAULTS };
String[] value() default { ThreadContext.ALL_OTHER };

/**
* <p>Defines a set of thread context types that are essentially ignored,
Expand All @@ -90,8 +117,11 @@
* advanced patterns where it is desirable to leave certain context types
* on the executing thread.</p>
*
* <p>For example, to run under the transaction of the thread of execution:</p>
* <pre><code> &commat;Inject &commat;ThreadContextConfig(unchanged = ThreadContext.TRANSACTION)
* <p>For example, to run as the current application, but under the
* transaction of the thread where the task executes:</p>
* <pre><code> &commat;Inject &commat;ThreadContextConfig(unchanged = ThreadContext.TRANSACTION,
* propagated = ThreadContext.APPLICATION,
* cleared = ThreadContext.ALL_OTHER)
* ThreadContext threadContext;
* ...
* task = threadContext.withCurrentContext(new MyTransactionalTask());
Expand All @@ -110,10 +140,8 @@
* <p>A <code>ThreadContext</code> must fail to inject, raising
* <code>DefinitionException</code> on application startup, if the same
* context type is included in this set as well as in the set specified by
* {@link ThreadContextConfig#value}, or if {@link ThreadContext#ALL} is
* included in the <code>unchanged</code> context because the latter would
* otherwise render the <code>ThreadContext</code> instance meaningless.
* </p>
* {@link ThreadContextConfig#unchanged} or the set specified by
* {@link ThreadContextConfig#value}.</p>
*/
String[] unchanged() default {};
}

0 comments on commit 842fe13

Please sign in to comment.