Multi-Member entity event routing: docs, tests, and @EventTag recipe - #4998
Open
MateuszNaKodach wants to merge 3 commits into
Open
Multi-Member entity event routing: docs, tests, and @EventTag recipe#4998MateuszNaKodach wants to merge 3 commits into
MateuszNaKodach wants to merge 3 commits into
Conversation
The multi-entity migration guide claimed the default for delivering events to child entities is equivalent to ForwardAll. That holds only for a single child declared without a routingKey. With a routingKey (required for collections) the default RoutingKeyEventTargetMatcherDefinition routes by matching the routingKey, and a child event is silently skipped when it does not carry a matching value, a common cause of a child @EventSourcingHandler not firing after migration. Correct the "Event forwarding mode" section to state the actual conditional default, and add a troubleshooting note covering the two gates an event must pass: it must be sourced into the parent (every event, parent-level and child-level, must carry the parent tagKey) and then routed to the child. Add AxonTestFixture tests for the behaviour: - EntityMemberMessageRoutingTest: single and collection routing, the fail-fast on a collection without a routingKey, and a broadcast matcher. - ChildEntityEventTaggingTest: a child event only reaches the child when it carries the parent tag, independent of routing. - UuidChildEntityEventSourcingTest: the same with UUID identifiers. - SpringEventSourcedChildEntityTest: the Spring @eventsourced stereotype with a UUID id registers the child hierarchy and honours the tagging gate.
AddEventTagAnnotation only scanned root entity classes (@aggregate, @eventsourced, @EventSourcedEntity), so events handled by an @AggregateMember/@EntityMember child never received an @eventtag. After migration those child events were not sourced into the parent stream and the child @EventSourcingHandler never ran. Extend the scan to collect the events used by every class and to follow @AggregateMember/@EntityMember fields (including List and Map elements) from a parent to its child type. Child events are reconciled into the tag targets with the parent's identifier field name and tag key, so they are tagged with the parent's tag and sourced into the parent stream, mirroring the single stream an Axon Framework 4 aggregate shared with its members. The existing exact-name match, first-field fallback, and TODO(axon4to5) comment are reused for ambiguous cases.
MateuszNaKodach
requested review from
hatzlj,
jangalinski and
zambrovski
and removed request for
a team
September 2, 2026 08:42
MateuszNaKodach
changed the title
MateuszNaKodach
changed the title
MateuszNaKodach
added
Priority 2: Should
The documentation site lint (Vale rule AxonIQ.Headings, sentence-style for h2-h6) flags the component titles of the message-handler-customization and meta-annotations guides. Those titles render as an h3 in the navigation on every page, so title-style capitalization fails the check and breaks the docs build. Lowercase the non-initial words in the antora.yml titles; the page H1 titles keep title-style capitalization for the AxonIQ.HeadingTitle (h1) rule. These were pre-existing site-wide lint errors surfaced by the shared Vale package, unrelated to the child-entity changes, but the docs check runs on this branch because it also touches docs, so they must be fixed for CI to pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corrects the multi-entity migration guide, which wrongly claimed the Axon Framework 5 default for delivering events to child entities is equivalent to
ForwardAll; it is routing-key based (only a single child without aroutingKeygets every event), and a troubleshooting note now explains the two gates an event must pass: it must be sourced into the parent (every event, parent-level and child-level, must carry the parenttagKey) and then routed to the child. Extends theAddEventTagAnnotationOpenRewrite recipe to follow@AggregateMember/@EntityMemberfields (includingList/Mapelements) and tag child events with the parent's tag, so a migrated child@EventSourcingHandleris actually sourced instead of silently skipped. AddsAxonTestFixturetests covering single and collection routing, the fail-fast on a collection without aroutingKey, a broadcast matcher, the tagging/sourcing gate, UUID identifiers, and the Spring@EventSourcedstereotype, plus a recipe test for the member-tagging behaviour.