Chapter 11: The design of the FTGO 'Create Order saga'
Introduces the FTGO Create Order saga as a concrete application of earlier saga concepts and outlines the chapter’s design topics.
After this chapter you will be able to
- Create Order transaction phases. Describe how the saga’s six steps are classified around credit-card authorization: the preceding compensatable steps, the pivot, and the subsequent retriable steps.
- Order and Ticket semantic locks. Explain why the saga uses the semantic lock countermeasure for both Order and Ticket entities.
- Centralized orchestration choice. Explain why the multi-step Create Order Saga uses orchestration rather than choreography.
- Order Service orchestrator placement. Describe where the orchestrator resides and what that means for Order entity operations.
- Participant messaging arrangement. Trace how commands and replies travel between the orchestrator and saga participants, and state why the section uses request/asynchronous-response.
- Tram Saga framework roles. Distinguish SimpleSaga’s role in defining an orchestrator from SagaManager’s role in creating and managing saga instances.
- Initial saga command sequence. Trace how OrderService starts a Create Order Saga and how its first command reaches a participant.
- Participant reply progression. Trace how a Consumer Service reply advances the saga to a command for the Kitchen Service.
- Participant command routing. Describe how the participant package connects incoming saga commands to business logic and replies.
- Saga initiation and local operations. Describe the distinct roles of OrderSagaService and OrderService: one handles the POST /orders request and initiates the saga, while the other is invoked by CreateOrderSaga to perform local operations on Orders.
- Saga definition state and proxies. State what CreateOrderSaga, CreateOrderSagaState, and the SagaParticipantProxy classes each define or hold in the design.
- Create Order saga initiation. Trace how OrderSagaService handles a POST /orders request, from creating the saga state through returning the Order.
- CreateOrderSaga definition and interface. Explain that CreateOrderSaga implements SimpleSaga and uses the Eventuate Tram Saga DSL to define the saga’s steps. Describe how its constructor stores the definition and getSagaDefinition() returns it.
- Local Order step and compensation. Describe how the first step creates the Order locally and compensates by rejecting it locally, with create() and reject() invoking OrderService.
- Kitchen Service participant step. Trace how the third step asks Kitchen Service to create a Ticket and compensates by canceling it. Explain that invokeParticipant() defines the forward transaction using a CommandWithDestination produced through KitchenServiceProxy.
- Create Order saga state. Trace how OrderService initializes CreateOrderSagaState, how the framework persists it, and how saga steps read and update it.
- OrderService local operations. Explain that CreateOrderSaga invokes OrderService to create, approve, and reject the Order, while it uses saga proxies to create command messages for saga participants.
- Participant proxy purpose and benefits. Explain what a saga participant proxy class defines, why it is optional, and why the Create Order Saga uses one for each participant.
- Participant command handling. Explain how a non-local saga participant handles a command and, when the orchestrator expects a reply, turns the business outcome into a reply message. Describe how the Kitchen Service’s createTicket() handler follows this pattern.
What it builds on
- The structure of a saga (chapter 9) · Assumes the basic structure of a saga as a sequence of steps.
- Countermeasures for handling the lack of isolation (chapter 9) · Assumes the lack-of-isolation problem and the idea of countermeasures for it.
- Orchestration-based sagas (chapter 10) · Introduces orchestration-based sagas.
- Implementing orchestration using asynchronous messaging (chapter 10) · Introduces orchestration using asynchronous messaging.
- Implementing the saga orchestrator (chapter 10) · The earlier explanation of a saga orchestrator.
- Example orchestration-based Create Order Saga (chapter 10) · The orchestration-based Create Order Saga example.
Section by section
Introduction
Introduces the FTGO Create Order saga as a concrete application of earlier saga concepts and outlines the chapter’s design topics.
11.1 An overview of the FTGO Create Order saga
This section previews an examination of the FTGO Create Order saga’s definition, implementing service architecture, and orchestrator framework.
11.1.1 The FTGO Create Order Saga definition
Defines the FTGO Create Order Saga by identifying its transaction phases and how it handles concurrent updates.
- Create Order transaction phases: Describe how the saga’s six steps are classified around credit-card authorization: the preceding compensatable steps, the pivot, and the subsequent retriable steps.
Why it matters: These phases explain where business-rule failure remains possible and what happens after authorization succeeds. - Order and Ticket semantic locks: Explain why the saga uses the semantic lock countermeasure for both Order and Ticket entities.
Why it matters: The locks address the risk of other transactions encountering entities partway through the saga.
Key terms: pivot transaction, compensatable transactions, retriable transactions, consumer, credit card, semantic lock countermeasure, lack of isolation, Order, Ticket
11.1.2 The Create Order Saga's orchestrators design
This section explains why the FTGO Create Order Saga uses a centralized orchestrator in the Order Service and how it coordinates participants through messaging.
- Centralized orchestration choice: Explain why the multi-step Create Order Saga uses orchestration rather than choreography.
Why it matters: This choice explains where the saga’s overall definition lives. - Order Service orchestrator placement: Describe where the orchestrator resides and what that means for Order entity operations.
Why it matters: The orchestrator’s location distinguishes local Order changes from its interactions with saga participants. - Participant messaging arrangement: Trace how commands and replies travel between the orchestrator and saga participants, and state why the section uses request/asynchronous-response.
Why it matters: The channel directions show how the central orchestrator communicates with participants. - Saga framework responsibilities: State what infrastructure the Eventuate saga orchestration framework supplies for this implementation.
Why it matters: It identifies which orchestration concerns the implementation relies on the framework to support.
Key terms: Create Order Saga, orchestration, choreography, Order Service, orchestrator, Order entity, local operations, request/asynchronous-response, command channel, reply channel
11.1.3 The Eventuate Platform’s Tram Saga framework
This section explains how Eventuate Tram Saga creates and advances the FTGO Create Order Saga, handles participant replies and failures, and routes commands to participants.
- Tram Saga framework roles: Distinguish SimpleSaga’s role in defining an orchestrator from SagaManager’s role in creating and managing saga instances.
Why it matters: These roles clarify which part defines the saga and which part runs it. - Initial saga command sequence: Trace how OrderService starts a Create Order Saga and how its first command reaches a participant.
Why it matters: The starting sequence shows how a saga definition becomes a running, persisted instance. - Participant reply progression: Trace how a Consumer Service reply advances the saga to a command for the Kitchen Service.
Why it matters: A reply is what lets the manager resume a stored saga and move it to the next participant. - Failure compensation order: State what SagaManager does when a saga participant fails.
Why it matters: The failure path explains how the manager responds when the forward saga cannot continue. - Participant command routing: Describe how the participant package connects incoming saga commands to business logic and replies.
Why it matters: It shows what happens on the participant side of the command-and-reply exchange.
Key terms: Eventuate Tram Saga, SimpleSaga, SagaManager, saga orchestration package, OrderService, CreateOrderSagaState, Consumer Service, reply message, Kitchen Service, compensating transactions
11.2 The Create Order Saga orchestrator design
Identifies the main Order Service classes involved in the Create Order Saga and their responsibilities.
- Saga initiation and local operations: Describe the distinct roles of OrderSagaService and OrderService: one handles the POST /orders request and initiates the saga, while the other is invoked by CreateOrderSaga to perform local operations on Orders.
Why it matters: This distinction clarifies which class starts the saga and which carries out its local Order operations. - Saga definition state and proxies: State what CreateOrderSaga, CreateOrderSagaState, and the SagaParticipantProxy classes each define or hold in the design.
Why it matters: These roles distinguish the saga definition and its state from the commands and replies used with participants.
Key terms: OrderSagaService, OrderService, POST /orders, CreateOrderSaga, CreateOrderSagaState, SagaParticipantProxy, commands, replies
11.2.1 The OrderSagaService class
This section traces how OrderSagaService starts the Create Order saga in response to a POST /orders request and returns the Order created by its first local step.
- Create Order saga initiation: Trace how OrderSagaService handles a POST /orders request, from creating the saga state through returning the Order.
Why it matters: This identifies the entry point and handoff from the REST request to the saga.
Key terms: OrderSagaService, createOrder(), CreateOrderSagaState, SagaInstanceFactory.create(), CreateOrderSaga, first local step
11.2.2 The CreateOrderSaga orchestrator class
This section shows how CreateOrderSaga defines local and cross-service steps, their compensations, and handling of a successful Kitchen Service reply.
- CreateOrderSaga definition and interface: Explain that CreateOrderSaga implements SimpleSaga and uses the Eventuate Tram Saga DSL to define the saga’s steps. Describe how its constructor stores the definition and getSagaDefinition() returns it.
Why it matters: It identifies where the orchestrator’s sequence of steps is defined. - Local Order step and compensation: Describe how the first step creates the Order locally and compensates by rejecting it locally, with create() and reject() invoking OrderService.
Why it matters: It shows how a saga step associates an action with an action that can compensate for it. - Kitchen Service participant step: Trace how the third step asks Kitchen Service to create a Ticket and compensates by canceling it. Explain that invokeParticipant() defines the forward transaction using a CommandWithDestination produced through KitchenServiceProxy.
Why it matters: It distinguishes a cross-service saga step from the local Order step. - Successful Ticket reply handling: Explain what onReply() specifies for a successful Kitchen Service reply and what the designated handler stores.
Why it matters: It connects the Kitchen Service’s successful response to state retained by the saga.
Key terms: CreateOrderSaga, SimpleSaga, saga definition, Eventuate Tram Saga, getSagaDefinition(), invokeLocal(), withCompensation(), OrderService, compensating transaction, Kitchen Service
11.2.3 The CreateOrderSagaState class
This section explains how CreateOrderSagaState holds, persists, and supplies application-specific data during the Create Order saga.
- Create Order saga state: Trace how OrderService initializes CreateOrderSagaState, how the framework persists it, and how saga steps read and update it.
Why it matters: The state carries the data that saga steps need as the Create Order saga runs.
Key terms: CreateOrderSagaState, application-specific saga state, Eventuate Tram Saga framework, service command arguments
11.2.4 The OrderService class
This subsection explains how the CreateOrderSaga uses OrderService for local Order operations and outlines what OrderService.createOrder() does.
- OrderService local operations: Explain that CreateOrderSaga invokes OrderService to create, approve, and reject the Order, while it uses saga proxies to create command messages for saga participants.
Why it matters: This distinction clarifies which work happens locally and which work is directed to saga participants. - Order creation method steps: Describe the four actions of OrderService.createOrder(): retrieve the Restaurant, create and persist the Order, and publish any domain events created by the Order aggregate.
Why it matters: These steps show what the saga’s local Order creation call accomplishes.
Key terms: CreateOrderSaga, OrderService, saga proxies, saga participants, createOrder(), Restaurant, Order, domain events, Order aggregate
11.2.5 The saga participant proxy classes
This section explains why the Create Order Saga uses participant proxy classes and illustrates their API and metadata with KitchenServiceProxy.
- Participant proxy purpose and benefits: Explain what a saga participant proxy class defines, why it is optional, and why the Create Order Saga uses one for each participant.
Why it matters: Proxies make participant interactions less error-prone, easier to test, and documentable without being required to send commands. - Kitchen proxy operations and annotations: Describe how KitchenServiceProxy represents Kitchen Service operations and what its annotations tell Eventuate Spring Wolf.
Why it matters: The Kitchen example shows how a proxy presents participant operations and supplies metadata for documenting them.
Key terms: saga participant proxy class, static typed endpoints, Eventuate Spring Wolf, AsyncAPI, KitchenServiceProxy, createTicket(), confirmCreateTicket(), cancelCreateTicket(), CommandWithDestination, @SagaParticipantProxy
11.3 The saga participant command handlers
This section explains how non-local participants in the FTGO Create Order Saga handle commands, using the Kitchen Service as an example.
- Participant command handling: Explain how a non-local saga participant handles a command and, when the orchestrator expects a reply, turns the business outcome into a reply message. Describe how the Kitchen Service’s createTicket() handler follows this pattern.
Why it matters: This connects the orchestrator’s commands to the work performed by each participant. - Command handler subscription annotation: Describe what the @EventuateCommandHandler annotation specifies for a Kitchen Service command handler.
Why it matters: These settings identify the handler’s subscriber and the channel from which it receives commands.
Key terms: non-local participants, command handler, business logic, createTicket(), KitchenService, @EventuateCommandHandler, subscriberId, Apache Kafka consumer group, command channel
11.4 Summary
Concepts explained in this chapter
- Eventuate Tram Saga frameworkThe Eventuate Tram Saga framework provides infrastructure for defining and executing sagas that coordinate transactions across services.
- saga participantA service or component that performs one or more local transactions as part of a saga.
- saga orchestratorA saga orchestrator coordinates saga steps by invoking participants, maintaining saga state, and determining what to do based on their outcomes.
- asynchronous requestAn interaction style in which a requester sends a request and later receives a response without blocking for an immediate result.
- orchestration-based saga coordinationA saga whose steps are coordinated by a centralized orchestrator.
- compensating transactionA transaction that semantically undoes the effects of a previously committed transaction.
- channelA communication path through which messages are sent and received.
- command channelA command channel is a message channel through which a participant receives command messages.
- compensatable stepA saga step before the pivot transaction whose effects may need to be undone by a compensating transaction.
- pivot transactionA saga transaction that marks the point after which the saga must complete through forward recovery or subsequent noncompensatable actions.
- retriable transactionA retriable transaction is a Saga step after the pivot transaction that is guaranteed to succeed, potentially through repeated invocation after transient failure.
- semantic lockA semantic lock is an application-level record flag or locking convention that indicates an uncommitted value may change and should be restricted or treated cautiously.
- saga stateSaga state is the durable data recording a saga instance's execution position and information needed to continue it.
- software architectureThe structures of a software system, including its elements, their relationships, and their properties.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
