Package org.eclipse.microprofile.context

Interface ManagedExecutor.Builder

Enclosing interface:
ManagedExecutor
public static interface ManagedExecutor.Builder

Builder for ManagedExecutor instances.

Example usage:

 ManagedExecutor executor = ManagedExecutor.builder()
                                                  .maxAsync(5)
                                                  .maxQueued(20)
                                                  .propagated(ThreadContext.SECURITY)
                                                  .build();
 ...

  • Method Summary

    Modifier and Type
    Method
    Description
    ManagedExecutor
    build()
    Builds a new ManagedExecutor with the configuration that this builder represents as of the point in time when this method is invoked.
    ManagedExecutor.Builder
    cleared(String... types)
    Defines the set of thread context types to clear from the thread where the action or task executes.
    ManagedExecutor.Builder
    maxAsync(int max)
    Establishes an upper bound on the number of async completion stage actions and async executor tasks that can be running at any given point in time.
    ManagedExecutor.Builder
    maxQueued(int max)
    Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution.
    ManagedExecutor.Builder
    propagated(String... types)
    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.

  • Method Details

    • build

      ManagedExecutor build()

      Builds a new ManagedExecutor with the configuration that this builder represents as of the point in time when this method is invoked.

      After build() is invoked, the builder instance retains its configuration and may be further updated to represent different configurations and build additional ManagedExecutor instances.

      All created instances of ManagedExecutor are destroyed when the application is stopped. The container automatically shuts down these managed executors.

      Returns:
      new instance of ManagedExecutor.
      Throws:
      IllegalStateException - for any of the following error conditions

    • cleared

      ManagedExecutor.Builder cleared(String... types)

      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.

      This set replaces the cleared set that was previously specified on the builder instance, if any.

      For example, if the user specifies ThreadContext.TRANSACTION in this set, then 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.

      ThreadContext.ALL_REMAINING is automatically appended to the set of cleared context if the propagated(java.lang.String...) set does not include ThreadContext.ALL_REMAINING.

      Constants for specifying some of the core context types are provided on ThreadContext. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

      The MicroProfile Config property, mp.context.ManagedExecutor.cleared, establishes a default that is used if no value is otherwise specified. The value of the MicroProfile Config property can be the empty string or a comma separated list of context type constant values.

      Parameters:
      types - types of thread context to clear from threads that run actions and tasks.
      Returns:
      the same builder instance upon which this method is invoked.

    • propagated

      ManagedExecutor.Builder propagated(String... types)

      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.

      This set replaces the propagated set that was previously specified on the builder instance, if any.

      Constants for specifying some of the core context types are provided on ThreadContext. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

      The MicroProfile Config property, mp.context.ManagedExecutor.propagated, establishes a default that is used if no value is otherwise specified. The value of the MicroProfile Config property can be the empty string or a comma separated list of context type constant values.

      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.

      Parameters:
      types - types of thread context to capture and propagate.
      Returns:
      the same builder instance upon which this method is invoked.

    • maxAsync

      ManagedExecutor.Builder maxAsync(int max)

      Establishes an upper bound on the number of async completion stage actions and async executor tasks that can be running at any given point in time. There is no guarantee that async actions or tasks will start running immediately, even when the maxAsync constraint has not get been reached. Async actions and tasks remain queued until the ManagedExecutor starts executing them.

      The default value of -1 indicates no upper bound, although practically, resource constraints of the system will apply. You can switch the default by specifying the MicroProfile Config property, mp.context.ManagedExecutor.maxAsync.

      Parameters:
      max - upper bound on async completion stage actions and executor tasks.
      Returns:
      the same builder instance upon which this method is invoked.
      Throws:
      IllegalArgumentException - if max is 0 or less than -1.

    • maxQueued

      ManagedExecutor.Builder maxQueued(int max)

      Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution. Async actions and tasks are rejected if no space in the queue is available to accept them.

      The default value of -1 indicates no upper bound, although practically, resource constraints of the system will apply. You can switch the default by specifying the MicroProfile Config property, mp.context.ManagedExecutor.maxQueued.

      Parameters:
      max - upper bound on async actions and tasks that can be queued.
      Returns:
      the same builder instance upon which this method is invoked.
      Throws:
      IllegalArgumentException - if max is 0 or less than -1.