docs: improve javadoc of registerThreadLocal* methods, add note for…

… getting `ThreadLocal` instances by reflection #329
alibaba · Jul 1, 2022 · cc95487 · cc95487
1 parent 854e0a3
commit cc95487
Showing 1 changed file with 36 additions and 0 deletions.
diff --git a/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java b/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java
@@ -745,6 +745,15 @@ public static <R> R runCallableWithClear(@NonNull Callable<R> bizLogic) throws E
          * since a {@link TransmittableThreadLocal} instance itself has the {@code Transmittable} ability,
          * it is unnecessary to register a {@link TransmittableThreadLocal} instance.
          * <p>
+         * The fields stored the {@code ThreadLocal} instances are generally {@code private static},
+         * so the {@code ThreadLocal} instances need be got by reflection:
+         *
+         * <pre>{@code Field field = TheClassStoredThreadLocal.class.getDeclaredField(staticFieldName);
+         * field.setAccessible(true);
+         * @SuppressWarnings("unchecked")
+         * ThreadLocal<T> threadLocal = (ThreadLocal<T>) field.get(null);
+         * }</pre>
+         * <p>
          * <B><I>Caution:</I></B><br>
          * If the registered {@link ThreadLocal} instance is not {@link InheritableThreadLocal},
          * the instance can NOT <B><I>{@code inherit}</I></B> value from parent thread(aka. the <b>inheritable</b> ability)!
@@ -771,6 +780,15 @@ public static <T> boolean registerThreadLocal(@NonNull ThreadLocal<T> threadLoca
          * since a {@link TransmittableThreadLocal} instance itself has the {@code Transmittable} ability,
          * it is unnecessary to register a {@link TransmittableThreadLocal} instance.
          * <p>
+         * The fields stored the {@code ThreadLocal} instances are generally {@code private static},
+         * so the {@code ThreadLocal} instances need be got by reflection:
+         *
+         * <pre>{@code Field field = TheClassStoredThreadLocal.class.getDeclaredField(staticFieldName);
+         * field.setAccessible(true);
+         * @SuppressWarnings("unchecked")
+         * ThreadLocal<T> threadLocal = (ThreadLocal<T>) field.get(null);
+         * }</pre>
+         * <p>
          * <B><I>Caution:</I></B><br>
          * If the registered {@link ThreadLocal} instance is not {@link InheritableThreadLocal},
          * the instance can NOT <B><I>{@code inherit}</I></B> value from parent thread(aka. the <b>inheritable</b> ability)!
@@ -794,6 +812,15 @@ public static <T> boolean registerThreadLocalWithShadowCopier(@NonNull ThreadLoc
          * since a {@link TransmittableThreadLocal} instance itself has the {@code Transmittable} ability,
          * it is unnecessary to register a {@link TransmittableThreadLocal} instance.
          * <p>
+         * The fields stored the {@code ThreadLocal} instances are generally {@code private static},
+         * so the {@code ThreadLocal} instances need be got by reflection:
+         *
+         * <pre>{@code Field field = TheClassStoredThreadLocal.class.getDeclaredField(staticFieldName);
+         * field.setAccessible(true);
+         * @SuppressWarnings("unchecked")
+         * ThreadLocal<T> threadLocal = (ThreadLocal<T>) field.get(null);
+         * }</pre>
+         * <p>
          * <B><I>Caution:</I></B><br>
          * If the registered {@link ThreadLocal} instance is not {@link InheritableThreadLocal},
          * the instance can NOT <B><I>{@code inherit}</I></B> value from parent thread(aka. the <b>inheritable</b> ability)!
@@ -835,6 +862,15 @@ public static <T> boolean registerThreadLocal(@NonNull ThreadLocal<T> threadLoca
          * since a {@link TransmittableThreadLocal} instance itself has the {@code Transmittable} ability,
          * it is unnecessary to register a {@link TransmittableThreadLocal} instance.
          * <p>
+         * The fields stored the {@code ThreadLocal} instances are generally {@code private static},
+         * so the {@code ThreadLocal} instances need be got by reflection:
+         *
+         * <pre>{@code Field field = TheClassStoredThreadLocal.class.getDeclaredField(staticFieldName);
+         * field.setAccessible(true);
+         * @SuppressWarnings("unchecked")
+         * ThreadLocal<T> threadLocal = (ThreadLocal<T>) field.get(null);
+         * }</pre>
+         * <p>
          * <B><I>Caution:</I></B><br>
          * If the registered {@link ThreadLocal} instance is not {@link InheritableThreadLocal},
          * the instance can NOT <B><I>{@code inherit}</I></B> value from parent thread(aka. the <b>inheritable</b> ability)!