jEAP Messaging outbox
jEAP Messaging outbox is an implementation of the Transactional outbox pattern for jEAP Spring Boot services. It lets a service change persistent data and publish Kafka messages within a single database transaction: messages are stored in an outbox table together with the business data in the same transaction, and are only relayed to Kafka after the transaction commits. If the transaction rolls back, the messages are never sent. This gives reliable, at-least-once message delivery without distributed transactions (XA / 2PC), even when Kafka is temporarily unavailable.
It complements jeap-messaging: messages are still strongly-typed Avro events and commands, contracts are still enforced, and signing, encryption and tracing carry over.
- Atomic "save data + queue message" in one local DB transaction
- Two delivery modes: send immediately after commit, or hand off to a scheduled background relay
- Background message relay with ShedLock-based locking for safe multi-instance operation
- Failed-message handling (query, mark for resend) for messages that fail for message-specific reasons
- Configurable housekeeping with separate retention for sent and unsent messages
- Multi-cluster support and Micrometer metrics for operational monitoring
Documentation
Start with Getting started, then follow the links below.
| Topic | File |
|---|---|
| Getting started (add the dependency, send a message) | docs/getting-started.md |
| Architecture & the relay flow | docs/architecture.md |
Sending messages (TransactionalOutbox API, delivery modes) | docs/sending-messages.md |
| Database schema & migrations | docs/database.md |
| Failure handling & failed-message operations | docs/failure-handling.md |
| Housekeeping & retention | docs/housekeeping.md |
| Metrics | docs/metrics.md |
| Multi-cluster support | docs/multi-cluster.md |
Configuration reference (jeap.messaging.transactional-outbox.*) | docs/configuration.md |
Modules
Group id for all modules is ch.admin.bit.jeap; the version is managed by the jEAP Spring Boot parent.
| Module | Purpose |
|---|---|
jeap-messaging-outbox | The outbox implementation; the artifact consumers depend on |
jeap-messaging-outbox-test | Internal integration-test module (embedded Kafka, H2, Flyway); not a consumer API |