Introduction to Event Sourcing

Have you ever stumbled upon a concept that completely changed how you think about building software? For me, that moment came when our architect introduced the Event Sourcing pattern a few years ago. Like many junior developers, I started my career working on traditional CRUD applications. They were simple, efficient, and worked well—until we really understood our domain.

As system grew more complex due to complex business flows, we found struggling with basic questions:

• How do we trace the root cause of a bug months after it occurred and after tens of versions were deployed?
• How can we rebuild a user’s journey when all we have are their current state in the database and a lot of logs?
• What data should be collected for any future use cases ? Is our architecture flexible enough for the unknown?

The main purpose of my article is to present the foundational concepts with pure Java code examples.

If there’s one thing I’ve learned over the years, it’s that this pattern is highly subjective in its implementation, and there’s no perfect way to do things—any cake recipe is good as long as you and your family enjoy eating it.

PS: I’ll do my best to show you that the following metaphor shouldn’t hold true: “Software ages like milk, not wine“.

To be honest, in the first place, this pattern may require additional related concepts that complement each other very well, especially for complex or large systems. Domain Driven Design (DDD) and Command Query Responsibility Segregation (CQRS) provide significant benefits when used together ❤️ with Event Sourcing (ES), but they are not mandatory ⚠️. Each one has their proven benefits, but the complexity added to the system, pff … can easily become a nightmare, so please be aware and think more carefully before applying any.

“If the only tool you have is a hammer , you tend to see every problem as a nail.” (Abraham Maslow)

DEFINITION

Event sourcing is an architectural pattern where state transitions of a system are stored into an immutable append-only storage as a sequence of immutable events into an immutable append-only storage, instead of just saving the latest state.

These events represent facts that have occurred in the past, and by replaying them in order, you can reconstruct the system’s state at any point in time.

Events timeline

Event Storming

Given the fact that the only single source of truth is in the events stream we need to do a small session of brainstorming but with events, so called Event Storming.

The first step in running an event storming workshop is to invite the right stakeholders and bring them together (I prefer a physical room for high concentration, not a virtual one). It’s a place where technicalities are left at the door—no Java, no Spring Boot, just business. I get it; you might think it’s just another boring meeting, but trust me, it’s the safest playground before writing any piece of code. Try to ask as many questions as possible (even the dumbest ones, because you don’t fully understand the domain yet), you’ll thank yourself later.

The rules of the game are simple, we need coloured sticky notes:

• Orange – for domain events. Things that happen in the system written in the past tense (e.g. Application Created)
• Blue – for commands. Actions or requests initiated by a user or system that trigger domain events. They represent the intent to change a state (e.g. Create Application)
• Pink – for actors. The users or systems that interact with the domain, initiating commands or reacting to events. (e.g. Student)
• Purple – for policies. Business rules that automatically trigger commands in response to events. (e.g. Send Confirmation Email)
• Green – for projections (read models). Business oriented and optimised query model. (e.g. List of Draft Applications).
• Yellow – for aggregates. Core business entities that manage the consistency of the domain model. They are responsible for handling commands and emitting domain events (e.g. Application)

For our remote setup we’ll use one great tool for this called Miro. We’ve been using it since the beginning of our journey, and it has never let us down, so I highly recommend it.

Event Storming terminology

Firstly, each participant must add events to the board in any order. Then, we will remove duplicates and arrange them chronologically on the timeline — unfortunately, I don’t have sufficient space to replicate the timeline in a horizontal format.

Secondly, participants must enhance the events with corresponding commands, actors, policies and views. After all puzzle pieces are in place we must align them accordingly to consistency requirements and aggregates will be evident enough.

In DDD, an aggregate is the core lifecycle pattern treated as a single unit which enforces invariance and transactional boundaries to maintain data consistency within.

In ES, the transactional boundary is redefined within the stream of events – Sara Pellegrini wrote in her gold series about this (https://sara.event-thinking.io/2023/04/kill-aggregate-chapter-1-I-am-here-to-kill-the-aggregate.html).

Our journey begins with a real-life scenario that deviates from the usual examples (e.g., bank accounts or eCommerce shopping carts), drawing inspiration from the Spring demo project, PetClinic.

Let’s begin by defining some fundamental events.

Events

Due to space and time constraints, I will not cover here all use cases but will focus solely on the business flows related to the Pet.

Pet domain

To sum up the board results, the command side is composed by 5 actions, all performed by the same actor:

• Register pet – Vet creates a new pet in the clinic.
• Update details pet – Vet updates pet details.
• Add medical entry – Vet adds new medical entry to pet’s medical log.
• Transfer pet – Vet changes the pet’s owner.
• Remove pet – Vet remove the pet from the clinic because the owner changed the responsible vet or the pet is dead 😭.

A single policy exists in our scenario for sending a notification to the new owner to inform about the ownership change.

For the read side, we currently have only 2 views:

• Pets – Displays all pets in the clinic along with their information. This view is useful for tables, pet detail pages and similar use cases.
• Sick pets – Shows all active pets with ongoing medical entries, which is required for the home page dashboard.

The key advantage of this approach is its flexibility—additional views can be constructed even from the existing events, allowing product owners to be highly creative in designing new features.

I’ve tried to simplify as much as I could the story and I hope you got the point.

Earlier this year, I came across the Event Modeling approach proposed by Adam Dymitruk, which feels like a natural evolution of Event Storming. While I haven’t had hands-on experience with this method yet, I’m eager to dive in, explore, and put it into practice.

Event sTORE

What is it ? It’s a specialised database designed to store and retrieve events which are immutable records of changes that have occurred in the system.

Another database ?

Wait, wait, I can try to explain!

Why do we need it? Because we must store the source of truth in a highly available and performant storage with several essential features:

• Append-only storage – events are written once and never modified or deleted.
• Event streams – supports logical groupings of events into streams, preserving their order (e.g. a partition in a Kafka topic).
• Read stream events – allows reading stream events in the same order they were written.
• Consistency – ensures that two events with the same sequence number cannot exist in the same stream (this represents the C from ACID).

As you dive deeper into the topic you’ll discover additional specific requirements, such as appending multiple events at once, reading only committed events, reading streams from a specific offset, streaming data via subscriptions, building snapshots, and much more.

Currently, Axon Server is the leading choice in the Java ecosystem, while EventStoreDB dominates in the .NET ecosystem.

In 2024 the SQL winner among developers is PostgreSQL, so why not use it for event sourcing as well? You might think a single table partitioned by stream identifier would be sufficient.

Yes, you can do that, but I wouldn’t recommend it. I’ve tried it by myself (sadly, still here 😅), and it works—until you realise you’re essentially re-creating the same features that dedicated event store providers offer by default. Many frameworks support SQL databases for event storage, but that doesn’t mean it’s the right choice in production.

Enough theory, let’s turn on the JVM!

SHOW ME THE CODE

To better understand event sourcing, I decided to build a basic custom infrastructure without using frameworks or libraries. This hands-on approach allowed me to focus on the core concepts.

The foundation of event sourcing lies in events, making their design the natural starting point. I initially implemented a basic interface but found it lacked sufficient compiler support for enforcing validations and raising errors if an event was not properly handled. To address this, I transitioned to a more robust solution using sealed interfaces, introduced in Java 17.

Immutability is a key requirement for events, making records the natural choice.

Applying the theory to our example, each PetEvent implements the sealed interface PetEvent, which enforces a restricted set of allowed events. Adding a new event involves two steps:

1. Define the event as a record with the necessary business fields (e.g., PetRegistered)
2. Include it in the sealed interface’s list of permitted implementations.

public sealed interface PetEvent
        permits PetEvent.PetRegistered,
        PetEvent.PetDetailsUpdated,
        PetEvent.PetOwnerTransferred,
        PetEvent.PetDeactivated,
        PetEvent.PetMedicalEntryAdded {

    record PetRegistered(
            UUID id,
            String name,
            Instant birthDate,
            PetType type,
            Owner owner
    ) implements PetEvent {}

    ....
}

Events can be defined as static nested classes within the interface or as separate classes. Given the small number of events in this example, I preferred them in the same interface for simplicity.

Next, we need to establish the API for the event store. Two core functionalities are critical:

• appending events to a stream ✍️
• reading from a stream 📖

Additionally, a subscription mechanism is essential to notify listeners about changes.

public interface EventStore {

    List<Object> readStream(String streamId);
    void appendStream(String streamId, int expectedVersion, Object[] events);

    void subscribe(EventListener listener);
}

The read operation is straightforward, as you only need to provide the stream identifier, and a list of events is returned in the order they were written.

The append operation is a bit more complex because it must handle optimistic locking and the creation of a non-existing stream. The key element here is the provided expectedVersion.

The subscribe operation follows the basic Observer pattern.

public interface EventListener {
    void on(Object event);
}

Let’s explore in more detail how an InMemoryEventStore might be implemented.

First, it must partition all streams by identifiers, maintaining a sequential list of events for each. A Map would be the ideal structure for this. Second, it should manage the list of subscribers. The subscribe and readStream methods are self-explanatory.

public class InMemoryEventStore implements EventStore {

    static final Map<String, LinkedList<EventEnvelope>> STORE = new ConcurrentHashMap<>();
    static final List<EventListener> EVENTS_SUBSCRIBERS = new LinkedList<>();

    public void subscribe(EventListener listener) {
        EVENTS_SUBSCRIBERS.add(listener);
    }

    public List<Object> readStream(String streamId) {
        return STORE.get(streamId)
    }

    ....
        
}

Instead of storing a simple event object, we use an EventEnvelope. But why is this necessary?

It splits the stored data into two parts: metadata and event payload.

• Metadata is added by the event store and includes details like the event’s timestamp, version, and other important context.
• Event payload contains the core business data representing the actual event.

This separation makes it easier to track events, adds flexibility for future changes, and improves scalability.

public record EventEnvelope(
        EventMetadata metadata,
        EventPayload data
) {}
public record EventMetadata(
        int version,
        Instant timestamp
) {}
public record EventPayload(
        String name,
        String data
) {}

if (!STORE.containsKey(streamId)) {
    if (expectedVersion != -1) {
        throw new IllegalStateException("Version mismatch for uninitialized stream");
    }

    int lastVersion = 1;
    var newEvents = new LinkedList<EventEnvelope>();
    
    for (var event : events) {
        newEvents.add(
                new EventEnvelope(
                        new EventMetadata(
                                lastVersion++,
                                Instant.now()),
                        serialize(event)
                )
        );
    }

    STORE.put(streamId, newEvents);
}

else {
    var currentEvents = STORE.get(streamId);

    if (currentEvents == null) {
        throw new IllegalStateException("Stream not initialized");
    }

    var lastVersion = currentEvents.getLast().metadata().version();
    if (lastVersion != expectedVersion) {
        throw new IllegalStateException("Optimistic locking failure");
    }

    int newVersion = lastVersion + 1;
    for (var eventPayload : eventPayloads) {
        currentEvents.addLast(new EventEnvelope(new EventMetadata(newVersion++, Instant.now()), eventPayload));
    }
}

for (var event : events) {
    for (var eventSubscriber : EVENTS_SUBSCRIBERS) {
        eventSubscriber.on(event);
    }
}

public interface Aggregrate<ID> {

    ID id();
    int version();

    Object[] uncommitedEvents();

}

public abstract class AbstractAggregate<I, E> implements Aggregrate<I> {

  protected I id;
  protected int version;

  private final Queue<E> uncommittedEvents = new LinkedList<>();

  @Override
  public I id() {
      return id;
  }

  @Override
  public int version() {
      return version;
  }

  @Override
  public Object[] uncommitedEvents() {
      Object[] events = uncommittedEvents.toArray();
      uncommittedEvents.clear();
      return events;
  }

  public void replay(List<E> events) {
      events.forEach(e -> {
          apply(e);
          version++;
      });
  }

  protected abstract void apply(E event);

  protected void enqueue(E event) {
      uncommittedEvents.add(event);
      apply(event);
  }

}

public class Pet extends AbstractAggregate<UUID, PetEvent> {

    private String name;
    private Instant birthDate;
    private PetType type;
    private Owner owner;
    private boolean active;
    private final List<MedicalEntry> medicalEntries = new LinkedList<>();

    ...
}

public Pet(RegisterPet command) {
    enqueue(
       new PetRegistered(
         UUID.randomUUID(), 
         command.name(), 
         command.birthDate(), 
         command.type(), 
         command.owner()
       )
   );
}

@Override
protected void apply(PetEvent event) {
    switch (event) {
        case PetRegistered registered -> {
            this.id = registered.id();
            this.name = registered.name();
            this.birthDate = registered.birthDate();
            this.owner = registered.owner();
            this.type = registered.type();
            this.active = true;
        }
        ...
    }
}

public void handle(UpdatePetDetails command) {
    if (!active) {
        throw new IllegalStateException("Pet is not active");
    }

    enqueue(new PetDetailsUpdated(this.id, command.name(), command.birthDate(), command.type()));
}

Pet dog = new Pet(
        new PetCommand.RegisterPet(
                "My dog", 
                LocalDateTime.of(2020, 1, 1, 0, 0)
                        .toInstant(ZoneOffset.UTC), 
                PetType.DOG, 
                new Owner("Alex", "alex@gmail.com", "Street 1")
        )
);

eventStore.appendStream(
        dog.id().toString(), 
        -1, 
        dog.uncommitedEvents()
);

Pet storedPet = new Pet(
        eventStore.readStream(dog.id().toString())
);

storedPet.handle(
        new PetCommand.UpdatePetDetails(
                "My dog is a cat", 
                LocalDateTime.of(2020, 1, 1, 0, 0)
                        .toInstant(ZoneOffset.UTC), 
                PetType.CAT
        )
);
eventStore.appendStream(
        dog.id().toString(), 
        storedPet.version(), 
        storedPet.uncommitedEvents()
);

public class NotificationPolicy implements EventListener {

 private final Repository<Notification, UUID> repository;

 public NotificationPolicy(
          Repository<Notification, UUID> repository
 ) {
     this.repository = repository;
 }

  @Override
  public void on(Object event) {
    switch (event) {
      case PetEvent.PetOwnerTransferred petOwnerTransferred -> {
           repository.save(
                 new Notification(
                     petOwnerTransferred.newOwner().email(), 
                     "Your new pet", 
                     "Congratulations for owning!"
                 )
            );
      }
      default -> 
         System.out.println(
          "Event " + event.getClass().getName() + " not handled"
         );
    }
  }
}

public class PetsProjection implements EventListener {

    private final Repository<PetDetails, UUID> repository;

    public PetsProjection(Repository<PetDetails, UUID> repository) {
        this.repository = repository;
    }

    @Override
    public void on(Object event) {
        switch (event) {
            case PetEvent.PetRegistered registered 
-> addPet(registered);
            case PetEvent.PetDetailsUpdated detailsUpdated 
-> updatePetDetails(detailsUpdated);
            case PetEvent.PetMedicalEntryAdded medicalEntryAdded -> addMedicalEntry(medicalEntryAdded);
            case PetEvent.PetOwnerTransferred ownerTransferred 
-> changeOwner(ownerTransferred);
            case PetEvent.PetDeactivated petDeactivated 
-> deactivatePet(petDeactivated);
            default -> System.out.println("Event " + event.getClass().getName() + " not handled");
        }
    }

    private void addPet(PetEvent.PetRegistered registered) {
        repository.save(
                new PetDetails(
                        registered.id(),
                        registered.name(),
                        registered.birthDate(),
                        registered.type(),
                        registered.owner(),
                        true,
                        new ArrayList<>()
                )
        );
    }

    private void updatePetDetails(PetEvent.PetDetailsUpdated detailsUpdated) {
        var petDetails = repository.findById(detailsUpdated.petId());

        petDetails.ifPresent(pet -> {
            pet.updateDetails(detailsUpdated.name(), detailsUpdated.birthDate(), detailsUpdated.type());
            repository.save(pet);
        });
    }

   .....
}

public class MostSickPetsProjection implements EventListener {

    private final Repository<SickPetDetails, UUID> repository;

    public MostSickPetsProjection(Repository<SickPetDetails, UUID> repository) {
        this.repository = repository;
    }

    @Override
    public void on(Object event) {
        switch (event) {
            case PetEvent.PetMedicalEntryAdded medicalEntryAdded -> addMedicalEntry(medicalEntryAdded);
            case PetEvent.PetDeactivated petDeactivated 
-> removePet(petDeactivated);
            default -> System.out.println("Event " + event.getClass().getName() + " not handled");
        }
    }

    private void addMedicalEntry(
         PetEvent.PetMedicalEntryAdded medicalEntryAdded) 
     {
        var petDetails = repository.findById(medicalEntryAdded.petId());

        petDetails.ifPresentOrElse(pet -> {
            pet.addMedicalEntry(new MedicalEntry(medicalEntryAdded.entryDescription(), medicalEntryAdded.entryDate()));
            repository.save(pet);
        }, () -> {
            repository.save(new SickPetDetails(medicalEntryAdded.petId(), new MedicalEntry(medicalEntryAdded.entryDescription(), medicalEntryAdded.entryDate())));
        });

    }
    
    private void removePet(PetEvent.PetDeactivated petDeactivated) {
        repository.delete(petDeactivated.petId());
    }
}

public record GetPetsQuery(
        int offset,
        int size,
        Optional<String> name
) {}

public class PetsRepository extends Repository<PetDetails, UUID> {

    public List<PetDetails> findPets(GetPetsQuery query) {
        var pets = findAll();

        if (query.name().isPresent()) {
            pets = pets.stream()
                 .filter(pet -> pet.name().toLowerCase()
                    .contains(query.name().get().toLowerCase()))
                 .toList();
        }

        return pets.subList(
            query.offset(), 
            Math.min(query.size(), pets.size())
        );
    }  

}

public class SickPetsRepository extends Repository<SickPetDetails, UUID> {

    public List<SickPetDetails> findSickPetsOrderDesc() {
        return findAll().stream()
                .sorted(
                     Comparator.comparing(p ->   
                         p.medicalEntries().size()))
                .toList();
    }
}

Author: Alexandru Adam

Experienced Java developer with expertise in Spring and Kubernetes, driven by a passion for clean architecture and event-driven systems, including event sourcing.