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
67 lines
3.4 KiB
Markdown
67 lines
3.4 KiB
Markdown
[← What @Transactional does](01-what-transactional-does.md) · [Index](../README.md) · [Rollback →](03-rollback.md)
|
|
|
|
# 2. The seven propagation values
|
|
|
|
Transcript: [`01-propagation.txt`](output/01-propagation.txt). Every row was produced by calling
|
|
the method, not by reading the enum.
|
|
|
|
| Propagation | Caller has a transaction | Caller has none |
|
|
|---|---|---|
|
|
| `REQUIRED` (default) | joins it | starts one |
|
|
| `REQUIRES_NEW` | suspends it, starts its own | starts one |
|
|
| `NESTED` | savepoint — **fails on JPA**, see [chapter 4](04-nested-and-jpa.md) | starts one |
|
|
| `SUPPORTS` | joins it | runs with **no** transaction |
|
|
| `NOT_SUPPORTED` | **suspends** it, runs with none | runs with none |
|
|
| `MANDATORY` | joins it | `IllegalTransactionStateException` |
|
|
| `NEVER` | `IllegalTransactionStateException` | runs with none |
|
|
|
|
## The measured version
|
|
|
|
```
|
|
PROPAGATION CALLER ACTIVE TRANSACTION NAME / OUTCOME
|
|
----------------------------------------------------------------------------
|
|
REQUIRED inside @Transactional True inTransaction
|
|
REQUIRED no transaction True required
|
|
REQUIRES_NEW inside @Transactional True requiresNew
|
|
NESTED inside @Transactional -- NestedTransactionNotSupportedException
|
|
SUPPORTS inside @Transactional True inTransaction
|
|
SUPPORTS no transaction False supports
|
|
NOT_SUPPORTED inside @Transactional False notSupported
|
|
MANDATORY no transaction -- IllegalTransactionStateException
|
|
NEVER inside @Transactional -- IllegalTransactionStateException
|
|
```
|
|
|
|
Read the **name** column. `REQUIRED` inside a transaction reports `inTransaction` — the
|
|
caller's method — because it joined. `REQUIRES_NEW` reports `requiresNew` — its own — because
|
|
it started a second physical transaction.
|
|
|
|
## Notes that matter in practice
|
|
|
|
**`SUPPORTS` with no transaction is not "no writes".** The method still runs and still writes;
|
|
the write just lands on an auto-commit connection with no rollback available. `SUPPORTS` is for
|
|
read paths that do not care, and it is a poor default for anything that mutates.
|
|
|
|
**`NOT_SUPPORTED` suspends, it does not merely decline.** The caller's transaction is set aside
|
|
and restored afterwards. Suspension holds the outer connection open while the inner work runs.
|
|
|
|
**`REQUIRES_NEW` needs two connections at once.** The outer transaction keeps its connection
|
|
while the inner one takes another. A pool sized to the number of request threads will deadlock
|
|
under load — size it to exceed concurrent threads by at least one, per request nesting level.
|
|
|
|
**`MANDATORY` is an assertion.** Use it on a helper that must never be called outside a
|
|
transaction; it turns a silent correctness bug into a startup-visible exception.
|
|
|
|
**`NEVER` is rare** and usually means the work should be somewhere else entirely.
|
|
|
|
## Exact messages
|
|
|
|
```
|
|
NESTED NestedTransactionNotSupportedException:
|
|
Transaction manager does not allow nested transactions by default -
|
|
specify 'nestedTransactionAllowed' property with value 'true'
|
|
MANDATORY IllegalTransactionStateException:
|
|
No existing transaction found for transaction marked with propagation 'mandatory'
|
|
NEVER IllegalTransactionStateException:
|
|
Existing transaction found for transaction marked with propagation 'never'
|
|
```
|