Understanding of Axon Event Sourcing

Question

I have been learning about axon and event sourcing and I think I have finally understood part of it and it makes sense in my head, but I want to make sure that my understanding of it is correct and that I am not making any mistakes. The code works, and I can see the events in my DOMAIN_EVENT_ENTRY table also.

I will post my code below (simple GiftCard example from the docs) and explain my thought process. If I have not understood it correctly, please could you help me on understanding that part in the correct way.

I've not included the commands/events as they are very simple with fields for id,amount

First my code:

TestRunner.java

package com.example.demoaxon;

import java.util.UUID;

import org.axonframework.commandhandling.gateway.CommandGateway;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import lombok.extern.slf4j.Slf4j;

@Component
@Slf4j
public class TestRunner implements CommandLineRunner {
    
    private final CommandGateway commandGateway;
    
    @Autowired
    public TestRunner(CommandGateway commandGateway) {
        this.commandGateway = commandGateway;
    }
    
    @Override
    public void run(String... args) throws Exception {
        log.info("send command");
        String id = UUID.randomUUID().toString();
        commandGateway.sendAndWait(new IssueCardCommand(id,100));
        commandGateway.sendAndWait(new RedeemCardCommand(id,90));
        
    }
}

GiftCard.java

package com.example.demoaxon;

import org.axonframework.commandhandling.CommandHandler;
import org.axonframework.eventsourcing.EventSourcingHandler;
import org.axonframework.modelling.command.AggregateIdentifier;
import static org.axonframework.modelling.command.AggregateLifecycle.apply;
import org.axonframework.spring.stereotype.Aggregate;

import lombok.NoArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@NoArgsConstructor
@Aggregate
@Slf4j
public class GiftCard {
    
    @AggregateIdentifier
    private String giftCardId;
    private Integer amount;
    
    @CommandHandler
    public GiftCard(IssueCardCommand cmd) {
        log.info("handling {}",cmd);
        apply(new CardIssuedEvent(cmd.getCardId(),cmd.getAmount()));
    }
    
    @EventSourcingHandler
    public void onCardIssuedEvent(CardIssuedEvent evt) {
        log.info("applying {}",evt);
        this.giftCardId = evt.getCardId();
        this.amount = evt.getAmount();
    }
    
    @CommandHandler
    public void redeemCardCommandHandler(RedeemCardCommand cmd) {
        log.info("handling {}",cmd);
        this.amount -= cmd.getAmount();
        apply(new CardRedeemedEvent(cmd.getCardId(),cmd.getTransactionId(),this.amount));
    }
    
    @EventSourcingHandler
    public void onCardRedeemedEvent(CardRedeemedEvent evt) {
        log.info("applying {}",evt);
        this.amount = evt.getAmount();
    }   
}

From what I can understand:

In my TestRunner class, the Command Gateway dispatches the issueCardCommand to it's CommandHandler using the command bus, which is then creating a new instance of the GiftCard aggregate. In this CommandHandler we can perform any logic, and then we use this apply method.
The apply(event) method is used to publish the CardIssuedEvent as an EventMessage within the scope of the GiftCard aggregate and it also invokes the EventSourcingHandler for that particular event, so in this case onCardIssuedEvent. It publishes the EventMessage to the EventBus and is sent to EventHandlers.
In the @EventSourcingHandler onCardIssuedEvent, we can make any state changes to the GiftCard aggregate and we are also persisting the event to the DOMAIN_EVENT_ENTRY table using spring Jpa.
Once this CommandHandler is finished executing, the aggregate object doesn't exist anymore.
Now in my TestRunner class again, the Command Gateway dispatches the RedeemCardCommand to its CommandHandler and as the first command no longer exists, the empty no args constructor is used to create the objects. The axon framework retrieves all events from this DOMAIN_EVENT_ENTRY table and it replays all the events (EventSourcingHandlers) for the GiftCard aggregate instance in order to get it's current state (which is why the @AggregateIdentifier is important).
The RedeemCardCommandHandler method is then executed, it performs any logic and applies the event, which is published within the aggregate and it invokes it's EventSourcingHandler. This EventSourcingHandler then updates the state of the GiftCard aggregate / persists to the DOMAIN_EVENT_ENTRYtable.

Is my understanding of how the event sourcing works correct?

Lucas Campos Lucas Campos · Accepted Answer · 2021-01-11T10:05:25

let me try to guide you through this journey!

Your understanding is almost completely correct. I would just like to split it into Event Sourcing and Axon for a better understanding.

Event Sourcing

In short, Event Sourcing is a way of storing an application’s state through the history of events that have happened in the past. Keep in mind that you have other patterns as well, for example State Stored Aggregates. In your example you are using Event Sourcing hence why @EventSourcingHandlers are in place. Now to the next topic.

Axon

I recommend you reading this awesome blog by one of our colleagues, specially the slide decks included on it, and you will see the journey of a message inside Axon Framework!

Now to your points, there are things I want to clarify upfront:

Correct, you dispatch a Command and since the method annotated is a constructor, it will create an Aggregate for you. CommandHanlders are the right place for business logic and validations.
Here the apply will publish the message internally (to this Aggregate but also to their Entities/AggregateMembers) and later on to the EventBus. From the javadoc:

The event should be applied to the aggregate immediately and scheduled for publication to other event handlers.

Since we are talking about Event Sourcing, all the EventSourcingHandlers will be called and the state of the Aggregate modified/updated. This is important because, as stated before, this is how you reconstruct your Aggregate state whenever needed. But the persisting of the Event does not occur here, it was already scheduled to happen when this process is done.
Correct.
Also correct. This has to do with Event Sourcing in general and how it reconstructs your Aggregate.
Also correct with the observations made on point 3, regarding when the Event is published/saved/persisted.

Another small side note on your code: you are doing this on your @CommandHandler

@CommandHandler
public void redeemCardCommandHandler(RedeemCardCommand cmd) {
    log.info("handling {}", cmd);
    this.amount -= cmd.getAmount(); // you should not do this here
    apply(new CardRedeemedEvent(cmd.getCardId(), cmd.getTransactionId(), this.amount));
}

This state change should be made in an @EventSourcingHandler. On the @CommandHandler you should only do validation if this Aggregate has enough 'money' to be redeemed :)

Understanding of Axon Event Sourcing

2 Answers