Define event handlers in Java

Event handlers process events by creating a new aggregate or updating an existing one. The Eventuate client framework for Java supports a number of ways to implement event handlers. The simplest approach is to use the high-level API.

High-level event handler API for Java

The high-level API hides a lot of the boilerplate code that you would otherwise have to write. When using this API you define one or more event handler Spring beans. Each Spring bean defines one or more event handler methods, one for each type of event that the handler processes. The framework subscribes to the events and dispatches each event to the appropriate event handler method.

Here is an example of an event handler class. It defines two methods, debitAccount(), which handles MoneyTransferCreatedEvents, and creditAccount, which handles DebitRecordedEvents.

public class AccountWorkflow {

  public Observable<?> debitAccount(EventHandlerContext<MoneyTransferCreatedEvent> ctx) {
    MoneyTransferCreatedEvent event = ctx.getEvent();
    BigDecimal amount = event.getDetails().getAmount();
    Aggregate.EntityId transactionId = ctx.getEntityId();

    Aggregate.EntityId fromAccountId = event.getDetails().getFromAccountId();

    return ctx.update(Account.class, fromAccountId,
                          new DebitAccountCommand(amount, transactionId));

  public Observable<?> creditAccount(EventHandlerContext<DebitRecordedEvent> ctx) {

The @EventSubscriber annotation specifies the name of the subscription. Each event handler method is annotated with @EventHandlerMethod. An event handler method has a single parameter of type EventHandlerContext, a generic interface, which is parameterized by the event type. It has methods that provide access to the event as well as metadata such as the type and identity of the aggregate that published the event. It also defines save() and update() methods that the event handler uses to create or update an aggregate.

Low-level API

The low-level API is much more flexible but requires you to write much more code. It consists of an EventStoreSubscriptionManagement interface, which you can inject into your event handling code.

class MyEventHandlingCode {

  private EventStoreSubscriptionManagement eventStoreSubscriptionManagement;

EventStoreSubscriptionManagement has a subscribeForObservable() method. This method creates a durable named subscription to one or more event types:

trait EventStoreSubscriptionManagement {

  def subscribeForObservable(subscriptionId: SubscriptionId):


The subscriptionId parameter specifies the name of the subscription and the events to subscribe to. Since the process of establishing the subscription is asynchronous, it returns an Observable[AcknowledgableEventStream]. An AcknowledgableEventStream consists of a RxJava Observable containing the published events and an Acknowledger that provides API to acknowledge that an event has been processed.

Stay in touch
Copyright © 2019 Eventuate, Inc • All rights reserved.