Unified Handling of ThreadLocal Issues in Java Projects

Java's ThreadLocal is widely used for implicit parameter passing and thread safety, but it often leads to information loss, corruption, or OOM because the stored data is not properly initialized and cleared.

Two main solutions are proposed:

Use a Java agent with bytecode modification to apply JVM‑level AOP side‑car handling, similar to how tracing tools like SkyWalking work.

Adopt an explicit or implicit proxy pattern by wrapping thread pools with ready‑made utilities, such as Spring Cloud Sleuth's tracing executors.

Examples of Spring‑provided classes include

org.springframework.cloud.sleuth.instrument.async.TraceableExecutorService

,

org.springframework.cloud.sleuth.autoconfig.instrument.async.ExecutorBeanPostProcessor

,

org.springframework.cloud.sleuth.instrument.async.TraceRunnable

, and

org.springframework.cloud.sleuth.instrument.async.TraceCallable

, which automatically propagate trace information.

To generalize ThreadLocal propagation, an interface is defined and registered via ThreadLocalCopyUtils.register(...). Implementations of AbstractThreadLocalCopy handle specific ThreadLocal instances, and a custom ThreadLocalRunnable replaces the original Runnable logic to perform initialization and cleanup.

Testing shows that without registering the custom copies, ThreadLocal data (e.g., MDC, custom TEST) is lost in asynchronous threads, while after registration the main thread's information is correctly transferred to worker threads.

By implementing the interface for any business‑specific ThreadLocal and using the provided utilities together with the wrapped thread pool, developers can reliably prevent ThreadLocal information loss and ensure proper cleanup.

Conclusion : The article presents two practical, widely used methods to solve ThreadLocal information loss, corruption, and OOM problems in Java projects, offering both agent‑based bytecode manipulation and Spring‑based proxy wrappers with concrete code examples.