What does @Externalized do in Spring Modulith, and how does externalizing events to a broker relate to the Event Publication Registry?

## The idea So far events are **in-process**: publisher and `@ApplicationModuleListener` live in the same JVM. **`@Externalized`** (from `org.springframework.modulith.events`) says: *this event should also leave the process and be published to a message broker*, so external systems/services can consume it. This is the bridge from 'modular monolith' toward 'event-driven services' — the same publisher code, now heard outside. ## Enabling it Add a broker integration module, e.g.: - `spring-modulith-events-kafka` - `spring-modulith-events-amqp` (RabbitMQ) - `spring-modulith-events-jms` - cloud variants (AWS SQS/SNS/Kinesis, etc.) With an integration on the classpath, Modulith's externalization support activates and looks for events to externalize. ## Selecting what gets externalized Two ways: 1. **Annotation:** put `@Externalized` on the event type. 2. **Programmatic:** define an `EventExternalizationConfiguration` bean to select events (by package/type), route them, and map/transform the payload — useful when you don't want broker annotations polluting domain events. ## The `target::key` routing syntax The `@Externalized` value is a string of the form **`target::key`**: - **target** — the destination name. For Kafka that's the **topic**; for AMQP an exchange/routing target, etc. - **`::key`** — optional. Everything after `::` is a **SpEL expression evaluated against the event instance**, producing the **routing/message key** (e.g. Kafka message key used for partitioning/ordering). ```java @Externalized("orders::#{#this.orderId()}") public record OrderCompleted(String orderId, long total) {} ``` Here every `OrderCompleted` is sent to the `orders` topic with the message key set to the order id, so all events for one order land on the same partition (per-key ordering). With no `::key`, only the target is used and the broker assigns partitioning. ## Relationship to the Event Publication Registry — the key point Externalization is **not** fire-and-forget over the network. It's wired through the **same Event Publication Registry**: 1. When the transaction commits, an **incomplete publication** is recorded for the externalization 'listener'. 2. Modulith attempts the **broker send**. 3. On a successful send, the publication is **completed**. 4. If the broker is **down** or the send fails, the publication stays **incomplete** and is subject to the normal recovery paths (republish-on-restart, `IncompleteEventPublications` resubmit). This is the **transactional outbox extended across the process boundary**: the event is durably stored with the business data in one transaction, then relayed to the broker with **at-least-once** semantics. It solves the classic dual-write problem (DB commit + broker publish can't be atomic) — you never publish to the broker without having committed, and you never permanently lose a publish because the broker was briefly unavailable. ## Consequences to reason about (principal level) - **At-least-once to the broker** → downstream consumers must dedupe/idempotent-consume; the routing key helps with per-key ordering but not exactly-once. - **Payload contract & schema evolution** become an inter-service concern now, not just internal — version your externalized event schemas carefully (consumers you don't control). - **Serialization/mapping:** you may externalize a different DTO than the internal event via the externalization configuration, decoupling internal model from wire contract. - **Ordering:** only guaranteed per key/partition, and replays can reorder — design consumers accordingly. - **Migration strategy:** you can start with in-process `@ApplicationModuleListener`s and later add `@Externalized` to the same events, gradually extracting a module into its own service — publishers don't change. ## When to use Reach for `@Externalized` when a consumer must live outside the JVM (another service, an analytics pipeline, a different team's system), or when you're deliberately carving a module toward independent deployment — while keeping the durability guarantees the registry already gives you internally.