Two years ago, my friend José Paumard held the talk "Concurrent and Asynchronous Programming: Loom" at the Geneva Java User Group. In his talk, he mentioned that the Spring team would need to completely redesign their approach to transaction: his reasoning was that the transactions are implemented on top of ThreadLocal object and Loom's virtual threads break this approach. ThreadLocal I was intrigued because, though I used Spring transactions a lot via the @Transactional annotation, I never thought about looking at their implementation. It made sense because of how you would propagate the context, but I wanted to make sure. In this post, I'd like to share my findings. @Transactional Finding Usage of ThreadLocal ThreadLocal The hardest part of the research was to find the usage itself. I started with doing a search for ThreadLocal on the GitHub Spring projects organizations. It returns a list of 364 different files. If you limit the results to the spring-framework project, it shrinks down to 78 files. I had had enough and asked ChatGPT: a search ThreadLocal limit the results spring-framework Find if Spring transactions uses ThreadLocal. If yes, tell me how and points to sources to prove your claims.
Yes, Spring transactions use ThreadLocal as part of their transaction management mechanism. Here's an explanation of how it works: Find if Spring transactions uses ThreadLocal. If yes, tell me how and points to sources to prove your claims. Yes, Spring transactions use ThreadLocal as part of their transaction management mechanism. Here's an explanation of how it works: Spring transactions ThreadLocal How Spring Transactions Use ThreadLocal

TransactionSynchronizationManager:

Spring’s transaction management uses the TransactionSynchronizationManager class to manage resources such as connections and transaction synchronizations. This class relies on ThreadLocal to store transaction context, ensuring it is bound to the current thread.

Thread-bound Transaction Context:

The TransactionSynchronizationManager maintains a ThreadLocal to hold information about:

The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback).


By binding this context to the current thread, Spring ensures that a transaction initiated in one part of the code can be propagated and recognized elsewhere on the same thread.


PlatformTransactionManager:

When you use PlatformTransactionManager to start a transaction (e.g., with @Transactional), it checks the current thread’s context for any existing transaction using TransactionSynchronizationManager.


Propagation Behavior:

The propagation behaviors (REQUIRED, REQUIRES_NEW, etc.) rely on the ThreadLocal context to determine whether to join an existing transaction or start a new one. How Spring Transactions Use ThreadLocal How Spring Transactions Use ThreadLocal TransactionSynchronizationManager: TransactionSynchronizationManager: TransactionSynchronizationManager Spring’s transaction management uses the TransactionSynchronizationManager class to manage resources such as connections and transaction synchronizations. This class relies on ThreadLocal to store transaction context, ensuring it is bound to the current thread. TransactionSynchronizationManager ThreadLocal Thread-bound Transaction Context:

The TransactionSynchronizationManager maintains a ThreadLocal to hold information about:

The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback).


By binding this context to the current thread, Spring ensures that a transaction initiated in one part of the code can be propagated and recognized elsewhere on the same thread.


PlatformTransactionManager:

When you use PlatformTransactionManager to start a transaction (e.g., with @Transactional), it checks the current thread’s context for any existing transaction using TransactionSynchronizationManager.


Propagation Behavior: Thread-bound Transaction Context:

The TransactionSynchronizationManager maintains a ThreadLocal to hold information about:

The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback).


By binding this context to the current thread, Spring ensures that a transaction initiated in one part of the code can be propagated and recognized elsewhere on the same thread. Thread-bound Transaction Context The TransactionSynchronizationManager maintains a ThreadLocal to hold information about:

The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback).


By binding this context to the current thread, Spring ensures that a transaction initiated in one part of the code can be propagated and recognized elsewhere on the same thread. The TransactionSynchronizationManager maintains a ThreadLocal to hold information about:

The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback). TransactionSynchronizationManager ThreadLocal The currently active transaction.
Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions).
Transaction synchronizations (callbacks that execute before/after commit/rollback). The currently active transaction. Resources associated with the transaction (e.g., JDBC connections, Hibernate sessions). Transaction synchronizations (callbacks that execute before/after commit/rollback). By binding this context to the current thread, Spring ensures that a transaction initiated in one part of the code can be propagated and recognized elsewhere on the same thread. PlatformTransactionManager:

When you use PlatformTransactionManager to start a transaction (e.g., with @Transactional), it checks the current thread’s context for any existing transaction using TransactionSynchronizationManager. PlatformTransactionManager When you use PlatformTransactionManager to start a transaction (e.g., with @Transactional), it checks the current thread’s context for any existing transaction using TransactionSynchronizationManager. When you use PlatformTransactionManager to start a transaction (e.g., with @Transactional), it checks the current thread’s context for any existing transaction using TransactionSynchronizationManager. PlatformTransactionManager @Transactional TransactionSynchronizationManager Propagation Behavior: Propagation Behavior The propagation behaviors (REQUIRED, REQUIRES_NEW, etc.) rely on the ThreadLocal context to determine whether to join an existing transaction or start a new one. REQUIRED REQUIRES_NEW ThreadLocal Indeed, the magic happens in the TransactionSynchronizationManager. TransactionSynchronizationManager Note: In the above search results, it appears on the second page, and doesn't give an inkling that it's the answer. ChatGPT was a great help! The TransactionSynchronizationManager Class TransactionSynchronizationManager Its Javadoc is pretty descriptive: Central delegate that manages resources and transaction synchronizations per thread. To be used by resource management code but not by typical application code.
Supports one resource per key without overwriting, that is, a resource needs to be removed before a new one can be set for the same key. Supports a list of transaction synchronizations if synchronization is active.
Resource management code should check for thread-bound resources, for example, JDBC Connections or Hibernate Sessions, via getResource. Such code is normally not supposed to bind resources to threads, as this is the responsibility of transaction managers. A further option is to lazily bind on first use if transaction synchronization is active, for performing transactions that span an arbitrary number of resources.
Transaction synchronization must be activated and deactivated by a transaction manager via initSynchronization() and clearSynchronization(). This is automatically supported by AbstractPlatformTransactionManager, and thus by all standard Spring transaction managers, such as JtaTransactionManager and DataSourceTransactionManager.
Resource management code should only register synchronizations when this manager is active, which can be checked via isSynchronizationActive(); it should perform immediate resource cleanup else. If transaction synchronization isn't active, there is either no current transaction, or the transaction manager doesn't support transaction synchronization.
Synchronization is for example used to always return the same resources within a JTA transaction, for example, a JDBC Connection or a Hibernate Session for any given DataSource or SessionFactory, respectively.
-- Class TransactionSynchronizationManager Javadoc Central delegate that manages resources and transaction synchronizations per thread. To be used by resource management code but not by typical application code. Supports one resource per key without overwriting, that is, a resource needs to be removed before a new one can be set for the same key. Supports a list of transaction synchronizations if synchronization is active. Resource management code should check for thread-bound resources, for example, JDBC Connections or Hibernate Sessions, via getResource. Such code is normally not supposed to bind resources to threads, as this is the responsibility of transaction managers. A further option is to lazily bind on first use if transaction synchronization is active, for performing transactions that span an arbitrary number of resources. Transaction synchronization must be activated and deactivated by a transaction manager via initSynchronization() and clearSynchronization(). This is automatically supported by AbstractPlatformTransactionManager, and thus by all standard Spring transaction managers, such as JtaTransactionManager and DataSourceTransactionManager. initSynchronization() clearSynchronization() AbstractPlatformTransactionManager JtaTransactionManager DataSourceTransactionManager Resource management code should only register synchronizations when this manager is active, which can be checked via isSynchronizationActive(); it should perform immediate resource cleanup else. If transaction synchronization isn't active, there is either no current transaction, or the transaction manager doesn't support transaction synchronization. isSynchronizationActive() Synchronization is for example used to always return the same resources within a JTA transaction, for example, a JDBC Connection or a Hibernate Session for any given DataSource or SessionFactory, respectively. -- Class TransactionSynchronizationManager Javadoc Class TransactionSynchronizationManager Javadoc In this regard, TransactionSynchronizationManager acts as a global variable. TransactionSynchronizationManager Let's have a look at a simplified sequence diagram. How Transactions Use TransactionSynchronizationManager TransactionSynchronizationManager I'll use the DataSourceTransactionManager, but other Spring-provided transaction managers behave in a similar way. DataSourceTransactionManager During startup, Spring searches for all @Transactional-annotated methods. For each of them, it creates a proxy (either a JDK one or a CGLIB one), which wraps the real method with pre- and post-code. @Transactional The sequence starts when you call a @Transactional-annotated method
The proxy object gets the transaction from the concrete transaction manager, via a couple of classes, which I didn't represent. If it doesn't find it, it starts a new one.
The manager binds the resource, i.e., stores a key-value pair: in this case, the key is the data source, the value is the ConnectionHolder
Initializes the synchronization set, i.e., resets the synchronizations set to a new set
Removes the synchronization from the ThreadLocal
Removes the data source key from the resources map The sequence starts when you call a @Transactional-annotated method @Transactional The proxy object gets the transaction from the concrete transaction manager, via a couple of classes, which I didn't represent. If it doesn't find it, it starts a new one. The manager binds the resource, i.e., stores a key-value pair: in this case, the key is the data source, the value is the ConnectionHolder i.e. ConnectionHolder Initializes the synchronization set, i.e., resets the synchronizations set to a new set i.e. synchronizations Removes the synchronization from the ThreadLocal ThreadLocal Removes the data source key from the resources map resources What About Reactive Transaction Management? In Reactive Programming, tasks are executed asynchronously across multiple threads to maximize resource utilization. Since ThreadLocal ties data to a specific thread, Spring can't use it reliably in reactive environments. Instead, Spring’s reactive transaction management uses a Context object associated with the reactive stream. Still, Spring designers kept the same class name-quite confusing. ThreadLocal Context Notice that the TransactionSynchronizationManager methods are instance-scoped in the Reactive context, while they were class-scoped (static) in the regular one. TransactionSynchronizationManager static It's harder to create a UML sequence diagram for reactive transaction management flow because: I'm much less familiar with the Reactive paradigm
The code itself is more complex
Method chaining and Mono are harder to represent in a sequence diagram I'm much less familiar with the Reactive paradigm The code itself is more complex Method chaining and Mono are harder to represent in a sequence diagram Mono In any case, Spring doesn't store the reactive context in a ThreadLocal but associates it in the Mono or Flux object. Spring propagates the context along with each signal. Note that such a context is immutable, e.g, updating the context creates a new instance. ThreadLocal Mono Flux such a context is immutable e.g Here's a quick comparison chart of how Spring passes the transaction context in regular vs. reactive paradigms. Aspect

Blocking Transactions

Reactive Transactions



Resource Binding

ThreadLocal

Reactive Context



Thread Dependence

Tied to a single thread

Propagates across threads



Immutability

Mutable

Context is immutable Aspect

Blocking Transactions

Reactive Transactions



Resource Binding

ThreadLocal

Reactive Context



Thread Dependence

Tied to a single thread

Propagates across threads



Immutability

Mutable

Context is immutable Aspect

Blocking Transactions

Reactive Transactions Aspect Aspect Blocking Transactions Blocking Transactions Reactive Transactions Reactive Transactions Resource Binding

ThreadLocal

Reactive Context Resource Binding Resource Binding ThreadLocal ThreadLocal ThreadLocal Reactive Context Reactive Context Context Thread Dependence

Tied to a single thread

Propagates across threads Thread Dependence Thread Dependence Tied to a single thread Tied to a single thread Propagates across threads Propagates across threads Immutability

Mutable

Context is immutable Immutability Immutability Mutable Mutable Context is immutable Context is immutable Context Discussion Spring's Reactive API isn't bound to a thread. Migrating the API to virtual threads isn't an issue because it offers the Context object to pass data across threads. However, the regular API offers no such commodity: Spring takes care of it using the ThreadLocal approach. Context ThreadLocal The Spring team faces two issues: Decide how to pass context in the regular context: either by continuing the "magic" or making it explicit, with potentially breaking changes
Support both threading approaches within the same code base; some will continue using regular threads while others will migrate to virtual threads Decide how to pass context in the regular context: either by continuing the "magic" or making it explicit, with potentially breaking changes Support both threading approaches within the same code base; some will continue using regular threads while others will migrate to virtual threads You can already see the beginning of such work in the VirtualThreadTaskExecutor introduced in Spring 6.1. VirtualThreadTaskExecutor To go further: To go further: A deep dive on Java Spring framework transactional annotation
AbstractPlatformTransactionManager.java
DataSourceTransactionManager.java
"All together now: Spring Boot 3.2, GraalVM native images, Java 21, and virtual threads with Project Loom"
Working with Virtual Threads in Spring A deep dive on Java Spring framework transactional annotation A deep dive on Java Spring framework transactional annotation AbstractPlatformTransactionManager.java AbstractPlatformTransactionManager.java DataSourceTransactionManager.java DataSourceTransactionManager.java "All together now: Spring Boot 3.2, GraalVM native images, Java 21, and virtual threads with Project Loom" "All together now: Spring Boot 3.2, GraalVM native images, Java 21, and virtual threads with Project Loom" Working with Virtual Threads in Spring Working with Virtual Threads in Spring Originally published at A Java Geek on October 5th, 2025 Originally published at A Java Geek on October 5th, 2025 A Java Geek

GitHub

Privacy for Subdomains: Here's What You Should Be Focusing On

My Findings Regarding Transactions and ThreadLocal in Spring: What I've Discovered

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

16 Best Practices For Securing Your APIs with Apache APISIX - Part 1

Java bits: 0xFF and 0xFFL

The Noonification: Charting a Path for Global AI Regulation (11/14/2023)

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

16 Best Practices For Securing Your APIs with Apache APISIX - Part 1

Java bits: 0xFF and 0xFFL

The Noonification: Charting a Path for Global AI Regulation (11/14/2023)

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps