Spring Application Events

Quick Start

// Custom Event (POJO - preferred)
public record OrderCreatedEvent(
    Long orderId,
    Long customerId,
    BigDecimal totalAmount,
    Instant createdAt
) {}

// Publisher
@Service
@RequiredArgsConstructor
public class OrderService {

    private final ApplicationEventPublisher eventPublisher;

    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        Order order = orderRepository.save(new Order(request));
        eventPublisher.publishEvent(new OrderCreatedEvent(
            order.getId(), order.getCustomerId(),
            order.getTotalAmount(), order.getCreatedAt()
        ));
        return order;
    }
}

// Listener
@Component
@Slf4j
public class OrderEventListener {

    @EventListener
    public void handleOrderCreated(OrderCreatedEvent event) {
        log.info("Order created: {}", event.orderId());
    }
}

@EventListener

@Component
public class EventListeners {

    // Basic listener
    @EventListener
    public void handleOrderCreated(OrderCreatedEvent event) {
        log.info("Processing order: {}", event.orderId());
    }

    // Conditional listener
    @EventListener(condition = "#event.totalAmount > 1000")
    public void handleLargeOrder(OrderCreatedEvent event) {
        notifyManager(event);
    }

    // Ordered execution
    @EventListener
    @Order(1)  // Executed first
    public void validateOrder(OrderCreatedEvent event) { }

    @EventListener
    @Order(2)  // Executed second
    public void processOrder(OrderCreatedEvent event) { }

    // Multiple event types
    @EventListener({OrderCreatedEvent.class, OrderUpdatedEvent.class})
    public void handleOrderChange(Object event) { }
}

Event Chain (Publish New Event from Listener)

@EventListener
public NotificationEvent handleOrderCreated(OrderCreatedEvent event) {
    return new NotificationEvent(event.customerId(), "Order created!");
}

@EventListener
public Collection<Object> handleOrderShipped(OrderShippedEvent event) {
    return List.of(
        new NotificationEvent(event.customerId(), "Order shipped!"),
        new AnalyticsEvent("order_shipped", event.orderId())
    );
}

Custom Events

// Generic event
public class EntityEvent<T> {
    private final T entity;
    private final EventType type;
    private final Instant timestamp = Instant.now();

    public enum EventType { CREATED, UPDATED, DELETED }
}

// Generic publisher
@Component
public class EntityEventPublisher {
    private final ApplicationEventPublisher publisher;

    public <T> void publishCreated(T entity) {
        publisher.publishEvent(new EntityEvent<>(entity, EventType.CREATED));
    }
}

// Typed listener
@EventListener
public void handleUserEvent(EntityEvent<User> event) {
    switch (event.getType()) {
        case CREATED -> handleUserCreated(event.getEntity());
        case UPDATED -> handleUserUpdated(event.getEntity());
    }
}

Full Reference: See transactional.md for @TransactionalEventListener, Async Events.

@TransactionalEventListener

// Execute AFTER transaction commit (default)
@TransactionalEventListener
public void handleAfterCommit(OrderCreatedEvent event) {
    emailService.sendOrderConfirmation(event.orderId());
}

// Execute AFTER rollback
@TransactionalEventListener(phase = TransactionPhase.AFTER_ROLLBACK)
public void handleAfterRollback(OrderCreatedEvent event) {
    alertService.notifyRollback(event);
}

// Execute BEFORE commit
@TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
public void handleBeforeCommit(OrderCreatedEvent event) {
    validateOrderBeforeCommit(event);
}

// Fallback if no transaction
@TransactionalEventListener(fallbackExecution = true)
public void handleWithFallback(OrderCreatedEvent event) { }

Full Reference: See patterns.md for Domain Events, Aggregate Root, Event Store.

Best Practices

✅ Use @TransactionalEventListener for side effects
✅ Use @Async for non-critical operations
✅ Implement retry for fallible listeners
✅ Use immutable events (records)
✅ Define order with @Order if needed
❌ Don't modify state in sync listeners
❌ Don't assume execution order without @Order

Production Checklist

[ ] Event classes immutabili
[ ] TransactionalEventListener for external calls
[ ] Async for non-critical operations
[ ] Error handling implemented
[ ] Retry for transient operations
[ ] Monitoring events

When NOT to Use This Skill

Distributed events - Use spring-kafka or spring-amqp
Guaranteed delivery - Use messaging systems
Event sourcing - Consider Axon Framework

Common Pitfalls

| Error | Cause | Solution | |-------|-------|----------| | Listener not executed | Missing @Component | Add annotation | | Event lost on rollback | Using @EventListener | Use @TransactionalEventListener | | Deadlock | Sync listener calls same service | Use @Async | | Exception hidden | Async void | Implement error handler |

Anti-Patterns

| Anti-Pattern | Problem | Solution | |--------------|---------|----------| | Sync events in transaction | Long transactions | Use @Async or @TransactionalEventListener | | Circular event publishing | Infinite loop | Guard with flags | | Heavy processing in sync | Blocks publisher | Use async listeners | | Modifying event after publish | Shared state issues | Make events immutable |

Quick Troubleshooting

| Problem | Diagnostic | Fix | |---------|------------|-----| | Listener not invoked | Check @EventListener | Verify component scanned | | Transaction not committed | Check event phase | Use AFTER_COMMIT | | Async not working | Check @EnableAsync | Add to config | | Order matters | Listeners random | Use @Order |

Reference Files

| File | Content | |------|---------| | transactional.md | @TransactionalEventListener, Async Events, Lifecycle | | patterns.md | Domain Events, Aggregate Root, Event Store |

spring-events