Package com.im.commons.base

Class ThreadContext

  • public final class ThreadContext
extends java.lang.Object
    The support for associating properties with threads. This class supports three main usecases.
    Since:
    6.4

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static ThreadContext EMPTY
      An empty ThreadContext.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static <V> V callInContext​(java.util.concurrent.Callable<V> task, java.util.Map<?,​?> context)
      Calls a Callable task with the supplied context.
      static java.lang.Runnable contextAware​(java.lang.Runnable task)
      Creates a Runnable wrapper that preserves the current ThreadContext.
      static <V> java.util.concurrent.Callable<V> contextAware​(java.util.concurrent.Callable<V> task)
      Creates a Callable wrapper that preserves the current ThreadContext.
      static java.util.concurrent.ExecutorService contextAware​(java.util.concurrent.ExecutorService executors)
      Creates an ExecutorService wrapper that preserves ThreadContext.
      static ThreadContext getCurrent()
      Gets the ThreadContext for the current thread.
      <T> T getProperty​(java.lang.Object key)
      Gets a property value for a key stored in this ThreadContext.
      static void runInContext​(java.lang.Runnable task, java.util.Map<?,​?> context)
      Runs a Runnable task with the supplied context.
      static void set​(ThreadContext value)  
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • EMPTY

        public static final ThreadContext EMPTY
        An empty ThreadContext. This context is returned from getCurrent() if there is no context set for the current thread.

    • Method Detail

      • getCurrent

        public static ThreadContext getCurrent()
        Gets the ThreadContext for the current thread.
        Returns:
        Current thread's context or EMPTY if the current thread has no context.

      • runInContext

        public static void runInContext​(java.lang.Runnable task,
                                java.util.Map<?,​?> context)
        Runs a Runnable task with the supplied context. If there is already some context associated with the calling thread it is merged with the new context passed into this method. The new context takes precedence, however.
        Parameters:
        task - The task to run.
        context - The context to associate with the calling thread. This context is then made available within the task if it calls getCurrent().

      • callInContext

        public static <V> V callInContext​(java.util.concurrent.Callable<V> task,
                                  java.util.Map<?,​?> context)
                           throws java.lang.Exception
        Calls a Callable task with the supplied context. If there is already some context associated with the calling thread it is merged with the new context passed into this method. The new context takes precedence, however.
        Type Parameters:
        V - The Callable task result type.
        Parameters:
        task - The task to run.
        context - The context to associate with the calling thread. This context is then made available within the task if it calls getCurrent().
        Returns:
        result of the task
        Throws:
        java.lang.Exception - if unable to compute a result

      • contextAware

        public static <V> java.util.concurrent.Callable<V> contextAware​(java.util.concurrent.Callable<V> task)
        Creates a Callable wrapper that preserves the current ThreadContext.

        This method must be used by any code that schedules Callable tasks running on a background thread. Failing to do so may result in the scheduler's ThreadContext not being visible in the spawned background threads. In particular this is important when using thread pools for performing background tasks such as various ExecutorService implementations provided by Executors class.

        This example shows how to implement a ThreadContext friendly scheduler.

         private final ExecutorService E = Executors.newFixedThreadPool(5);
 ...
 public Foo perform() {
     return E.submit(ThreadContext.contextAware(new Callable<Foo>() {
         public Foo call() {
             ...
         }
     }));
 }
        Type Parameters:
        V - The Callable task result type.
        Parameters:
        task - The task to accompany with the current ThreadContext.
        Returns:
        The ThreadContext friendly Callable for the original task.

      • contextAware

        public static java.lang.Runnable contextAware​(java.lang.Runnable task)
        Creates a Runnable wrapper that preserves the current ThreadContext.

        This method must be used by any code that schedules Runnable tasks running on a background thread. Failing to do so may result in the scheduler's ThreadContext not being visible in the spawned background threads. In particular this is important when using thread pools for performing background tasks such as various ExecutorService implementations provided by Executors class.

        This example shows how to implement a ThreadContext friendly scheduler.

         private final ExecutorService E = Executors.newFixedThreadPool(5);
 ...
 public void perform() {
     E.submit(ThreadContext.contextAware(new Runnable() {
         public void run() {
             ...
         }
     }));
 }
        Parameters:
        task - The task to accompany with the current ThreadContext.
        Returns:
        The ThreadContext friendly Runnable for the original task.

      • contextAware

        public static java.util.concurrent.ExecutorService contextAware​(java.util.concurrent.ExecutorService executors)
        Creates an ExecutorService wrapper that preserves ThreadContext.

        This is an alternative to calling contextAware(Runnable) and contextAware(Callable) methods, which can be used for creating a ThreadContext aware ExecutionService. Any code that creates and uses ExecutorService must either use this method or take care of using contextAware(Runnable) or contextAware(Callable) for particular tasks that it schedules. Failing to do so may result in the scheduler's ThreadContext not being visible in the spawned background threads.

        This example shows how to create a ThreadContext friendly ExecutorService.

         private final ExecutorService E = ThreadContext.contextAware(Executors.newFixedThreadPool(5));
 ...
 public void perform() {
     E.submit(new Runnable() {
         public void run() {
             ...
         }
     });
 }
        Parameters:
        executors - The original ExecutorService.
        Returns:
        The ThreadContext friendly ExecutorService..

      • getProperty

        public <T> T getProperty​(java.lang.Object key)
        Gets a property value for a key stored in this ThreadContext.
        Type Parameters:
        T - The property value type.
        Parameters:
        key - The property key.
        Returns:
        The property value or null if such a property is not in this ThreadContext.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object