Package com.alibaba.ttl

Class TransmittableThreadLocal.Transmitter

  • Enclosing class:
    TransmittableThreadLocal<T>
    public static class TransmittableThreadLocal.Transmitter
extends Object
    TransmittableThreadLocal.Transmitter transmit all TransmittableThreadLocal and registered ThreadLocal(registered by registerThreadLocal(java.lang.ThreadLocal<T>, com.alibaba.ttl.TtlCopier<T>)) values of the current thread to other thread by static methods capture() => replay(Object) => restore(Object) (aka CRR operation).

    TransmittableThreadLocal.Transmitter is internal manipulation api for framework/middleware integration; In general, you will never use it in the biz/application code!

    Framework/Middleware integration to TTL transmittance

    Below is the example code: 
    
 ///////////////////////////////////////////////////////////////////////////
 // in thread A, capture all TransmittableThreadLocal values of thread A
 ///////////////////////////////////////////////////////////////////////////

 Object captured = Transmitter.capture(); // (1)

 ///////////////////////////////////////////////////////////////////////////
 // in thread B
 ///////////////////////////////////////////////////////////////////////////

 // replay all TransmittableThreadLocal values from thread A
 Object backup = Transmitter.replay(captured); // (2)
 try {
     // your biz logic, run with the TransmittableThreadLocal values of thread B
     System.out.println("Hello");
     // ...
     return "World";
 } finally {
     // restore the TransmittableThreadLocal of thread B when replay
     Transmitter.restore(backup); (3)
 }

    see the implementation code of TtlRunnable and TtlCallable for more actual code sample.

    Of course, replay(Object) and restore(Object) operation can be simplified by util methods runCallableWithCaptured(Object, Callable) or runSupplierWithCaptured(Object, Supplier) and the adorable Java 8 lambda syntax.

    Below is the example code: 

    
 ///////////////////////////////////////////////////////////////////////////
 // in thread A, capture all TransmittableThreadLocal values of thread A
 ///////////////////////////////////////////////////////////////////////////

 Object captured = Transmitter.capture(); // (1)

 ///////////////////////////////////////////////////////////////////////////
 // in thread B
 ///////////////////////////////////////////////////////////////////////////

 String result = runSupplierWithCaptured(captured, () -> {
      // your biz logic, run with the TransmittableThreadLocal values of thread A
      System.out.println("Hello");
      ...
      return "World";
 }); // (2) + (3)

    The reason of providing 2 util methods is the different throws Exception type so as to satisfy your biz logic(lambda):

    1. runCallableWithCaptured(Object, Callable): throws Exception
    2. runSupplierWithCaptured(Object, Supplier): No throws

    If you need the different throws Exception type, you can define your own util method(function interface(lambda)) with your own throws Exception type.

    ThreadLocal Integration

    If you can not rewrite the existed code which use ThreadLocal to TransmittableThreadLocal, register the ThreadLocal instances via the methods registerThreadLocal(ThreadLocal, TtlCopier)/registerThreadLocalWithShadowCopier(ThreadLocal) to enhance the Transmittable ability for the existed ThreadLocal instances.

    Below is the example code: 

    
 // the value of this ThreadLocal instance will be transmitted after registered
 Transmitter.registerThreadLocal(aThreadLocal, copyLambda);

 // Then the value of this ThreadLocal instance will not be transmitted after unregistered
 Transmitter.unregisterThreadLocal(aThreadLocal);
    Caution:
    If the registered ThreadLocal instance is not InheritableThreadLocal, the instance can NOT inherit value from parent thread(aka. the inheritable ability)!
    Since:
    2.3.0
    Author:
    Yang Fang (snoop dot fy at gmail dot com), Jerry Lee (oldratlee at gmail dot com)
    See Also:
    TtlRunnable, TtlCallable