Eventuate, Inc

New Eventuate platform APIs that support Async API: part 1 - events

Tue, 11 Mar 2025 08:01:00 +0000

New Eventuate platform APIs that support Async API: part 1 - events

I recently developed a plugin for SpringWolf that configures an Eventuate service to expose an /springwolf/docs endpoint that returns an Async API document describing the messages that the service sends and receives. While implementing the plugin, however, I discovered that the existing Eventuate APIs were not well suited to exposing Async API-style metadata. For example, the messages sent by the service — and the channels to which it sent them — were not explicitly defined; instead, these details were hidden within the code

This realization prompted the creation of a new set of Eventuate APIs for sending and receiving messages. The old APIs still work but only limited metadata can be generated from them. In this article, I’ll describe the new APIs for publishing and subscribing to events. A later article will describe the new APIs for commands and sagas. Let’s first look at the changes to event publishing.

Event publishing

Let’s first look at the old way of publishing events. After that I describe the new approach.

Original event publishing API

Previously, domain logic simply used the DomainEventPublisher to publish events:

public class CustomerService {

  private DomainEventPublisher domainEventPublisher;

  @Transactional
  public Customer createCustomer(String name, Money creditLimit) {
    ...
    domainEventPublisher.publish(Customer.class, customer.getId(), customerWithEvents.events);
    return customer;
  }

As a result, the channels and event types were not explicitly defined.

New event publishing API

The new approach consists of defining one or more DomainEventPublisherForAggregate @Beans. A DomainEventPublisherForAggregate publishes events for a specific aggregate. Although defining DomainEventPublisherForAggregates involves more code, it explicitly defines the channels and events. The Eventuate plugin for Spring Wolf uses the DomainEventPublisherForAggregate @Beans to generate an Async API document describing the published events and their channels.

Here’s the definition of a DomainEventPublisherForAggregate for the Customer aggregate:

public interface CustomerEventPublisher extends DomainEventPublisherForAggregate<Customer, Long, CustomerEvent> {
}

It’s injected into the CustomerService:

public class CustomerService {

  private final CustomerEventPublisher customerEventPublisher;

  public void reserveCredit(long orderId, long customerId, Money orderTotal) {

      CustomerCreditReservedEvent customerCreditReservedEvent =
              new CustomerCreditReservedEvent(customerId, orderId);

      customerEventPublisher.publish(customer, customerCreditReservedEvent);

Finally, here is the @Bean implementation of the CustomerEventPublisher:

@Component
public class CustomerEventPublisherImpl extends AbstractDomainEventPublisherForAggregateImpl<Customer, Long, CustomerEvent> implements CustomerEventPublisher {

    public CustomerEventPublisherImpl(DomainEventPublisher domainEventPublisher) {
        super(Customer.class, Customer::getId, domainEventPublisher, CustomerEvent.class);
    }
}

Let’s now look at the new event handling API.

Subscribing to events

Let’s first look at the old way of subscribing to events. After that I describe the new approach.

Original event handling API

Previously, event handlers were configured by defining a class that constructed DomainEventHandlers:

public class OrderEventConsumer {

  public DomainEventHandlers domainEventHandlers() {
    return DomainEventHandlersBuilder
            .forAggregateType("io.eventuate.examples.tram.ordersandcustomers.orders.domain.Order")
            .onEvent(OrderCreatedEvent.class, this::handleOrderCreatedEvent)
            ...
            .build();
  }

  public void handleOrderCreatedEvent(DomainEventEnvelope<OrderCreatedEvent> domainEventEnvelope) {
    ...

The DomainEventHandlers was then passed to a DomainEventDispatcherFactory:

public class CustomerConfiguration {

  @Bean
  public OrderEventConsumer orderEventConsumer(CustomerService customerService) {
    return new OrderEventConsumer(customerService);
  }

  @Bean
  public DomainEventDispatcher domainEventDispatcher(OrderEventConsumer orderEventConsumer, DomainEventDispatcherFactory domainEventDispatcherFactory) {
    return domainEventDispatcherFactory.make("orderServiceEvents", orderEventConsumer.domainEventHandlers());
  }

The Eventuate plugin for Spring Wolf can use the DomainEventDispatcher @Beans to generate an Async API document describing the subscribed to events and their channels. However, there’s no obvious way to customize the Async API document by, for example, specifying additional documentation.

New event handling API

The new approach is to define beans that have methods annotated with @EventuateDomainEventHandler. The annotation specifies the event handler’s subscriber ID and the channel. The event type is obtained from the method parameter.

@Component
public class OrderEventConsumer {
  private Logger logger = LoggerFactory.getLogger(getClass());

  private CustomerService customerService;

  public OrderEventConsumer(CustomerService customerService) {
    this.customerService = customerService;
  }

  @EventuateDomainEventHandler(subscriberId = "OrderEventConsumer", channel = "io.eventuate.examples.tram.ordersandcustomers.orders.domain.Order")
  public void handleOrderCreatedEvent(DomainEventEnvelope<OrderCreatedEvent> domainEventEnvelope) {
    OrderCreatedEvent event = domainEventEnvelope.getEvent();
    customerService.reserveCredit(Long.parseLong(domainEventEnvelope.getAggregateId()),
            event.orderDetails().customerId(), event.orderDetails().orderTotal());
  }

The Eventuate plugin for Spring Wolf can search the application context for @Beans that have methods annotated with @EventuateDomainEventHandler. Moreover, in the future, it will support additional annotations that allow you to customize the generated Async API document.

Show me the code

The Eventuate Spring Wolf repository contains some example Async API docs
The development branch of the eventuate-tram-examples-customers-and-orders repository contains an example application that uses the new APIs.

What’s next

A later post will describe the new APIs for sagas and command handlers.

Simplified getting started experience for Spring Boot applications

Thu, 09 Jan 2025 08:01:00 +0000

Simplified getting started experience for Spring Boot applications

There’s a new guide that describes a simpler getting started experience for Spring Boot applications that use the Eventuate platform. It currently describes how to configure Gradle. The Maven instructions will be added soon.

Eventuate now supports Quarkus

Fri, 04 Jun 2021 07:01:00 +0000

Eventuate now supports Quarkus

We are very excited to announce that Eventuate now supports the Quarkus framework in addition to Spring Boot, Micronaut, and .NET.

You can now easily write Quarkus-based that use the Saga and CQRS patterns.

Please see the example applications and the getting start docs.

Quickly get started with @SpringBoot and @EventuateIO with start.eventuate.io

Sun, 02 Aug 2020 09:01:00 +0000

Quickly get started with @SpringBoot and @EventuateIO with start.eventuate.io

The website start.eventuate.io is a quick and convenient way to start the development of an Eventuate/Spring Boot-based service.

There are many Eventuate dependencies to choose from:

If you want to using event sourcing, then select the Eventuate Local dependencies.
Otherwise, if you want to use traditional persistence then select the Eventuate Tram and Eventuate Saga dependencies. Don’t forget you need to pick exactly one transport for the message broker that you want to use.

Start.eventuate.io built on Spring Initialzr. You can, for example, use the command line to generate a service project:

curl https://start.eventuate.io/starter.zip \
-d type=maven-project \
-d language=java \
-d platformVersion=2.3.2.RELEASE \
-d packaging=jar \
-d jvmVersion=11 \
-d groupId=io.eventuate.example.sagas \
-d artifactId=orchestrator \
-d name=orchestrator \
-d description=Demo%20project%20Eventuate%2C%20domain%20events%2C%20and%20saga%20orchestration \
-d packageName=io.eventuate.example.sagas.orchestrator \
-d dependencies=eventuatetramdomainevents,eventuatetramsagaorchestrator,eventuatetramkafka,actuator \
-o demo.zip

An overview of the Eventuate Platform

Sun, 24 May 2020 13:01:00 +0000

An overview of the Eventuate Platform

Here is an overview of the Eventuate Platform.

Slides

An overview of the Eventuate Platform from Chris Richardson

Video

New version of the Eventuate platform released!

Sun, 03 May 2020 13:01:00 +0000

New version of the Eventuate platform released!

We are excited to announce that a new version of the Eventuate platform has been released:

Eventuate Tram
Eventuate Tram Sagas
Eventuate Local
Eventuate CDC Service

There are several major enhancements to the platform including:

Support for Micronaut - see the Micronaut versions of the Eventuate example apps and the user manual
Improved Eventuate CDC service performance - more on that in a later post
start.eventuate.io - for quickly bootstrapping an Eventuate service: search for the Eventuate dependencies

Please read this previous post on upgrading to this new version.

Eventuate Tram supports Java 14 and @SpringBoot 2.2.6.RELEASE

Tue, 31 Mar 2020 09:01:00 +0000

Eventuate Tram supports Java 14 and @SpringBoot 2.2.6.RELEASE #AllTestsGreenOnJDK14

We just upgraded the development branches of a couple of example applications to Java 14 and @SpringBoot 2.2.6.RELEASE:

Eventuate Tram Customers and Orders - Spring Boot - demonstrates how to maintain data consistency in an Spring Boot, JPA-based microservice architecture using choreography-based sagas.
Eventuate Tram Sagas Customers and Orders - Spring Boot - demonstrates how to maintain data consistency in an Spring Boot, JPA-based microservice architecture using orchestration-based sagas.

When the Eventuate Tram libraries, which are currently RC, are released the changes will be merged into master.

Eventuate for Spring Boot and now Micronaut - upgrade information

Tue, 31 Mar 2020 09:01:00 +0000

Upgrading to the upcoming release of Eventuate

Eventuate is a platform that solves the distributed data management problems inherent in a microservice architecture. It makes it straightforward to use patterns such as Sagas, CQRS and Event Sourcing and enables you focus on your business logic.

The latest versions of Eventuate Local (0.32.0.RC4), Eventuate Tram (0.24.0.RC4), Eventuate Tram Sagas (0.13.0.RC4) now support both Spring Boot and Micronaut. We plan to make .RELEASE versions shortly.

Here are the Eventuate Micronaut example applications:

Eventuate Tram Customers and Orders - Micronaut - demonstrates how to maintain data consistency in an Micronaut, JPA-based microservice architecture using choreography-based sagas.
Eventuate Tram Sagas Customers and Orders - Micronaut - demonstrates how to maintain data consistency in an Micronaut, JPA-based microservice architecture using orchestration-based sagas.
Eventuate Customers and Orders - Micronaut - demonstrates how to maintain data consistency in an Micronaut, JPA-based microservice architecture using Micronaut, Event Sourcing, choreography-based sagas and CQRS.

There are numerous other example applications for Spring Boot.

Please note that adding support for Micronaut required changing the names of both Maven artifacts and packages. In order to upgrade to these versions, you must edit your source code. To simplify the process, we created a Python-based upgrade script that makes all but one of the needed renames for Eventuate Local, Tram and Saga applications. It would be great if you try it and provide feedback.

Eventuate explained using microservices patterns

Mon, 24 Feb 2020 09:01:00 +0000

Eventuate explained using microservices patterns

A while back I came up with this diagram that explains Eventuate using microservice architecture patterns.

Let’s look at each of the patterns in turn starting with the Database per Service pattern.

Database per Service pattern

A key characteristic of the Microservice Architecture is loose coupling. There are two types of coupling:

design-time coupling - changing one service requires other services to change. Services must be loosely coupled from a design-time perspective in order to ensure that teams are loosely coupled and, therefore, productive.
runtime coupling - the failure of one service prevents another service from handling a request. Services must also be loosely coupled from a runtime perspective in order to maximize availability.

This requirement for loose coupling significantly impacts the database architecture and creates the need for the Database per Service pattern. At a minimum, to avoid design time coupling, services must not share database tables. And, ideally, to reduce runtime coupling, each service should have its own database server.

Distributed data management patterns

The Database per Service pattern creates distributed data management challenges. There are two key distributed data management patterns that solve these problems:

Saga pattern - implements transactions that span services
CQRS pattern - implements queries that span services

Transaction management with the Saga pattern

Some update operations (a.k.a. commands) need to update data in multiple services. Such an operation typically doesn’t use traditional distributed transactions (2PC) since that’s a type of runtime coupling. Instead, a command that spans services must be implemented using the Saga pattern. A saga is a series of local transactions that are coordinated by the participating services exchanging messages.

As I describe in this series of blog posts about sagas there are two types of saga coordination mechanisms:

choreography-based sagas - services collaborate by exchanging domain events
orchestration-based sagas - a centralized coordinator sending command messages to participants, which respond with reply messages

Implementing queries with the CQRS pattern

Some queries need to retrieve data from multiple services. Since each database is private, the data can only be retrieved using each service’s API. One option is to use API Composition and simply invokes query operations on the services. However, sometimes API composition is inefficient and instead the application must use the CQRS pattern.

The CQRS pattern maintains an easily queryable replica of the data using domain events published by the services that own the data.

How Eventuate solves these distributed data management challenges

Eventuate is a family of frameworks that solve the distributed data management challenges in microservice architecture. By using Eventuate, you can easily implement the Saga and CQRS patterns in your application. Eventuate also provides the messaging primitives for general purpose transactional messaging between services.

The following diagram shows the Eventuate family of frameworks:

There are the following frameworks:

Eventuate Tram Sagas - an orchestration-based saga framework
Eventuate Tram - a transactional message framework
Eventuate Local - an event sourcing framework

Let’s look at the capabilities of these frameworks.

Orchestration-based sagas

The Eventuate Tram Sagas framework implements orchestration-based sagas. It provides an easy to use Java-based domain-specific language for the defining the steps of your saga and their compensating transactions. The saga execution engine is embedded within your services, which simplifies the architecture and improves scalability and availability.

Choreography-based sagas and CQRS

Eventuate makes it easy to implement event-driven microservices that use choreography-based sagas and CQRS. It provides an API for publishing and consuming events. Services can use Eventuate to publish events as part of a database transaction that updates business entity. Other services can use Eventuate to consume events with automatic duplicate detection, which ensures that your message handlers are idempotent.

Eventuate provides different event-driven programming models

Explicit event publishing - use for applications that persist business entities using traditional (e.g. JDBC/JPA) persistence. The Eventuate Tram framework provides APIs for publishing and consuming events.
Event sourcing - an event-centric way of writing your business logic and persisting your business objects. Event sourcing is useful for application that need to maintain the history of changes to business entities. The Eventuate Local framework is Eventuate’s event sourcing framework.

Foundational messaging patterns

These higher level capabilities are built on several foundational patterns:

Transactional Outbox - publish a message as part of the database transaction that updates business entities. This pattern is essential for maintaining consistency. Without it, there is a risk of either updating the database without sending a message or sending a message without the corresponding database update.
Idempotent Consumer - detect and discard duplicate messages by tracking the messages that have already been processed. This pattern handles the scenario where a failure causes the message broker to deliver a message more than once.

This patterns are implemented by both the Eventuate Tram and Eventuate Local frameworks.

Learn more

To learn more please take a look at the following resources:

Developing sagas with Eventuate Tram

Sat, 04 Jan 2020 09:01:00 +0000

Developing sagas with Eventuate Tram

Chris Richardson has written a series of blog posts describing how to implement sagas using Eventuate Tram: