[#4991] Rework `SagaLifecycle` to resolvable parameter by smcvb · Pull Request #4997 · AxonIQ/AxonFramework

smcvb · 2026-09-02T07:25:03Z

This pull request reworks the SagaLifecycle to be a resolvable parameter instead of a statically invoked infrastructure component.

This is required, as the old approach used the ThreadLocal logic of the previous UnitOfWork to access the Saga, which is no longer an option with AF5.
Instead, it's something that's injected, the ProcessingContext.

Hence, this can be seen as one of the few breaking changes for users moving towards axon-legacy in 5.4.0, which is sadly mandatory.
To limit the break, the package of the SagaLifecycle is the same as well as the name.

The main difference for users is two-fold:

It no longer has any static methods.
It is injected as a parameter i.o. (statically) imported.

From a technical stance, the only SagaLifecycle implementation was the AnnotatedSaga.
Hence, this PR also pulls in that class, immediately adjusting it to be an EventHandlingComponent instead of an EventHandlerInvoker.

This portion has a large scoped outcome on this PR, as it had to pull in:

The Saga interface, as it's used by the AnnotatedSaga.
The @StartSaga, @SagaEventHandler and @EndSaga annotations, as we're dealing with the AnnotatedSaga
The SagaMethodMessageHandlerDefinition to be able to wire the @SagaEventHandler correctly
The AssociationResolver plus its implementations, as those are used by the SagaEventHandler and SagaMethodMessageHandlerDefinition alike
The SagaCreationPolicy, as it's by the SagaMethodMessageHandlerDefinition
The SagaModel and it's creation, as those are used by the AnnotatedSaga

Note that this PR does not fully implement all the EventHandlingComponent operations yet!
This PR is already bigger than I wanted, so I decided against doing that part here as well.
Expect a follow-up PR instead.

In doing the above, this PR resolves #4991.

Rough sketch to port the SagaLifecycle. Do so by adjusting the SagaLifecycle by not having static methods, but plain methods. Furthermore, let the Saga be an implementation of the SagaLifecycle. From there, we should add the SagaLifecycle to the ProcessingContext when handling a SagaEventHandler in the (Annotated)Saga. To wire the SagaLifecycle, users can simply add a parameter for it with their SagaEventHandler. Lastly, move other annotation-specific components from the stash to this project, as those are utilized by the annotation solution (in)directly. #4991

…placement

Remove the files that were now moved to axon-legacy #4991

Move applicable tests and StartSaga #4991

Expand api-changes #4991

MateuszNaKodach

A few nits, generally good job. Thanks for the PR! :)
I think we should wait with merging that till featsaga-store merge.

MateuszNaKodach · 2026-09-02T11:29:38Z

+    // TODO
+    // TODO


What are those TODO about? I thinks supportsReset returning false is appropriate here.

Whoops, totally right. This is a leftover that I missed to fix. Adjusted it, by overriding the supportsReset to return false.
Added, I defaulted the handle(ResetContext, ProcessingContext) method here as well, throwing the throw new ResetNotSupportedException("Sagas do not support reset"); exception from the AF4-version of that method.

MateuszNaKodach · 2026-09-02T11:44:16Z

+    private final AssociationValues associationValues;
+    private final String sagaId;
+    private final T sagaInstance;
+    private volatile boolean isActive = true;


Is saga always accessed by single thread? I believe the LockingSagaRepository needs to care about that, am I right?

Yep, correct! The LockingSagaRepository will take care of that :-)

MateuszNaKodach · 2026-09-02T11:49:41Z

+ * This is the {@link ProcessingContext}-scoped replacement for the Axon Framework 4 {@code SagaLifecycle}, which
+ * exposed the very same operations as {@code static} methods resolved through a {@code ThreadLocal}. Axon Framework


Since it's a replacement should it be since 5.4.0, or earlier version?
Regardless, I think the name "SagaLifecycle" is nice, just use instance methods instead of the static ones :)

I added a quick doc-draft as the old version had practically no JavaDoc...I've fine-tuned it a little right now.
I've also marked it as since 3.0.0, as that's the accurate since tag.

MateuszNaKodach · 2026-09-02T11:51:39Z

+
+    @Override
+    public Set<QualifiedName> supportedEvents() {
+        throw new UnsupportedOperationException("TODO");


I'd place TODOs here with the issue number.

Good point, will do!

MateuszNaKodach · 2026-09-02T11:52:26Z

+ * @author Steven van Beelen
+ * @since 5.4.0
+ */
+public class SagaLifecycleParameterResolverFactory implements ParameterResolverFactory {


I don't see tests for that.

Good point, will add!

MateuszNaKodach · 2026-09-02T11:54:16Z

+            testSubject.handle(matchingEvent, StubProcessingContext.forMessage(matchingEvent)).asCompletableFuture().join();
+            var nonMatchingEvent = new GenericEventMessage(new MessageType("event"), new RegularEvent("wrongId"));
+            testSubject.handle(nonMatchingEvent, StubProcessingContext.forMessage(nonMatchingEvent)).asCompletableFuture().join();
+            var unhandledEvent = new GenericEventMessage(new MessageType("event"), new Object());
+            testSubject.handle(unhandledEvent, StubProcessingContext.forMessage(unhandledEvent)).asCompletableFuture().join();


You have a few join() without timeouts here.

Good point, will do!

Add deprecation warning to StartSaga annotaion #4991

Remove accidental TODO #4991

Correct reset support on Saga interface #4991

Improve JavaDoc #4991

Added issue numbers to todo #4991

Add tests for the SagaLifecycleParameterResolverFactory #4991

Ensure joins have a timeout #4991

smcvb added 2 commits September 2, 2026 09:00

Merge branch 'featsaga-store' into enhancement/4991/saga-lifecycle-re…

d277ce7

…placement

smcvb added this to the Release 5.4.0 milestone Sep 2, 2026

smcvb self-assigned this Sep 2, 2026

smcvb added Type: Feature Use to signal an issue is completely new to the project. Priority 1: Must Highest priority. A release cannot be made if this issue isn’t resolved. labels Sep 2, 2026

smcvb added 2 commits September 2, 2026 10:23

Remove the files that were now moved to axon-legacy

1e07aa6

Remove the files that were now moved to axon-legacy #4991

Move applicable tests and StartSaga

b56d0e5

Move applicable tests and StartSaga #4991

smcvb marked this pull request as ready for review September 2, 2026 08:57

smcvb requested a review from a team as a code owner September 2, 2026 08:57

smcvb requested review from MateuszNaKodach, jangalinski and zambrovski and removed request for a team September 2, 2026 08:57

Expand api-changes

aa541e7

Expand api-changes #4991

MateuszNaKodach approved these changes Sep 2, 2026

View reviewed changes

smcvb added 2 commits September 2, 2026 15:20

Add deprecation warning to StartSaga annotaion

3f68ac0

Add deprecation warning to StartSaga annotaion #4991

Remove accidental TODO

cef1da2

Remove accidental TODO #4991

Base automatically changed from featsaga-store to main September 3, 2026 08:47

smcvb added 5 commits September 3, 2026 11:42

Correct reset support on Saga interface

c36fa68

Correct reset support on Saga interface #4991

Improve JavaDoc

839c3dd

Improve JavaDoc #4991

Added issue numbers to todo

eb54ffd

Added issue numbers to todo #4991

Add tests for the SagaLifecycleParameterResolverFactory

b023be8

Add tests for the SagaLifecycleParameterResolverFactory #4991

Ensure joins have a timeout

1ab6190

Ensure joins have a timeout #4991

MateuszNaKodach merged commit b7b562d into main Sep 3, 2026
6 checks passed

MateuszNaKodach deleted the enhancement/4991/saga-lifecycle-replacement branch September 3, 2026 10:25

MateuszNaKodach mentioned this pull request Sep 3, 2026

[#3728] Port the Axon Framework 4 saga repositories into axon-legacy #5009

Open

		* This is the {@link ProcessingContext}-scoped replacement for the Axon Framework 4 {@code SagaLifecycle}, which
		* exposed the very same operations as {@code static} methods resolved through a {@code ThreadLocal}. Axon Framework

Uh oh!

Conversation

smcvb commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MateuszNaKodach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

smcvb commented Sep 2, 2026 •

edited

Loading

MateuszNaKodach left a comment •

edited

Loading