Package org.eclipse.microprofile.context

Interface ThreadContext.Builder

  • Enclosing interface:
    ThreadContext
    public static interface ThreadContext.Builder

    Builder for ThreadContext instances.

    Example usage:

     ThreadContext threadContext = ThreadContext.builder()
                                                   .propagated(ThreadContext.APPLICATION, ThreadContext.SECURITY)
                                                   .unchanged(ThreadContext.TRANSACTION)
                                                   .build();
 ...

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      ThreadContext build()
      Builds a new ThreadContext instance with the configuration that this builder represents as of the point in time when this method is invoked.
      ThreadContext.Builder cleared​(java.lang.String... types)
      Defines the set of thread context types to clear from the thread where the action or task executes.
      ThreadContext.Builder propagated​(java.lang.String... types)
      Defines the set of thread context types to capture from the thread that contextualizes an action or task.
      ThreadContext.Builder unchanged​(java.lang.String... types)
      Defines a set of thread context types that are essentially ignored, in that they are neither captured nor are they propagated or cleared from thread(s) that execute the action or task.

    • Method Detail

      • build

        ThreadContext build()

        Builds a new ThreadContext instance 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 ThreadContext instances.

        All created instances of ThreadContext are destroyed when the application is stopped. The container automatically shuts down these ThreadContext instances and raises IllegalStateException to reject subsequent attempts to apply previously captured thread context.

        Returns:
        new instance of ThreadContext.
        Throws:
        java.lang.IllegalStateException - for any of the following error conditions

      • cleared

        ThreadContext.Builder cleared​(java.lang.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 neither the propagated(java.lang.String...) set nor the unchanged(java.lang.String...) set 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.ThreadContext.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

        ThreadContext.Builder propagated​(java.lang.String... types)

        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.

        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.ThreadContext.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 or in the unchanged(java.lang.String...) 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.

      • unchanged

        ThreadContext.Builder unchanged​(java.lang.String... types)

        Defines a set of thread context types that are essentially ignored, in that they are neither captured nor are they propagated or cleared from thread(s) that execute the action or task.

        This set replaces the unchanged set that was previously specified on the builder instance.

        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.ThreadContext.unchanged, 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. If a default value is not specified by MicroProfile Config, then the default value is an empty set.

        The configuration of unchanged context is provided for advanced patterns where it is desirable to leave certain context types on the executing thread.

        For example, to run under the transaction of the thread of execution, with security context cleared and all other thread contexts propagated:

         ThreadContext threadContext = ThreadContext.builder()
                                                   .unchanged(ThreadContext.TRANSACTION)
                                                   .cleared(ThreadContext.SECURITY)
                                                   .propagated(ThreadContext.ALL_REMAINING)
                                                   .build();
 ...
 task = threadContext.contextualRunnable(new MyTransactionlTask());
 ...
 // on another thread,
 tx.begin();
 ...
 task.run(); // runs under the transaction due to 'unchanged'
 tx.commit();
        Parameters:
        types - types of thread context to leave unchanged on the thread.
        Returns:
        the same builder instance upon which this method is invoked.