Ankur Mhatre
585eed4d57
The repository now aggregates two independent modules. migration-behavior/ is the
original project, moved unchanged; it stays on Spring Boot 4.0.6 / JDK 21 because
that is what the four published migration articles were verified against, and
upgrading it would silently invalidate output they quote. The article-tagged trees
are untouched, so links into a tag are unaffected.
transactions/ Companion code for "@Transactional in Spring: Propagation, Isolation,
and the Six Ways It Silently Does Nothing". Spring Boot 4.1.1 / JDK 25.
Every row of the propagation matrix is produced by calling the method and asking the
transaction manager what it did. The transaction NAME is the exhibit: a scope that
joined reports its caller's name, a scope that started its own reports its own.
Three things the transcripts settle:
- Propagation.NESTED cannot be used with JpaTransactionManager. It fails twice,
with two different messages, the second of which blames your JPA provider. The
savepoint manager comes from the object the JpaDialect returns when it begins the
transaction, and Hibernate's does not implement one. It works on
DataSourceTransactionManager, because a savepoint is a JDBC concept -- shown
working there rather than only failing here.
- Catching a REQUIRED inner failure does not save the transaction. The inner scope
has already marked it rollback-only, so the commit throws
UnexpectedRollbackException from a place with no connection to the cause.
- A checked exception commits, and so does a swallowed one. Those two do not merely
fail to start a transaction; they commit work the code was abandoning.
19 contract tests, six captured transcripts, all regenerated by scripts/run-all.sh.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gip4srpzMwjgoba6uEfbr5
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
[Index](../README.md) · [Propagation →](02-propagation.md)
|
|
|
|
# 1. What `@Transactional` actually does
|
|
|
|
`@Transactional` is an AOP proxy. That single fact predicts every failure in
|
|
[chapter 5](05-six-silent-failures.md), and it is the same mechanism as
|
|
[Spring AOP](../../../spring-boot-demo/spring-aop) generally.
|
|
|
|
When a method carrying the annotation is called **through the proxy**, an interceptor:
|
|
|
|
1. asks the `PlatformTransactionManager` for a transaction, according to the propagation rule;
|
|
2. invokes the target method;
|
|
3. on a normal return, commits;
|
|
4. on a `RuntimeException` or `Error`, rolls back;
|
|
5. on a checked `Exception`, **commits** and rethrows.
|
|
|
|
Step 5 is not a typo. See [chapter 5](05-six-silent-failures.md).
|
|
|
|
## Logical versus physical
|
|
|
|
The distinction that makes propagation comprehensible:
|
|
|
|
- A **logical transaction** is one `@Transactional` scope — one annotated method call.
|
|
- A **physical transaction** is one real database transaction with one connection, one
|
|
`BEGIN` and one `COMMIT`.
|
|
|
|
`REQUIRED` maps many logical scopes onto one physical transaction. `REQUIRES_NEW` gives each
|
|
scope its own. Everything else is a variation on that theme.
|
|
|
|
## Seeing which is which
|
|
|
|
`TransactionSynchronizationManager` is public API and answers this anywhere in application
|
|
code:
|
|
|
|
```java
|
|
TransactionSynchronizationManager.isActualTransactionActive(); // is there a PHYSICAL one?
|
|
TransactionSynchronizationManager.getCurrentTransactionName(); // whose scope started it?
|
|
TransactionSynchronizationManager.isCurrentTransactionReadOnly();
|
|
TransactionSynchronizationManager.getCurrentTransactionIsolationLevel();
|
|
```
|
|
|
|
The transaction *name* is the most useful and least known of these. A method that joined its
|
|
caller's transaction reports the **caller's** name; a method that started its own reports its
|
|
own. That one string distinguishes joining from starting without reading any documentation.
|
|
|
|
## The log to turn on
|
|
|
|
```yaml
|
|
logging.level.org.springframework.orm.jpa.JpaTransactionManager: DEBUG
|
|
logging.level.org.springframework.transaction.interceptor: TRACE
|
|
```
|
|
|
|
which narrates the whole thing in the transaction manager's own words:
|
|
|
|
```
|
|
Creating new transaction with name [...OuterService.serializableScope]:
|
|
PROPAGATION_REQUIRED,ISOLATION_SERIALIZABLE
|
|
Participating in existing transaction
|
|
Initiating transaction commit
|
|
```
|
|
|
|
`Creating new transaction` versus `Participating in existing transaction` is the answer to most
|
|
questions people ask about propagation.
|
|
|
|
## Method visibility
|
|
|
|
`@Transactional` works on `public` methods, and since Spring 6.0 also on `protected` and
|
|
package-private ones **when the proxy is class-based** (which is Spring Boot's default). It
|
|
never works on `private` methods, and with interface-based proxies the method must be public
|
|
and declared on the interface.
|