Module events and the outbox
Listening to another module
Fire events with a CDI jakarta.enterprise.event.Event. Listen with @ApplicationModuleListener:
public class InventoryListener {
@ApplicationModuleListener
void on(OrderPlaced event) {
// ...
}
}
A listener method declares exactly one parameter, the event. Its class becomes a @Singleton bean if it has no scope. A listener receives events of its parameter type and every subtype, through one CDI observer per listened type that the build registers. Nothing observes the other events of the application, so request and transaction lifecycle events cost nothing.
A listener of java.lang.Object receives every event fired without a qualifier (an injected Event<X> without qualifiers counts as @Default). It never receives qualified events, such as the container’s @Initialized and @Destroyed lifecycle events. Prefer a listener of the narrowest type: an Object listener is called for every unqualified event of the application.
Delivery works like Spring Modulith’s @ApplicationModuleListener, which combines @Async, @Transactional(REQUIRES_NEW) and @TransactionalEventListener(AFTER_COMMIT):
-
when the event is fired inside a transaction, listeners run after the commit, and never if the transaction rolls back or is marked for rollback,
-
when there is no transaction, listeners run right away,
-
listeners run on the listener executor, unless
@ApplicationModuleListener(async = false), -
each listener runs in a new transaction when
quarkus-narayana-jtais present, with the request context active, -
an exception in a listener is logged (event type, listener id and publication id; the event itself only at
DEBUG) and does not reach the publisher.
Events fired on a Vert.x event loop without a transaction (a reactive route, a Vert.x handler) are handed to the listener executor first, so storing publications and synchronous listeners never block the I/O thread. Firing inside a JTA transaction already implies a worker thread.
The dispatcher calls listeners through ArC invokers generated at build time, and a generated bean creates them, so there is no reflection.
Attributes
| Attribute | Meaning |
|---|---|
|
The listener identifier stored with every publication. The default is Spring’s: |
|
|
|
Only events for which the condition holds reach the listener, and only those are stored. See below. |
|
|
|
With |
@ApplicationModuleListener can be used as a meta-annotation, at any depth:
@ApplicationModuleListener(async = false)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface SynchronousListener {
}
Conditions
Spring Modulith evaluates SpEL. Quarkus Modulith compiles the conditions Spring users write into bytecode at build time, and fails the build for anything else, so a typo never turns into a silently skipped listener:
-
the event:
event,event,#root.event,#root.args[0],args[0],#a0,#p0orand the parameter name, -
property paths (
#event.customer.vip, read throughgetVip(),isVip()or a record accessorvip()) and methods without parameters (#event.isUrgent()), -
number, string (
'EUR'or"EUR"), boolean andnullliterals, -
== != < ⇐ > >=andeq ne lt le gt ge,&& || !andand or not, and parentheses.
Numbers compare by value whatever their type, and an enum equals the string of its name: #event.state == 'OPEN'. and and or short-circuit, so #event.customer != null and #event.customer.vip is safe.
A listener bean can also implement io.quarkiverse.modulith.events.ConditionalEventListener and decide in supports(Object event). Both checks run before the publication is stored.
Executor and shutdown
| Property | Meaning |
|---|---|
|
|
|
At shutdown the dispatcher stops taking deliveries and waits this long (default |
|
|
The event publication registry
Without a registry, an event whose listener fails, or that is lost because the application stops before the listener runs, is gone. Add a store, quarkus-modulith-events-jpa for Hibernate ORM, and every delivery goes through the outbox, with Spring Modulith’s lifecycle:
-
When the event is fired, one publication per listener is stored with status
PUBLISHED, in the publishing transaction. If that transaction rolls back, the publications go with it. -
Right before the listener runs, the publication becomes
PROCESSINGand counts one more completion attempt, in a short transaction of its own. A publication that is completed or gone by then is not delivered. -
When the listener succeeds, the publication is
COMPLETED, then updated, deleted or archived depending on the completion mode. -
When it fails, the publication becomes
FAILED. -
Submitting a publication again first claims it with one conditional update to
RESUBMITTED, which only succeeds while the publication isPUBLISHEDorFAILED. A publication another instance claimed or is delivering cannot be claimed, so several instances can share a table without delivering a publication twice through resubmission. A claimed or processing publication whose last publication date (the last resubmission, or else the publication) is older thanquarkus.modulith.events.staleness.processing, or else.resubmitted, or elserepublish-older-than(default5m), is taken over, so a delivery whose instance died (killed, out of memory, redeployed) is delivered again, also with the default configuration. The trade-off: a delivery that is still running after that age, for example a listener slower thanrepublish-older-than, is taken over too and delivered twice, so delivery is at least once (see Delivery guarantees). Setquarkus.modulith.events.staleness.processingabove the duration of the slowest listener. This is stricter than Spring Modulith 2.1.2, whose claim only excludesRESUBMITTED. -
A resubmission that cannot hand the publication to its listener, because the event cannot be read or the dispatcher refuses it, logs a warning and marks the publication
FAILEDwith one more attempt, soabandon-after-attemptseventually applies to it. -
Listeners that another component delivers, such as the outbox drain of event externalization, are left out of every resubmission: they declare themselves through a
ResubmissionExclusionbean.
Completion attempts count deliveries. Spring Modulith 2.1.2 counts differently: one when the publication is stored and one per resubmission, none when processing. Rows a Spring application wrote keep their count after a migration, so abandon-after-attempts may see one attempt more for them.
Submitting publications again
Inject the API beans:
| Bean | Methods |
|---|---|
|
|
|
|
|
|
|
|
Every resubmission and deletion reads the store page by page (quarkus.modulith.events.republish-batch-size, default 100, at least 1), in the database, and deserializes an event only when a filter or the listener needs it. A publication whose listener no longer exists is marked FAILED, as in Spring Modulith.
Jobs
| Property | Meaning |
|---|---|
|
Resubmits the incomplete publications after startup, in the background, without delaying readiness: every |
|
Resubmits incomplete publications older than |
|
Deletes completed publications older than |
|
Marks publications that stayed longer than the threshold in that status |
The periodic jobs are registered with the programmatic scheduler API and skip a run while the previous one is still going. The first failure of a job is logged at ERROR, the following ones at DEBUG until it succeeds again. They need quarkus-scheduler, which stays optional. The scheduler is only started when the build sees a job interval or a staleness threshold, so set them in application.properties (they can still be changed at runtime); a job configured only at runtime, or without quarkus-scheduler, logs a warning and does not run. At shutdown the registry lists the publications left unfinished (event type and listener only).
Completion modes
quarkus.modulith.events.completion-mode (build, readable at runtime): update (default) sets the completion date and keeps the row, delete removes it, archive moves it to event_publication_archive, where every query about completed publications looks. The JPA store maps the archive entity in archive mode only. In archive mode, CompletedEventPublications.deletePublications(Predicate) deletes the matching archived publications and returns how many it deleted. This differs from Spring Modulith 2.1.2 on purpose: there, deleting by identifier only touches the publication table, so the call deletes nothing in archive mode.
CDI transactional observers
With a store present, CDI observers of the application notified after a successful commit, void on(@Observes(during = TransactionPhase.AFTER_SUCCESS) OrderPlaced event), are delivered by the dispatcher too, the way Spring Modulith’s registry covers every @TransactionalEventListener: their deliveries are stored, completed and resubmitted. They keep their timing (synchronously, right after the commit, without transaction) and get Spring’s default listener id. quarkus.modulith.events.registry-trigger-annotation (build) restricts this to observer methods carrying the given annotation. Only observers declared in the application archive with the event as their only parameter and no qualifier are routed: observers of libraries, qualified observers and observers with injected parameters keep their plain CDI delivery. Observers with notifyObserver = Reception.IF_EXISTS are not routed either, since their bean may not exist when the dispatcher delivers. A routed observer method must be a non-private instance method, otherwise the build fails and names the method.
Clock and serialization
Publication dates come from the application’s java.time.Clock bean when there is one, else from the UTC system clock.
Events are written as JSON by the EventSerializer bean of quarkus-modulith-events, which uses the application’s Jackson mapper: Jackson 2 on Quarkus 3, Jackson 3 on Quarkus 4. Declare a bean of that type to replace it. Like Spring Modulith, the stored format follows the application mapper’s settings (naming strategy, unknown properties, dates), so changing them changes what new rows contain and what old rows must still match. Keep the mapper settings stable, or provide a dedicated EventSerializer. A store that keeps text uses toString() on the serialized form.
Every listened event type is registered for reflection in native executables with its whole type graph and every known subtype, since the registry stores the concrete class. For a listener of a JDK type, such as Object or Serializable, only the subtypes in the application are registered, with a build warning; annotate other event types with @RegisterForReflection.
The JPA store
quarkus-modulith-events-jpa keeps publications in the event_publication table with Spring Modulith’s columns and status values, so an application moving from Spring Modulith keeps its table: the shop integration tests let Spring Modulith 2.1.2 write a publication, and Quarkus Modulith read, resubmit and complete it.
| Property | Meaning |
|---|---|
|
The persistence unit of the outbox tables, |
CREATE TABLE event_publication (
id UUID NOT NULL PRIMARY KEY,
listener_id VARCHAR(512) NOT NULL,
event_type VARCHAR(512) NOT NULL,
serialized_event TEXT NOT NULL,
publication_date TIMESTAMP WITH TIME ZONE NOT NULL,
completion_date TIMESTAMP WITH TIME ZONE,
status VARCHAR(32),
completion_attempts INT,
last_resubmission_date TIMESTAMP WITH TIME ZONE
);
CREATE INDEX event_publication_by_completion_date_idx ON event_publication (completion_date);
CREATE INDEX event_publication_by_listener_idx
ON event_publication (completion_date, listener_id, publication_date, id);
The first index is Spring Modulith’s. The second, which a schema generated by Hibernate gets as well, serves the queries every resubmission page and outbox run makes: the incomplete publications of one listener in publication order. Add it to a table that Spring Modulith or a migration tool created.
Every query is portable HQL. A publication date bound at or after 9999-12-30 is no bound, so "every publication" never meets the timestamp range of the database. An event published inside a read-only listener transaction, whose session does not flush by itself, is flushed right away, so its deliveries find it after the commit. The repository and the read-only transactions are default beans (@DefaultBean on Quarkus 3, @Reserve on Quarkus 4): an application’s own EventPublicationRepository or ReadOnlyTransactions bean replaces them. Looking up the incomplete publication of an equal event compares the stored text in Java, page by page over the listener’s publications, so it also works where long text cannot be compared in SQL (Oracle CLOB). The tests run on H2, PostgreSQL and MySQL; the repository contract also runs on PostgreSQL 18 from Dev Services.
event_publication_archive has the same columns. Rows without status, written by older Spring Modulith versions, read as COMPLETED when they have a completion date and as FAILED otherwise, so the failed-publication resubmission picks them up, as in Spring Modulith 2.1.2 and the other stores.
Delivery guarantees
Delivery is at least once. A listener can see an event twice after a crash between its side effects outside the database and the completion, after a staleness check marked a slow delivery failed and it was resubmitted, or when a delivery runs longer than the takeover age (staleness.processing, or else republish-older-than) and a resubmission takes it over. Make listeners idempotent.
Claims are single conditional updates. When the database reports a concurrent claim as a serialization failure (SQLState 40001, PostgreSQL at REPEATABLE READ or SERIALIZABLE, MySQL deadlocks), the claim counts as lost to the other instance, not as a failure. The two-instance tests run on PostgreSQL 17 and MySQL 8.4.
Configuration reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Whether events are externalized when a transport is present, for example Environment variable: |
boolean |
|
How events reach the broker: Environment variable: |
|
|
What happens to a publication once its listener succeeded: Environment variable: |
|
|
When set, only CDI observers notified Environment variable: |
string |
|
Whether to submit all incomplete publications again when the application starts. The resubmission runs in the background after startup, in batches. With several instances of the application, prefer Environment variable: |
boolean |
|
How often to submit incomplete publications again. Disabled when not set. Needs Environment variable: |
||
Only publications older than this are submitted again by the periodic job, so that deliveries still in flight are left alone. Without Environment variable: |
|
|
How many publications a resubmission reads from the store at once. Must be positive. Environment variable: |
int |
|
How often to delete completed publications. Disabled when not set. Needs Environment variable: |
||
Completed publications whose completion is older than this are deleted by the periodic job. Environment variable: |
|
|
After how long a Environment variable: |
||
After how long a Environment variable: |
||
After how long a Environment variable: |
||
How often to look for stale publications. Must be positive. Needs Environment variable: |
|
|
Publications with at least this many completion attempts are abandoned: they are no longer resubmitted and are listed by Environment variable: |
int |
|
Whether the default externalization configuration sends events one at a time, so that the broker sees them in the order they were published. Like Spring Modulith’s Environment variable: |
boolean |
|
When externalization is serialized, how long one send may wait for the broker’s acknowledgement. A send that takes longer fails, and the next event is sent, so that a broker that never answers cannot stop externalization. Environment variable: |
|
|
How often the job looks for publications to send, in addition to running after every transaction that recorded events. Publications that failed are sent again on the next run. Environment variable: |
|
|
How long to wait for the broker to acknowledge a message before the publication counts as failed and the run stops, so that later events do not overtake it. Environment variable: |
|
|
How long, on top of Environment variable: |
|
|
How many publications a run reads at once. Must be at least 1. Environment variable: |
int |
|
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
The persistence unit holding the event publication tables. The publishing transaction must use the same datasource for the outbox guarantee to hold. Environment variable: |
string |