Akka Saga Patterns

This demo project demonstrates more sophisticated use of Akka components to implement a distributed system that uses both Saga flavors: choreography and orchestration.

The blog post series walks through the implementation of a seat reservation system, focusing not only on a basic business flow but also on the error handling and edge cases.

• Part 1 - event choreography
• Part 2 - read models
• Part 3 - exactly-once delivery with deduplication
• Part 4 - error handling, DLQ
• Part 5 - orchestration with workflows

Prerequisites

• A Akka account
• Java 21 (we recommend Eclipse Adoptium)
• Apache Maven
• Docker Engine
• curl command-line tool

Concepts

Designing

To understand the Akka concepts behind this example, see Development Process in the documentation.

Developing

This project demonstrates the use of Workflow and Event Sourced Entity components. For more information, see Developing Services.

Build

Use Maven to build your project:

mvn compile

Run Locally

To start your service locally, for orchestration with the Workflow component run:

mvn compile exec:java -Dapplication.mode="orchestration"

For choreography run:

mvn compile exec:java -Dapplication.mode="choreography"

This command will start your Akka service.

Exercising the service

Create wallet

curl -i -X POST http://localhost:9000/wallet/1/create/100  

Deposit (only 1 request will update the balance, the other will be deduplicated)

curl http://localhost:9000/wallet/1/deposit \
  -i -X PATCH \
  --header "Content-Type: application/json" \
  --data '{"amount": 100, "commandId": "12345"}' 

curl http://localhost:9000/wallet/1/deposit \
  -i -X PATCH \
  --header "Content-Type: application/json" \
  --data '{"amount": 100, "commandId": "12345"}' 

Get wallet

curl http://localhost:9000/wallet/1

Create cinema show

curl http://localhost:9000/cinema-show/show1 \
  -i -X POST \
  --header "Content-Type: application/json" \
  --data '{"title": "Pulp Fiction", "maxSeats": 10}'

Get cinema show

curl http://localhost:9000/cinema-show/show1

Orchestration

Make reservation

curl http://localhost:9000/seat-reservation/123 \
  -i -X POST \
  --header "Content-Type: application/json" \
  --data '{"showId": "show1", "seatNumber": 3, "walletId": 1}'

Get reservation

curl http://localhost:9000/seat-reservation/123

Choreography

Make reservation

curl http://localhost:9000/cinema-show/show1/reserve \
  -i -X PATCH \
  --header "Content-Type: application/json" \
  --data '{"walletId": "1", "reservationId": "123", "seatNumber": 3}'

Verify wallet balance

curl http://localhost:9000/wallet/1

Verify seat status

curl http://localhost:9000/cinema-show/show1/seat-status/3

Run integration tests

To run the integration tests located in src/it/java:

mvn integration-test

Troubleshooting

If you encounter issues, ensure that:

• The Akka service is running and accessible on port 9000.
• Your curl commands are formatted correctly.

Need help?

For questions or assistance, please refer to our online support resources.

Deploying

You can use the Akka Console to create a project and see the status of your service.

Build container image:

mvn clean install -DskipTests

Install the akka CLI as documented in Install Akka CLI.

Deploy the service using the image tag from above mvn install:

akka service deploy order-saga akka-order-saga:tag-name --push

Refer to Deploy and manage services for more information.