Event Sourcing Handlers & Rebuilding State

An @EventSourcingHandler method is typically a small, void-returning method named on, overloaded once per event type the aggregate needs to react to. Its body does exactly one thing: unconditionally set fields from the event's data.

For CustomerCreatedEvent, that means copying the event's customerId, name, and email straight onto the aggregate's own fields. Nothing in this method checks whether those values are valid — that check already happened, back in the @CommandHandler constructor that decided to apply this event in the first place. By the time this method runs, there is nothing left to decide.

This same method is what runs in two very different situations, and it's worth being clear about both. First, it runs immediately after AggregateLifecycle.apply() is called inside a command handler, updating the live, in-memory instance right away. Second — and this is the part covered in the next section — it also runs during a full replay, when Axon rebuilds a fresh aggregate instance from its complete event history before handling a brand-new command. The method's code is identical in both cases; it simply reacts to "this event happened" and updates fields accordingly, regardless of why it's being invoked right now.

@Aggregate
public class CustomerAggregate {

    @AggregateIdentifier
    private String customerId;
    private String name;
    private String email;

    // ... no-args constructor and @CommandHandler constructor from earlier ...

    @EventSourcingHandler
    public void on(CustomerCreatedEvent event) {
        // this method NEVER validates or rejects anything — the decision already happened
        this.customerId = event.getCustomerId();
        this.name = event.getName();
        this.email = event.getEmail();
    }
}

The same command-handler-plus-event-sourcing-handler pair repeats for every operation an aggregate supports, not just creation. An update follows the identical pattern: validate in the command handler, apply an event if valid, then unconditionally reflect that event's fields in the matching event sourcing handler.

Delete is a small but useful variation. Rather than nulling out fields by hand, Axon provides AggregateLifecycle.markDeleted(), called from inside the event sourcing handler reacting to the deletion event. This tells Axon the aggregate instance is now finished — any command arriving afterward for the same identifier is treated as targeting a deleted aggregate, rather than silently succeeding against a half-cleared instance.

Notice the pattern holding steady across all three operations: every command handler's only real job is deciding whether something is allowed and, if so, applying the matching event; every event sourcing handler's only job is unconditionally reflecting that already-decided change onto the instance's own fields. Once this pattern is familiar, adding a new operation to an aggregate is almost mechanical — write the command, write the event, write the pair of handlers, and the shape barely changes from one operation to the next.

@CommandHandler
public void handle(UpdateCustomerCommand command) {
    if (command.getName() == null || command.getName().isBlank()) {
        throw new IllegalArgumentException("name cannot be empty");
    }
    AggregateLifecycle.apply(new CustomerUpdatedEvent(customerId, command.getName(), command.getEmail()));
}

@EventSourcingHandler
public void on(CustomerUpdatedEvent event) {
    this.name = event.getName();
    this.email = event.getEmail();
}

@CommandHandler
public void handle(DeleteCustomerCommand command) {
    AggregateLifecycle.apply(new CustomerDeletedEvent(customerId));
}

@EventSourcingHandler
public void on(CustomerDeletedEvent event) {
    AggregateLifecycle.markDeleted(); // tells Axon this aggregate instance is now finished
}

The most common mistake at this stage is putting a business-rule check inside an @EventSourcingHandler method — for instance, throwing if a field looks wrong. Since this method also runs during a full replay of history, throwing here doesn't just reject one bad request; it can make the aggregate unable to load at all, because replay would hit the same exception on every future load too. Any check that could reasonably fail belongs strictly in the command handler, never here.

A second common worry, and a completely reasonable one, is that replaying potentially thousands of events on every single command sounds wildly inefficient. It's worth knowing Axon does cache aggregates in memory to avoid replaying on every command in rapid succession — but understanding the "replay from scratch" model as the underlying truth is essential groundwork, since it's what any further optimization is built on top of, not a replacement for it.