Using ThreadLocal safely is crucial because, while it provides a way to store data that is accessible only by a specific thread, it can easily lead to memory leaks and unexpected behavior in environments that use thread pools (like Spring MVC or Jakarta EE).

Here is how to use it safely in your Java applications.

1. Always Clean Up with remove()

This is the most important rule. In most modern applications, threads are reused (via a ThreadPoolExecutor). If you don’t call remove(), the data from a previous task will persist in the thread and can be “leaked” to the next task that happens to use the same thread.

The Pattern:
Always wrap your logic in a try-finally block to ensure remove() is called.

package org.kodejava.util.concurrent;

public class UserContextHolder {
    private static final ThreadLocal<String> userContext = new ThreadLocal<>();

    public static void set(String userId) {
        userContext.set(userId);
    }

    public static String get() {
        return userContext.get();
    }

    public static void clear() {
        userContext.remove();
    }
}

// Usage in a service or filter
try {
    UserContextHolder.set("user-123");
    // ... perform business logic ...
} finally {
    UserContextHolder.clear(); // CRITICAL: Prevents memory leaks and data contamination
}

2. Make the ThreadLocal Variable static final

ThreadLocal instances are typically meant to be metadata keys associated with a thread. Declaring them as private static final ensures there is only one ThreadLocal instance per class, which is more memory-efficient and prevents accidental re-initialization.

3. Consider ScopedValue (Java 21+)

Since you are using Java SDK 25, you should strongly consider using ScopedValue. It was introduced to address the pitfalls of ThreadLocal.

• Immutable: Data cannot be changed once bound.
• Automatic Cleanup: The value is only available within a specific scope and is automatically cleared when the scope ends.
• Performance: More efficient than ThreadLocal, especially with Virtual Threads.

private final static ScopedValue<String> USER_ID = ScopedValue.newInstance();

ScopedValue.where(USER_ID, "user-123").run(() -> {
    // Inside this block, USER_ID.get() returns "user-123"
    System.out.println("Processing for: " + USER_ID.get());
}); 
// Outside the block, the value is automatically gone. No manual remove() needed!

4. Use with Spring/Jakarta EE Filters

In a Spring MVC or Jakarta EE application, the best place to handle ThreadLocal setup and cleanup is in a Filter or an HandlerInterceptor.

@Component
public class ContextFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
            throws IOException, ServletException {
        try {
            String token = ((HttpServletRequest) request).getHeader("X-User-ID");
            UserContextHolder.set(token);
            chain.doFilter(request, response);
        } finally {
            UserContextHolder.clear(); // Ensures the thread is clean before returning to the pool
        }
    }
}

5. Be Wary of InheritableThreadLocal

InheritableThreadLocal allows child threads to inherit values from the parent thread. However, this is dangerous with thread pools because child threads are often created once and reused many times, meaning they might inherit “stale” state from the parent thread that originally spawned them.

Summary Checklist

1. Static Final: Always declare as private static final ThreadLocal<T> ....
2. Finally block: Always remove() in a finally block.
3. No leaks: Don’t store large objects (like heavy UI components or full DB entities) in ThreadLocal.
4. Modernize: If you are on Java 21+, use ScopedValue for a safer and more performant alternative.