What is ThreadLocal in Java?

ThreadLocal lets each thread keep its own private value, even though all threads access the same ThreadLocal variable.

It is useful when you want data to be available throughout the current thread's execution without passing it through every method call.

Imagine a web server handling many requests at the same time. Each request may have its own user ID, request ID, tenant ID, or trace ID.

You could pass that data through every method:

service.processOrder(order, userId, requestId, tenantId);

But as the call chain grows, this becomes noisy. ThreadLocal gives you a way to attach context to the current thread.

RequestContextHolder.set(
    new RequestContext(userId, requestId, tenantId)
);

service.processOrder(order);

Now deeper code can read the current request context without every method needing extra parameters.

All three threads access the same ThreadLocal variable, but each thread sees its own value.

public class RequestContextHolder {
    private static final ThreadLocal<String> currentUser =
        new ThreadLocal<>();

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

    public static String getUser() {
        return currentUser.get();
    }

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

The important methods are:

• set() stores a value for the current thread.
• get() reads the value for the current thread.
• remove() clears the value for the current thread.

This is the part many developers miss:

A ThreadLocal does not directly store one global value.

Instead, each Java Thread internally contains a special structure called a ThreadLocalMap.

Conceptually, developers often imagine this:

Map<Thread, Value>

That mental model is close, but the real implementation is more like:

Thread
        └── ThreadLocalMap
            ├── ThreadLocal -> value
            ├── ThreadLocal -> value
            └── ThreadLocal -> value

Each thread owns its own internal map of ThreadLocal keys to values.

So when code calls:

currentUser.set("Alice");

Java internally does something conceptually similar to:

Thread.currentThread()
            .threadLocalMap
            .put(currentUser, "Alice");

Then later:

currentUser.get();

conceptually behaves like:

Thread.currentThread()
            .threadLocalMap
            .get(currentUser);

That is why the same ThreadLocal variable can safely return different values for different threads.

Notice that both threads are using the SAME ThreadLocal object:

private static final ThreadLocal<String> currentUser =
            new ThreadLocal<>();

But each thread stores its own separate value inside its own ThreadLocalMap.

In a web server, threads are usually reused. A thread that handled User A's request may later handle User B's request.

If you set a ThreadLocal value and forget to remove it, the next request using the same thread may accidentally see old data.

try {
    RequestContextHolder.setUser(userId);

    service.handleRequest(request);
} finally {
    RequestContextHolder.clear();
}

The finally block matters because it runs even if the request fails. That prevents old context from leaking into future work on the same reused thread.

• Request context in web applications
• Correlation IDs and tracing IDs
• Security context
• Tenant context in multi-tenant systems
• Transaction context
• Logging MDC-style context

ThreadLocal should not become a hidden global variable. If normal parameter passing is clear and simple, prefer that.

Overusing ThreadLocal can make code harder to test and harder to reason about because dependencies are hidden instead of explicit.