git clone -b grails8 https://github.com/grails-guides/grails-transactional-events.git
cd grails-transactional-events/complete
./gradlew integrationTest

curl -sL "https://start.grails.org/grails/grails-transactional-events.zip?type=web&javaVersion=21&grailsVersion=8.0.0" -o grails-transactional-events.zip
unzip grails-transactional-events.zip -d grails-transactional-events
cd grails-transactional-events

package example

import grails.persistence.Entity

@Entity
class Customer {

    String name
    String email
    BigDecimal lifetimeValue = BigDecimal.ZERO

    static constraints = {
        name          blank: false, maxSize: 255
        email         email: true, unique: true, maxSize: 255
        lifetimeValue min: BigDecimal.ZERO
    }

    static mapping = {
        lifetimeValue scale: 2, precision: 19
    }

    String toString() { name }
}

package example

import grails.persistence.Entity

@Entity
class Order {

    Customer customer
    BigDecimal total
    Date dateCreated

    static belongsTo = [customer: Customer]

    static constraints = {
        total min: new BigDecimal('0.01')
    }

    static mapping = {
        // 'order' is reserved in most SQL dialects
        table 'orders'
        total scale: 2, precision: 19
    }
}

package example

import grails.persistence.Entity

@Entity
class AuditLog {

    String eventType
    Long orderId
    Long customerId
    BigDecimal orderTotal
    Date occurredAt

    static constraints = {
        eventType  blank: false, maxSize: 64
        orderId    min: 1L
        customerId min: 1L
        orderTotal min: new BigDecimal('0.01')
        occurredAt nullable: false
    }

    static mapping = {
        orderTotal scale: 2, precision: 19
    }
}

package example.events

import groovy.transform.Immutable

/**
 * Domain event published by OrderService after an Order is persisted.
 *
 * No ApplicationEvent inheritance is required. Spring's
 * ApplicationEventPublisher.publishEvent(Object) overload wraps any
 * payload in a PayloadApplicationEvent transparently, so plain POGOs
 * are the recommended event type since Spring Framework 4.2.
 */
@Immutable
class OrderPlacedEvent {
    Long orderId
    Long customerId
    BigDecimal total
}

package example

import example.events.OrderPlacedEvent
import grails.gorm.transactions.Transactional
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.context.ApplicationEventPublisher

@Transactional
class OrderService {

    @Autowired
    ApplicationEventPublisher applicationEventPublisher

    Order placeOrder(Long customerId, BigDecimal total) {
        Customer customer = Customer.get(customerId)
        if (!customer) {
            throw new IllegalArgumentException("Unknown customer: ${customerId}")
        }

        Order order = new Order(customer: customer, total: total).save(failOnError: true)

        // Fire-and-forget from the publisher's point of view. Spring buffers
        // the event in the synchronization manager and dispatches it to
        // @TransactionalEventListener beans only after this method's
        // transaction commits.
        applicationEventPublisher.publishEvent(
                new OrderPlacedEvent(order.id, customer.id, total))

        order
    }
}

package example

import example.events.OrderPlacedEvent
import org.springframework.transaction.event.TransactionPhase
import org.springframework.transaction.event.TransactionalEventListener

/**
 * Updates Customer.lifetimeValue after an order commits.
 *
 * An ordinary Grails service: because the class name ends in 'Service', Grails
 * auto-registers it as a Spring bean, and Spring scans its
 * @TransactionalEventListener method - no manual wiring. It carries no
 * @Transactional of its own, so Grails applies no transactional proxy.
 *
 * The AFTER_COMMIT callback runs after the publisher's transaction has already
 * committed, so this method opens its OWN transaction for the GORM write via
 * withNewTransaction { }. Do not reach for @Transactional(REQUIRES_NEW) to make
 * that declarative: Grails' @Transactional is an AST transform that relocates
 * the method body and would hide @TransactionalEventListener from Spring's
 * scanner, so the listener would never fire.
 */
class CustomerLifetimeValueService {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onOrderPlaced(OrderPlacedEvent event) {
        Customer.withNewTransaction {
            Customer customer = Customer.get(event.customerId)
            if (customer) {
                customer.lifetimeValue = (customer.lifetimeValue ?: BigDecimal.ZERO) + event.total
                customer.save(flush: true, failOnError: true)
            }
        }
    }
}

package example

import example.events.OrderPlacedEvent
import org.springframework.transaction.event.TransactionPhase
import org.springframework.transaction.event.TransactionalEventListener

/**
 * Persists an AuditLog row for every committed order.
 *
 * A separate service - not a method on OrderService - keeps the "place an
 * order" concern decoupled from the "record audit history" concern. Adding
 * another committed-only side-effect later means a new service, not an edit to
 * OrderService.
 *
 * Like CustomerLifetimeValueService it is auto-registered by Grails (its name
 * ends in 'Service') and does its GORM write inside withNewTransaction { }
 * because the AFTER_COMMIT callback fires after the publisher's transaction
 * has committed.
 */
class AuditService {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onOrderPlaced(OrderPlacedEvent event) {
        AuditLog.withNewTransaction {
            new AuditLog(
                    eventType:  'ORDER_PLACED',
                    orderId:    event.orderId,
                    customerId: event.customerId,
                    orderTotal: event.total,
                    occurredAt: new Date()
            ).save(failOnError: true)
        }
    }
}

package example

import example.events.OrderPlacedEvent
import org.springframework.scheduling.annotation.Async
import org.springframework.transaction.event.TransactionPhase
import org.springframework.transaction.event.TransactionalEventListener

/**
 * Off-thread side-effect: stand-in for sending a confirmation email.
 *
 * An ordinary Grails service, auto-registered by name - which also means Grails
 * injects a `log` (SLF4J) property for free, so the class declares none of its
 * own. @Async dispatches the listener body to Spring's task executor instead of
 * running it on the caller's thread. The transaction-phase binding is still
 * synchronous - Spring waits for AFTER_COMMIT, then hands the event to the
 * executor. The body therefore has NO inherited transaction; if it needs the
 * database it must open its own via withNewTransaction { }.
 *
 * Exceptions thrown from an @Async listener are NOT propagated to the
 * publisher - see Spring's AsyncUncaughtExceptionHandler.
 *
 * @EnableAsync must be present on Application for @Async to take effect;
 * without it the annotation is silently a no-op.
 */
class NotificationService {

    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onOrderPlaced(OrderPlacedEvent event) {
        log.info('Off-thread: sending confirmation email for order {} (total {})',
                event.orderId, event.total)
        // Real implementation would call emailService.send(...)
    }
}

package example

import grails.boot.GrailsApp
import grails.boot.config.GrailsAutoConfiguration
import grails.plugins.metadata.PluginSource
import org.springframework.scheduling.annotation.EnableAsync

@PluginSource
@EnableAsync
class Application extends GrailsAutoConfiguration {
    static void main(String[] args) {
        GrailsApp.run(Application, args)
    }
}

package example

import grails.testing.mixin.integration.Integration
import spock.lang.Specification

/**
 * Integration spec that proves the two non-negotiable claims:
 *
 *   1. AFTER_COMMIT listeners fire when (and only when) the outer
 *      transaction commits.
 *   2. AFTER_COMMIT listeners are silently skipped when the outer
 *      transaction rolls back - no phantom audit rows, no phantom
 *      emails for orders that never durably existed.
 *
 * Each test method opens its own committed transaction via
 * Customer.withNewTransaction { ... } / Order.withNewTransaction { ... }
 * because @Rollback would also prevent the AFTER_COMMIT listeners from
 * firing, which would conflate "the listener never ran because rollback"
 * with "the listener never ran because @Rollback".
 */
@Integration
class OrderServiceIntegrationSpec extends Specification {

    OrderService orderService

    void "AFTER_COMMIT listeners run only after the outer transaction commits"() {
        given:
        Customer customer = createCommitted('Eve Lin', 'eve@example.com')
        long auditBefore = AuditLog.withNewTransaction { AuditLog.count() }
        BigDecimal lvBefore = Customer.withNewTransaction { Customer.get(customer.id).lifetimeValue }

        when: 'placeOrder runs inside a transaction that commits'
        Order placed = null
        Order.withNewTransaction {
            placed = orderService.placeOrder(customer.id, new BigDecimal('19.95'))
        }

        then: 'Both AFTER_COMMIT listeners fired'
        AuditLog.withNewTransaction { AuditLog.count() } == auditBefore + 1
        Customer.withNewTransaction { Customer.get(customer.id).lifetimeValue } == lvBefore + new BigDecimal('19.95')

        cleanup:
        deleteCommitted(placed, customer)
    }

    void "AFTER_COMMIT listeners are skipped when the outer transaction rolls back"() {
        given:
        Customer customer = createCommitted('Fay Park', 'fay@example.com')
        long auditBefore = AuditLog.withNewTransaction { AuditLog.count() }
        BigDecimal lvBefore = Customer.withNewTransaction { Customer.get(customer.id).lifetimeValue }

        when: 'placeOrder runs inside a transaction that explicitly rolls back'
        Order.withNewTransaction { status ->
            orderService.placeOrder(customer.id, new BigDecimal('999.00'))
            status.setRollbackOnly()
        }

        then: 'Neither AFTER_COMMIT listener fired'
        AuditLog.withNewTransaction { AuditLog.count() } == auditBefore
        Customer.withNewTransaction { Customer.get(customer.id).lifetimeValue } == lvBefore

        cleanup:
        deleteCommitted(null, customer)
    }

    void "placing two orders accumulates lifetime value and writes one audit row each"() {
        given:
        Customer customer = createCommitted('Gus Hall', 'gus@example.com')
        long auditBefore = AuditLog.withNewTransaction { AuditLog.count() }

        when: 'two orders are placed in separate committed transactions'
        Order first = null
        Order second = null
        Order.withNewTransaction { first = orderService.placeOrder(customer.id, new BigDecimal('10.00')) }
        Order.withNewTransaction { second = orderService.placeOrder(customer.id, new BigDecimal('5.50')) }

        then: 'both AFTER_COMMIT fan-outs ran: two audit rows and the summed lifetime value'
        AuditLog.withNewTransaction { AuditLog.count() } == auditBefore + 2
        Customer.withNewTransaction { Customer.get(customer.id).lifetimeValue } == new BigDecimal('15.50')

        cleanup:
        Order.withNewTransaction {
            AuditLog.where { orderId == first.id || orderId == second.id }.deleteAll()
            Order.get(first.id)?.delete()
            Order.get(second.id)?.delete()
            Customer.get(customer.id)?.delete(flush: true)
        }
    }

    private Customer createCommitted(String name, String email) {
        Customer created = null
        Customer.withNewTransaction {
            created = new Customer(name: name, email: email).save(flush: true, failOnError: true)
        }
        created
    }

    private void deleteCommitted(Order placed, Customer customer) {
        Order.withNewTransaction {
            if (placed) {
                AuditLog.where { orderId == placed.id }.deleteAll()
                Order.get(placed.id)?.delete(flush: true)
            }
            Customer.get(customer.id)?.delete(flush: true)
        }
    }
}

./gradlew integrationTest --tests example.OrderServiceIntegrationSpec

package example

/**
 * Lifecycle of a customer request. SUBMITTED is the entry state;
 * COMPLETED and CANCELLED are terminal. The only automated transition
 * this guide drives is SUBMITTED -> IN_PROGRESS, performed by the
 * synchronous orchestration listener when work is planned.
 */
enum CustomerRequestStatus {
    SUBMITTED,
    IN_PROGRESS,
    COMPLETED,
    CANCELLED

    boolean isTerminal() {
        this == COMPLETED || this == CANCELLED
    }
}

package example

/**
 * Lifecycle of a work order. A work order starts OPEN with no assignee.
 * Assigning an employee moves it to PLANNED; finishing the job moves it
 * to COMPLETED. This guide drives the OPEN -> PLANNED transition.
 */
enum WorkOrderStatus {
    OPEN,
    PLANNED,
    COMPLETED
}

package example

import grails.persistence.Entity

/**
 * A request raised by a customer. One CustomerRequest spawns one or more
 * WorkOrders. Its status is advanced by the orchestration listener as the
 * work underneath it progresses - never edited directly from a controller.
 */
@Entity
class CustomerRequest {

    String summary
    CustomerRequestStatus status = CustomerRequestStatus.SUBMITTED

    static constraints = {
        summary blank: false, maxSize: 255
        status  nullable: false
    }

    String toString() { summary }
}

package example

import grails.persistence.Entity

/**
 * A unit of work belonging to a CustomerRequest. Starts OPEN; moves to
 * PLANNED the moment an employee is assigned. The status change is driven
 * by the synchronous orchestration listener, inside the same transaction
 * that created the assignment.
 */
@Entity
class WorkOrder {

    CustomerRequest customerRequest
    String description
    WorkOrderStatus status = WorkOrderStatus.OPEN

    static belongsTo = [customerRequest: CustomerRequest]

    static constraints = {
        description blank: false, maxSize: 255
        status      nullable: false
    }

    static mapping = {
        // 'order' is reserved in most SQL dialects; the prefixed table name
        // sidesteps the same family of keyword collisions for work orders.
        table 'work_orders'
    }
}

package example

import grails.persistence.Entity

/**
 * Joins an employee to a WorkOrder. Creating one of these is the business
 * event that kicks off the whole orchestration: the assignment, the work
 * order's status change, and the customer request's status change all
 * commit together or not at all.
 */
@Entity
class WorkOrderAssignee {

    WorkOrder workOrder
    String employeeName
    Date dateCreated

    static belongsTo = [workOrder: WorkOrder]

    static constraints = {
        employeeName blank: false, maxSize: 255
    }
}

package example.events

import groovy.transform.Immutable

/**
 * Published by WorkOrderAssignmentService the moment a WorkOrderAssignee is
 * created. Unlike OrderPlacedEvent (consumed AFTER_COMMIT), this event is
 * consumed SYNCHRONOUSLY, inside the publisher's transaction, by a plain
 * @EventListener. It still carries IDs rather than entity references, but
 * the listener that handles it runs in the same Hibernate session, so a
 * WorkOrder.get(workOrderId) returns the live, in-flight instance.
 */
@Immutable
class EmployeeAssignedEvent {
    Long workOrderId
    Long assigneeId
    String employeeName
}

package example

import example.events.EmployeeAssignedEvent
import grails.gorm.transactions.Transactional
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.context.ApplicationEventPublisher

/**
 * Assigns an employee to a work order. The persistence work and the event
 * publish both happen inside one @Transactional method.
 *
 * Contrast with OrderService: there the listeners run AFTER this method
 * commits, in their own transactions. Here the event is consumed by a plain
 * @EventListener, which Spring dispatches SYNCHRONOUSLY at the publishEvent
 * call - on this thread, inside this transaction, before this method returns.
 * So the assignee insert, plus every change the listener makes, are one
 * atomic unit: they all commit together or all roll back together.
 */
@Transactional
class WorkOrderAssignmentService {

    @Autowired
    ApplicationEventPublisher applicationEventPublisher

    WorkOrderAssignee assignEmployee(Long workOrderId, String employeeName) {
        WorkOrder workOrder = WorkOrder.get(workOrderId)
        if (!workOrder) {
            throw new IllegalArgumentException("Unknown work order: ${workOrderId}")
        }

        WorkOrderAssignee assignee = new WorkOrderAssignee(
                workOrder: workOrder, employeeName: employeeName)
                .save(failOnError: true)

        // Synchronous dispatch: the @EventListener for this event runs inline,
        // right here, inside this transaction and Hibernate session. If it
        // throws, the exception propagates back through this call and rolls
        // the whole method - including the assignee insert above - back.
        applicationEventPublisher.publishEvent(
                new EmployeeAssignedEvent(workOrder.id, assignee.id, employeeName))

        assignee
    }
}

package example

import example.events.EmployeeAssignedEvent
import org.springframework.context.event.EventListener

/**
 * Synchronous, in-transaction orchestration.
 *
 * A plain @EventListener (NOT @TransactionalEventListener) runs inline on the
 * publisher's thread, inside the publisher's transaction and Hibernate session:
 * reads see in-flight state, writes join the same commit, and a thrown
 * exception rolls the whole operation back.
 *
 * It is an ordinary Grails service (auto-registered by name) but deliberately
 * carries NO @Transactional: Grails' @Transactional is a compile-time AST
 * transform that relocates the method body and would hide @EventListener from
 * Spring's scanner, so the listener would never register. It needs no
 * transaction of its own anyway - it runs inside the one the publisher started.
 */
class WorkOrderPlanningService {

    @EventListener
    void onEmployeeAssigned(EmployeeAssignedEvent event) {
        WorkOrder workOrder = WorkOrder.get(event.workOrderId)

        // An assigned work order is ready to be planned.
        if (workOrder.status == WorkOrderStatus.OPEN) {
            workOrder.status = WorkOrderStatus.PLANNED
            workOrder.save(failOnError: true)
        }

        // Planning work means the originating request is now in progress.
        // This read sees the WorkOrder transition made one statement ago,
        // because both run in the same transaction.
        CustomerRequest request = workOrder.customerRequest
        if (request.status.terminal) {
            throw new IllegalStateException(
                    "Cannot start work on request ${request.id}: it is ${request.status}")
        }
        if (request.status == CustomerRequestStatus.SUBMITTED) {
            request.status = CustomerRequestStatus.IN_PROGRESS
            request.save(failOnError: true)
        }
    }
}

package example

import grails.testing.mixin.integration.Integration
import spock.lang.Specification

/**
 * Integration spec that proves the same-transaction orchestration is atomic:
 *
 *   1. On success, the assignment, the WorkOrder status, and the
 *      CustomerRequest status all commit together.
 *   2. On a failure raised mid-orchestration (the listener rejecting an
 *      illegal request transition), EVERY change rolls back - no assignee
 *      row, the WorkOrder is still OPEN, the CustomerRequest is untouched.
 *
 * As in OrderServiceIntegrationSpec, each method drives its own committed
 * transactions via withNewTransaction { ... } and asserts in fresh
 * transactions, so the assertions read committed database state rather than
 * mutated first-level-cache instances.
 */
@Integration
class WorkOrderAssignmentIntegrationSpec extends Specification {

    WorkOrderAssignmentService workOrderAssignmentService

    void "assigning an employee atomically plans the work order and advances the request"() {
        given:
        Long[] ids = createScenario(CustomerRequestStatus.SUBMITTED)
        Long requestId = ids[0]
        Long workOrderId = ids[1]

        when: 'an employee is assigned inside a transaction that commits'
        WorkOrderAssignee assignee = null
        WorkOrder.withNewTransaction {
            assignee = workOrderAssignmentService.assignEmployee(workOrderId, 'Dana Reed')
        }

        then: 'all three changes committed as one unit'
        assignee.id != null
        WorkOrder.withNewTransaction { WorkOrder.get(workOrderId).status } == WorkOrderStatus.PLANNED
        CustomerRequest.withNewTransaction { CustomerRequest.get(requestId).status } == CustomerRequestStatus.IN_PROGRESS

        cleanup:
        deleteScenario(workOrderId, requestId)
    }

    void "a failure mid-orchestration rolls every change back"() {
        given: 'a work order whose customer request is already closed'
        Long[] ids = createScenario(CustomerRequestStatus.COMPLETED)
        Long requestId = ids[0]
        Long workOrderId = ids[1]
        long assigneesBefore = countAssignees(workOrderId)

        when: 'assigning an employee triggers an illegal request transition'
        WorkOrder.withNewTransaction {
            workOrderAssignmentService.assignEmployee(workOrderId, 'Dana Reed')
        }

        then: 'the orchestration threw'
        thrown(IllegalStateException)

        and: 'nothing persisted - no assignee, both statuses unchanged'
        countAssignees(workOrderId) == assigneesBefore
        WorkOrder.withNewTransaction { WorkOrder.get(workOrderId).status } == WorkOrderStatus.OPEN
        CustomerRequest.withNewTransaction { CustomerRequest.get(requestId).status } == CustomerRequestStatus.COMPLETED

        cleanup:
        deleteScenario(workOrderId, requestId)
    }

    void "assigning a second employee to an already-planned work order does not re-run the cascade"() {
        given: 'a work order already planned by a first assignment'
        Long[] ids = createScenario(CustomerRequestStatus.SUBMITTED)
        Long requestId = ids[0]
        Long workOrderId = ids[1]
        WorkOrder.withNewTransaction {
            workOrderAssignmentService.assignEmployee(workOrderId, 'Dana Reed')
        }

        when: 'a second employee is assigned'
        WorkOrder.withNewTransaction {
            workOrderAssignmentService.assignEmployee(workOrderId, 'Sam Ortiz')
        }

        then: 'both assignees exist, but the OPEN/SUBMITTED guards make the status changes a no-op'
        countAssignees(workOrderId) == 2
        WorkOrder.withNewTransaction { WorkOrder.get(workOrderId).status } == WorkOrderStatus.PLANNED
        CustomerRequest.withNewTransaction { CustomerRequest.get(requestId).status } == CustomerRequestStatus.IN_PROGRESS

        cleanup:
        deleteScenario(workOrderId, requestId)
    }

    void "a cancelled request also blocks the assignment and rolls everything back"() {
        given:
        Long[] ids = createScenario(CustomerRequestStatus.CANCELLED)
        Long requestId = ids[0]
        Long workOrderId = ids[1]
        long assigneesBefore = countAssignees(workOrderId)

        when:
        WorkOrder.withNewTransaction {
            workOrderAssignmentService.assignEmployee(workOrderId, 'Dana Reed')
        }

        then:
        thrown(IllegalStateException)

        and:
        countAssignees(workOrderId) == assigneesBefore
        WorkOrder.withNewTransaction { WorkOrder.get(workOrderId).status } == WorkOrderStatus.OPEN
        CustomerRequest.withNewTransaction { CustomerRequest.get(requestId).status } == CustomerRequestStatus.CANCELLED

        cleanup:
        deleteScenario(workOrderId, requestId)
    }

    private Long[] createScenario(CustomerRequestStatus requestStatus) {
        Long requestId = null
        Long workOrderId = null
        CustomerRequest.withNewTransaction {
            CustomerRequest request = new CustomerRequest(
                    summary: 'Replace the rooftop HVAC unit', status: requestStatus)
                    .save(flush: true, failOnError: true)
            WorkOrder workOrder = new WorkOrder(
                    customerRequest: request, description: 'Site survey and install')
                    .save(flush: true, failOnError: true)
            requestId = request.id
            workOrderId = workOrder.id
        }
        [requestId, workOrderId] as Long[]
    }

    private long countAssignees(Long workOrderId) {
        WorkOrderAssignee.withNewTransaction {
            WorkOrderAssignee.where { workOrder.id == workOrderId }.count()
        }
    }

    private void deleteScenario(Long workOrderId, Long requestId) {
        WorkOrder.withNewTransaction {
            WorkOrder workOrder = WorkOrder.get(workOrderId)
            if (workOrder) {
                WorkOrderAssignee.findAllByWorkOrder(workOrder)*.delete()
                workOrder.delete(flush: true)
            }
            CustomerRequest.get(requestId)?.delete(flush: true)
        }
    }
}

./gradlew integrationTest --tests example.WorkOrderAssignmentIntegrationSpec