How do you register a TransactionSynchronization, what must be true for registration to succeed, how is invocation order among multiple synchronizations decided, and how does @TransactionalEventListener build on this?

## Registering a synchronization ```java TransactionSynchronizationManager.registerSynchronization(mySync); ``` `TransactionSynchronizationManager` is a thread-local coordinator. `registerSynchronization` adds your `TransactionSynchronization` to the current transaction's set. ## Precondition: synchronization must be active The call only works when a Spring-managed transaction with **active synchronization** exists on the thread. Otherwise it throws `IllegalStateException: Transaction synchronization is not active`. In practice this means you must be inside a `@Transactional` method (or a programmatic `TransactionTemplate`). To register conditionally and avoid the exception when there might be no transaction: ```java if (TransactionSynchronizationManager.isSynchronizationActive()) { TransactionSynchronizationManager.registerSynchronization(mySync); } else { // no transaction: run inline, or skip, or throw a clearer error } ``` Note: an *active transaction* and *active synchronization* are subtly different — a `PlatformTransactionManager` normally initializes synchronization, but exotic configs can have a transaction without synchronization. `isSynchronizationActive()` is the correct guard for registration. ## Ordering among multiple synchronizations `TransactionSynchronization` extends `Ordered` (via `Ordered`/`OrderComparator`) with `getOrder()` defaulting to `Ordered.LOWEST_PRECEDENCE`. When Spring drives a phase (say, all `afterCommit` calls), it retrieves the synchronizations **sorted by order** (`OrderComparator.sort`), so **lower `getOrder()` runs first**. Every registered synchronization completes its `beforeCommit` before any `afterCommit` runs — ordering applies *within* each phase, not across phases. Override `getOrder()` when you need deterministic sequencing between independent synchronizations (e.g., publish-to-broker must run before metrics). ## How @TransactionalEventListener builds on this `@TransactionalEventListener` is the ergonomic, event-driven front end: ```java @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT) public void on(OrderPlaced e) { publisher.publish(e); } ``` Mechanism: when you `applicationEventPublisher.publishEvent(new OrderPlaced(...))` inside a transaction, Spring's `TransactionalApplicationListenerMethodAdapter` registers an internal `TransactionSynchronization` on the current transaction. At the configured phase it invokes your method: - `BEFORE_COMMIT` → `beforeCommit` - `AFTER_COMMIT` (default) → `afterCommit` - `AFTER_ROLLBACK` → `afterCompletion` filtered to rolled-back - `AFTER_COMPLETION` → `afterCompletion` **No active transaction?** By default the event listener simply does **not** fire (the event is effectively dropped for the transactional listener). Set `fallbackExecution = true` to run it immediately in that case. You can also order these listeners with `@Order`. ## When to use which - Ad-hoc, low-level, or infrastructure hooks (resource cleanup, custom ordering, direct access to status) → implement `TransactionSynchronization` and register it. - Domain 'do X after commit' semantics with decoupling → publish an event + `@TransactionalEventListener`. It's the same underlying mechanism, but declarative and testable. ## Common gotchas - Registering outside a transaction → `IllegalStateException`; guard with `isSynchronizationActive()`. - Expecting cross-phase ordering from `getOrder()` — it only orders within a phase. - Forgetting that an `AFTER_COMMIT` event listener silently does nothing if there is no surrounding transaction (unless `fallbackExecution`).