Address PR #444 review feedback

schananas · schananas · commit 22da021e3e54 · 2026-05-11T13:29:36.000+02:00
- Bump axon-workflow dependency from 1.0.0-SNAPSHOT to released 0.1.0 in both demo poms; drop the central-portal-snapshots repository block now that the engine is on Maven Central. Fixes the red CI job. - Rename "Axon Workflow Engine" to "Axoniq Workflow Engine" across the remaining poms, READMEs, and inline comments. - Drop the now-obsolete "build the workflow engine locally first" snippet from order-fulfillment-workflow/README.md and update the Prerequisites version to 0.1.0. - Rebalance the workflow-saga README's comparison section: rename "What got simpler" to "Comparison: @saga vs @workflow", add a framing paragraph that this is a trade-off, and add explicit "Where @workflow reads more naturally" and "Where @saga reads more naturally" subsections that acknowledge the single ~70-line execute() method and the value of per-handler decomposition. - OrderEventStream: replace the manual HashMap.put chain in the OrderPlaced handler with ObjectMapper.convertValue(event, ...) plus the two extra "type"/"timestamp" entries. Uses the Jackson 3 ObjectMapper (tools.jackson.databind) autoconfigured by Spring Boot 4.
diff --git a/order-fulfillment-workflow/README.md b/order-fulfillment-workflow/README.md
@@ -37,15 +37,7 @@ public void execute(SimpleWorkflowContext ctx) {
 - Java 21+
 - Maven 3.9+
 - Docker (for Axon Server)
-- The Axon Workflow Engine (`io.axoniq.framework.workflow:*:1.0.0-SNAPSHOT`) installed in the local Maven repository
-
-If the workflow engine isn't published yet, build it locally first:
-
-```bash
-git clone git@github.com:AxonIQ/extension-workflow.git
-cd extension-workflow
-mvn clean install -DskipTests
-```
+- The Axoniq Workflow Engine (`io.axoniq.framework.workflow:*:0.1.0`), available on Maven Central
 
 ## Running the application
 
diff --git a/order-fulfillment-workflow/pom.xml b/order-fulfillment-workflow/pom.xml
@@ -8,7 +8,7 @@
     <artifactId>order-fulfillment-workflow</artifactId>
     <version>0.0.1-SNAPSHOT</version>
     <name>Order Fulfillment Workflow</name>
-    <description>Sample showing how to model an Order Fulfillment process with the Axon Workflow Engine.</description>
+    <description>Sample showing how to model an Order Fulfillment process with the Axoniq Workflow Engine.</description>
 
     <properties>
         <java.version>21</java.version>
@@ -18,7 +18,7 @@
 
         <axon.version>5.1.0</axon.version>
         <axoniq-framework.version>5.1.0</axoniq-framework.version>
-        <axon-workflow.version>1.0.0-SNAPSHOT</axon-workflow.version>
+        <axon-workflow.version>0.1.0</axon-workflow.version>
         <spring-boot.version>4.0.6</spring-boot.version>
         <testcontainers.version>2.0.5</testcontainers.version>
     </properties>
@@ -57,7 +57,7 @@
     </dependencyManagement>
 
     <dependencies>
-        <!-- Axon Workflow Engine: auto-configures @Workflow beans through Spring Boot. -->
+        <!-- Axoniq Workflow Engine: auto-configures @Workflow beans through Spring Boot. -->
         <dependency>
             <groupId>io.axoniq.framework.workflow</groupId>
             <artifactId>axon-workflow-spring-boot</artifactId>
@@ -170,18 +170,4 @@
             </plugin>
         </plugins>
     </build>
-
-    <repositories>
-        <repository>
-            <id>central-portal-snapshots</id>
-            <name>Central Portal Snapshots</name>
-            <url>https://central.sonatype.com/repository/maven-snapshots/</url>
-            <releases>
-                <enabled>false</enabled>
-            </releases>
-            <snapshots>
-                <enabled>true</enabled>
-            </snapshots>
-        </repository>
-    </repositories>
 </project>
diff --git a/order-fulfillment-workflow/src/main/java/io/axoniq/demo/orderfulfillment/projection/OrderEventStream.java b/order-fulfillment-workflow/src/main/java/io/axoniq/demo/orderfulfillment/projection/OrderEventStream.java
@@ -1,5 +1,7 @@
 package io.axoniq.demo.orderfulfillment.projection;
 
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
 import io.axoniq.demo.orderfulfillment.api.InitiatingPaymentForCustomerStarted;
 import io.axoniq.demo.orderfulfillment.api.OrderDelivered;
 import io.axoniq.demo.orderfulfillment.api.OrderFailed;
@@ -14,7 +16,6 @@
 
 import java.io.IOException;
 import java.time.Instant;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CopyOnWriteArrayList;
@@ -31,9 +32,11 @@ public class OrderEventStream {
 
     private final List<SseEmitter> emitters = new CopyOnWriteArrayList<>();
     private final OrderStatusProjection projection;
+    private final ObjectMapper objectMapper;
 
-    public OrderEventStream(OrderStatusProjection projection) {
+    public OrderEventStream(OrderStatusProjection projection, ObjectMapper objectMapper) {
         this.projection = projection;
+        this.objectMapper = objectMapper;
     }
 
     public SseEmitter subscribe() {
@@ -52,19 +55,8 @@ public SseEmitter subscribe() {
 
     @EventHandler
     public void on(OrderPlaced event) {
-        var payload = new HashMap<String, Object>();
+        Map<String, Object> payload = objectMapper.convertValue(event, new TypeReference<>() {});
         payload.put("type", "PLACED");
-        payload.put("orderId", event.orderId());
-        payload.put("customerId", event.customerId());
-        payload.put("email", event.email());
-        payload.put("amount", event.amount());
-        payload.put("originCity", event.originCity());
-        payload.put("originLat", event.originLat());
-        payload.put("originLng", event.originLng());
-        payload.put("destinationCity", event.destinationCity());
-        payload.put("destinationLat", event.destinationLat());
-        payload.put("destinationLng", event.destinationLng());
-        payload.put("scenario", event.scenario());
         payload.put("timestamp", Instant.now().toString());
         broadcast("order", payload);
     }
diff --git a/workflow-saga/README.md b/workflow-saga/README.md
@@ -5,9 +5,11 @@ Workflow Engine** instead of `@Saga`. The exact same orchestration — start on
 request payment + shipment in parallel, react to either of two payment outcomes, complete the
 process — is expressed as plain imperative Java.
 
-## What got simpler
+## Comparison: `@Saga` vs `@Workflow`
 
-Side-by-side: same business behaviour, expressed two different ways.
+Same business behaviour, expressed two different ways. Neither model is a strict
+upgrade over the other — they make different trade-offs, and which one fits
+better depends on the orchestration you're modelling.
 
 |                                  | `saga` module (`@Saga`)                                                                                                                                                                                                                                                                                                                                                                                                                          | `workflow-saga` module (`@Workflow`)                                                                                                                                                                                                                                                                                                                |
 |----------------------------------|---|---|
@@ -18,6 +20,36 @@ Side-by-side: same business behaviour, expressed two different ways.
 | Race / parallelism                | Implicit, via independent event handlers and shared mutable fields                                                                                                                                                                                                                                                                                                                                                                              | Explicit, via `ctx.anyMatch(WorkflowStepResult::success, paid, paymentCancelled)`                                                                                                                                                                                                                                                                  |
 | Cancellation of pending waits    | Manual: cancel deadlines via `DeadlineManager`, end saga via `SagaLifecycle.end()`                                                                                                                                                                                                                                                                                                                                                              | `delivered.cancel("payment cancelled")` and the workflow simply returns                                                                                                                                                                                                                                                                              |
 
+### Where `@Workflow` reads more naturally
+
+- The control flow is one ordinary Java method. `if`/`else`, early `return`, and
+  local variables describe the orchestration directly, without translating it
+  into a state machine spread across multiple handler methods.
+- Correlation, timeouts, and cancellation are local to the call site
+  (`waitForEvent("...", ..., Duration.ofDays(5))`, `delivered.cancel(...)`),
+  rather than spread between annotations, deadline managers, and lifecycle
+  calls.
+- The engine event-sources every step automatically, so there's no
+  `eventGateway.publish` inside the orchestration and nothing to keep in sync
+  between the orchestration and a projection.
+
+### Where `@Saga` reads more naturally
+
+- A saga naturally decomposes into small, individually-named methods — one per
+  `@SagaEventHandler`. The workflow's `execute(SimpleWorkflowContext ctx)` is a
+  single ~70-line method, which is harder to scan at a glance and harder to
+  unit-test in isolation. For sagas with more branches than this one, that
+  single method grows fast.
+- Saga state lives in named class fields, so "what does this saga remember
+  between events?" is answered by reading the class. In the workflow, the
+  equivalent information is encoded in local variables and the engine's stored
+  state — less direct when debugging.
+- `@SagaEventHandler` makes each correlation explicit at the method level,
+  which is convenient when you want to grep the codebase for every place a
+  particular event participates in an orchestration.
+- The annotation-driven model has been the Axon Framework idiom for years —
+  existing teams won't need to learn a new programming model to maintain it.
+
 The whole orchestration is one `execute(SimpleWorkflowContext ctx)` method:
 
 ```java
@@ -65,10 +97,12 @@ public void execute(SimpleWorkflowContext ctx) {
 }
 ```
 
-There is no `@StartSaga`, no `@EndSaga`, no `@DeadlineHandler`, no `SagaLifecycle.associateWith`, no
-serialized saga state, and no `eventGateway.publish` calls — the workflow never publishes events
-itself. The engine event-sources every step and emits a Started/Completed event pair for each
-`awaitExecute`; projections subscribe to those naturally-emitted events.
+In the workflow model, lifecycle and persistence are handled by the engine rather than by code in
+the orchestration class: there's no `@StartSaga`, `@EndSaga`, `@DeadlineHandler`,
+`SagaLifecycle.associateWith`, or `eventGateway.publish`. The engine event-sources every step and
+emits a Started/Completed event pair for each `awaitExecute`, which projections subscribe to.
+That moves boilerplate out of the orchestration, at the cost of a single longer `execute(...)`
+method — see the trade-off table above.
 
 ## Running the application
 
diff --git a/workflow-saga/pom.xml b/workflow-saga/pom.xml
@@ -8,7 +8,7 @@
     <artifactId>workflow-saga</artifactId>
     <version>0.0.1-SNAPSHOT</version>
     <name>Workflow Saga</name>
-    <description>Same order-process saga as the `saga` module — rewritten with the Axon Workflow Engine.</description>
+    <description>Same order-process saga as the `saga` module — rewritten with the Axoniq Workflow Engine.</description>
 
     <properties>
         <java.version>21</java.version>
@@ -18,7 +18,7 @@
 
         <axon.version>5.1.0</axon.version>
         <axoniq-framework.version>5.1.0</axoniq-framework.version>
-        <axon-workflow.version>1.0.0-SNAPSHOT</axon-workflow.version>
+        <axon-workflow.version>0.1.0</axon-workflow.version>
         <spring-boot.version>4.0.6</spring-boot.version>
         <testcontainers.version>2.0.5</testcontainers.version>
     </properties>
@@ -166,18 +166,4 @@
             </plugin>
         </plugins>
     </build>
-
-    <repositories>
-        <repository>
-            <id>central-portal-snapshots</id>
-            <name>Central Portal Snapshots</name>
-            <url>https://central.sonatype.com/repository/maven-snapshots/</url>
-            <releases>
-                <enabled>false</enabled>
-            </releases>
-            <snapshots>
-                <enabled>true</enabled>
-            </snapshots>
-        </repository>
-    </repositories>
 </project>
