EventSourcing.JVM

Extended distributed processes examples with Choreography and Process Manager in addition to the already existing Saga example.

See details in PR https://github.com/oskardudycz/EventSourcing.NetCore/pull/40.

Full sample: https://github.com/oskardudycz/EventSourcing.JVM/tree/main/samples/distributed-processes/src/main/java/io/eventdriven/distributedprocesses/hotelmanagement

Video with explanation:

• Updated to the Spring Boot 3.
• Migrated samples and workshops to EventStoreDB client v4 and EventStoreDB Docker image to 22.10 (the latest LTS).
• Bumped other dependencies.

See more in https://github.com/oskardudycz/EventSourcing.JVM/pull/38.

Event Sourcing is perceived as a complex pattern. Some believe that it's like Nessie, everyone's heard about it, but rarely seen it. In fact, Event Sourcing is a pretty practical and straightforward concept. It helps build predictable applications closer to business. Nowadays, storage is cheap, and information is priceless. In Event Sourcing, no data is lost.

The workshop aims to build the knowledge of the general concept and its related patterns for the participants. The acquired knowledge will allow for the conscious design of architectural solutions and the analysis of associated risks.

The emphasis will be on a pragmatic understanding of architectures and applying it in practice using Marten and EventStoreDB.

1. Introduction to Event-Driven Architectures. Differences from the classical approach are foundations and terminology (event, event streams, command, query).
2. What is Event Sourcing, and how is it different from Event Streaming. Advantages and disadvantages.
3. Write model, data consistency guarantees on examples from Marten and EventStoreDB.
4. Various ways of handling business logic: Aggregates, Command Handlers, functional approach.
5. Projections, best practices and concerns for building read models from events on the examples from Marten and EventStoreDB.
6. Challenges in Event Sourcing and EDA: deliverability guarantees, sequence of event handling, idempotency, etc.
7. Saga, Choreography, Process Manager, distributed processes in practice.
8. Event Sourcing in the context of application architecture, integration with other approaches (CQRS, microservices, messaging, etc.).
9. Good and bad practices in event modelling.
10. Event Sourcing on production, evolution, events' schema versioning, etc.

You can do the workshop as a self-paced kit. That should give you a good foundation for starting your journey with Event Sourcing and learning tools like Marten and EventStoreDB. If you'd like to get full coverage with all nuances of the private workshop, feel free to contact me via email.

Read also more in my article Introduction to Event Sourcing - Self Paced Kit.

Exercises

1. Events definition.
2. Getting State from events.
3. Appending Events:
   • EventStoreDB
   • TODO: Axon Server:
4. Getting State from events
   • EventStoreDB
   • TODO: Axon Server:
5. Business logic:
   • General
   • EventStoreDB
   • TODO: Axon Server:
6. Optimistic Concurrency:
   • EventStoreDB
   • TODO: Axon Server:
7. Projections:
   • General
   • Idempotency
   • Eventual Consistency

See PR: https://github.com/oskardudycz/EventSourcing.JVM/pull/29

Shows how to handle distributed processes in Event Sourcing in practice. Explains various use cases, like:

• batch processing,
• saga vs process managers,
• distributed processes in the single module and across boundaries,
• internal vs external events,
• compensating failures,
• implementation of command and event bus in EventStoreDB.

See the code and more detailed description: https://github.com/oskardudycz/EventSourcing.JVM/tree/main/samples/distributed-processes

See the PR: https://github.com/oskardudycz/EventSourcing.JVM/pull/24.

Read more in How to ensure uniqueness in Event Sourcing.

Shows how to handle unique constraint checks in an event-sources system. Explains various techniques like:

• talking to business,
• stream id design,
• reservation pattern.

See more in:

• Samples,
• How to ensure uniqueness in Event Sourcing,
• Pull request

Added sample showing how to apply stream transformations for events versioning with ESDB, see: https://github.com/oskardudycz/EventSourcing.JVM/blob/main/samples/events-versioning/src/test/java/io/eventdriven/eventsversioning/transformations/esdb/StreamTransformationsTests.java

Besides that:

• Added paths to GitHub Actions to trigger only when changes were made to a specific sample folder,
• did a minor cleanup with redundant code in the Events Versioning sample.

Shows how to handle basic event schema versioning scenarios using event and stream transformations (e.g. upcasting):

• Simple mapping
  • New not required property
  • New required property
  • Renamed property
• Upcasting
  • Changed Structure
  • New required property
• Downcasters
• Events Transformations
• Stream Transformation
• Summary
• 📝 Simple patterns for events schema versioning

See also PR: https://github.com/oskardudycz/EventSourcing.JVM/pull/18

Upgraded:

• EventStoreDB client to 3.0.0
• EventStoreDB Docker image to 21.10.5
• other dependencies

Besides that moved tests project into a dedicated stream metadata sample.

See more in:

• https://github.com/oskardudycz/EventSourcing.JVM/pull/15
• https://github.com/oskardudycz/EventSourcing.JVM/pull/16

Added link to "Practical introduction to Event Sourcing with Spring Boot and EventStoreDB" webinar. Watch it 👇

Besides that:

• Updated dependencies,
• Applied tiny refactorings in various places

Added link to "Let's build the worst Event Sourcing system!" talk I gave at EventSourcing Live 2021 conference.
Watch it 👇

Sample is showing basic Event Sourcing flow. It uses EventStoreDB for event storage and Spring Data JPA backed with PostgreSQL for read models.

The presented use case is Shopping Cart flow:

1. The customer may add a product to the shopping cart only after opening it.
2. When selecting and adding a product to the basket customer needs to provide the quantity chosen. The product price is calculated by the system based on the current price list.
3. The customer may remove a product with a given price from the cart.
4. The customer can confirm the shopping cart and start the order fulfilment process.
5. The customer may also cancel the shopping cart and reject all selected products.
6. After shopping cart confirmation or cancellation, the product can no longer be added or removed from the cart.

Technically it's modelled as Web API written in Spring Boot and Java 17.

Main assumptions

• explain basics of Event Sourcing, both from the write model (EventStoreDB) and read model part (PostgreSQL and Spring Data JPA),
• present that you can join classical approach with Event Sourcing without making a massive revolution,
• CQRS architecture sliced by business features, keeping code that changes together at the same place. Read more in How to slice the codebase effectively?,
• clean, composable (pure) functions for command, events, projections, query handling, minimising the need for marker interfaces. Thanks to that testability and easier maintenance.
• easy to use and self-explanatory fluent API for registering commands and projections with possible fallbacks,
• registering everything into regular DI containers to integrate with other application services.
• pushing the type/signature enforcement on edge, so when plugging to DI.

Overview

It uses:

• pure data entities, functions and handlers,
• Stores events from the command handler result EventStoreDB,
• Builds read models using Subscription to $all.
• Read models are stored to Postgres relational tables with Spring Data JPA.
• App has Swagger and predefined docker-compose to run and play with samples.

Write Model

• Sample ShoppingCart entity and events represent the business workflow. All events are stored in the same file using sealed classes to be able to understand flow without jumping from one file to another. It also enables better typing support in pattern matching. ShoppingCart also contains When method method defining how to apply events to get the entity state. It uses the Java 17 switch syntax for pattern matching.
• Command handlers are defined as static methods in the same file as command definition. It improves ergonomy and reduces context switching as they usually change together. They are pure functions that take command and/or state and create new events based on the business logic. See sample Adding Product Item to ShoppingCart. This example also shows that you can inject external services to handlers if needed.
• Code uses functional interfaces in many places to introduce composability and lously coupled, testable code.
• Added EventStoreDB entity store to load entity state and store event created by business logic.
• Command and Query handlers are grouped/wrapped into application service, to have the single entry point with all possible operations, see ShoppingCartService
• All command handling has to support optimistic concurrency. Implemented full flow using If-Match header and returning ETag. Read more details in my article How to use ETag header for optimistic concurrency

Read Model

• Read models are rebuilt with eventual consistency using subscribe to $all stream EventStoreDB feature,
• Used Spring Data JPA to store projection data into Postgres tables.
• Added sample projection for Shopping cart details and slimmed Shopping cart short info as an example of different interpretations of the same events. Shopping cart details also contain a nested collection of product items to show more advanced use case. Added also base JPAProjection class to reduce needed boilerplate. It supports idempotency by checking the last processed event position against the read model.
• Projections are registered as Spring Boot event listeners. Which enables reusing the generic mechanism for publishing events from EventStoreDB,
• Added long-polling example with If-None-Match header handling for getting shopping cart details by id. See details in ShoppingCartService and ShoppingCartDetailsRepository
• Used service EventStoreDBSubscriptionToAll to handle subscribing to all. It handles checkpointing and resubscribing when the connection is dropped. Added also general background worker to wrap the general Smart Lifecycle handling.
• EventStoreDB subscription forwards events to the Spring Boot ApplicationEventPublisher through EventForwarder wrapping them with EventEnvelope to pass theirs metadata.
• example query handlers for reading data t.
• Used checkpointing to EventStoreDB stream with EventStoreDBSubscriptionCheckpointRepository.

Testing

• Added API integration tests together with a simple wrapper with Specification Pattern to make tests cleaner using Given/When/Then approach. See more in ApiSpecification. See example tests in AddProductItemToShoppingCartTests.
• Added basic unit tests for state rebuild in ShoppingCartTests

Prerequisites

1. Install git - https://git-scm.com/downloads.
2. Install Java JDK 17 (or later) - https://www.oracle.com/java/technologies/downloads/.
3. Install IntelliJ, Eclipse, VSCode or other preferred IDE.
4. Install docker - https://docs.docker.com/engine/install/.
5. Open project folder.

Running

1. Run: docker-compose up.
2. Wait until all dockers got are downloaded and running.
3. You should automatically get:
   • EventStoreDB UI (for event store): http://localhost:2113/
   • Postgres DB running (for read models)
   • PG Admin - IDE for postgres. Available at: http://localhost:5050.
     • Login: [email protected], Password: admin
     • To connect to server Use host: postgres, user: postgres, password: Password12!
4. Open, build and run ECommerceApplication.
   • Swagger should be available at: http://localhost:8080/swagger-ui/index.html