Master Spring Bean Scopes and ThreadLocal to Prevent Thread‑Safety Bugs

Spring Bean Scopes and Thread Safety

Spring manages objects (beans) through its IoC/DI container, but it does not guarantee that beans are thread‑safe; developers must design thread‑safe beans themselves. Each bean has a scope attribute that defines its lifecycle, such as singleton, prototype, request, session, application, and websocket.

singleton : one instance per Spring container, created on first injection and reused until the application shuts down.

prototype : a new instance is created on every injection.

request : one instance per HTTP request.

session : one instance per HTTP session.

application : one instance per ServletContext.

websocket : one instance per WebSocket lifecycle.

Most beans managed by Spring are stateless (e.g., DO, DTO, VO, Service, DAO, Controller). Stateless objects are inherently thread‑safe because they hold no mutable state that could be corrupted by concurrent threads. Using a singleton for such beans also saves object‑creation and GC overhead.

Changing a controller’s scope to prototype can avoid shared state, but it incurs higher object‑creation cost and may degrade performance compared to the default singleton approach.

ThreadLocal Overview

ThreadLocal

provides a thread‑local variable: each thread gets its own independent copy of the variable, preventing accidental sharing between threads. It is a shallow copy mechanism; for reference types, overriding initialValue() to return a deep copy is recommended.

Unlike synchronization primitives, ThreadLocal trades time for space: it avoids locking overhead by allocating separate storage per thread.

ThreadLocal Internal Implementation

Each thread holds a ThreadLocalMap, a custom hash map that uses linear probing. The map’s keys are ThreadLocal objects stored as WeakReference instances, and values are the thread‑local copies. static class ThreadLocalMap { ... } Key fields include:

private final int threadLocalHashCode = nextHashCode();
private static AtomicInteger nextHashCode = new AtomicInteger();
private static final int HASH_INCREMENT = 0x61c88647;

The hash code is generated by adding HASH_INCREMENT to an atomic counter, ensuring a power‑of‑two table size and good distribution.

Retrieving a value calls get(), which obtains the current thread’s map via getMap(Thread t). If the map is null, setInitialValue() creates it and stores the initial value.

public T get() {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);
    if (map != null) {
        ThreadLocalMap.Entry e = map.getEntry(this);
        if (e != null) {
            @SuppressWarnings("unchecked")
            T result = (T) e.value;
            return result;
        }
    }
    return setInitialValue();
}

Setting and removing values simply obtain the map and invoke set() or remove() on it.

Memory‑Leak Risks and Mitigation

If a ThreadLocal instance becomes unreachable (set to null) but its entry remains in a thread’s map, the key becomes null while the value stays referenced, causing a memory leak that persists until the thread terminates.

To mitigate this, ThreadLocalMap methods ( getEntry(), set(), remove()) actively clean up entries whose keys are null. Example from getEntry():

private Entry getEntry(ThreadLocal<?> key) {
    int i = key.threadLocalHashCode & (table.length - 1);
    Entry e = table[i];
    if (e != null && e.get() == key)
        return e;
    else
        return getEntryAfterMiss(key, i, e);
}

The map’s weak‑reference keys ensure that when a ThreadLocal is garbage‑collected, its entry can be removed during subsequent map operations. However, if a thread pool reuses threads and remove() is never called, stale entries can accumulate, leading to both memory leaks and logical errors.

Best practice: always call threadLocal.remove() after the thread‑local value is no longer needed, especially when using thread pools.

References

Stack Overflow: “Are Spring objects thread safe?”

Spring Framework Documentation on bean scopes

Java Concurrency in Practice – ThreadLocal design