4. Domain Modeling

In Axon, all aggregate roots must implement the AggregateRoot interface. This interface describes the basic operations needed by the Repository to store and publish the generated domain events. However, Axon Framework provides a number of abstract implementations that help you writing your own aggregates.

The AbstractAggregateRoot is a basic implementation that provides a registerEvent(DomainEvent) method that you can call in your business logic method to have an event added to the list of uncommitted events. The AbstractAggregateRoot will keep track of all uncommitted registered events and make sure they are forwarded to the event bus when the aggregate is saved to a repository.

The interface EventSourcedAggregateRoot defines an extra method, initializeState(), on top of the AggregateRoot interface. This method initializes an aggregate's state based on an event stream.

Implementations of this interface must always have a default no-arg constructor. Axon Framework uses this constructor to create an empty Aggregate instance before initialize it using past Events. Failure to provide this constructor will result in an Exception when loading the Aggregate from a Repository.

The AbstractEventSourcedAggregateRoot implements all methods on the EventSourcedAggregateRoot interface, except getIdentifier(). It defines an abstract handle() method, which you need to implement with the actual logic to apply state changes based on domain events, and getChildEntities(), which you can use to declare the entities that are member of this aggregate. When you extend the AbstractEventSourcedAggregateRoot, you can register new events using apply(). This method will register the event to be committed when the aggregate is saved, and will call the handle() method with the event as parameter. You need to implement this handle() method to apply the state changes represented by that event. Below is a sample implementation of an aggregate.

public class MyAggregateRoot extends AbstractEventSourcedAggregateRoot<String> {

    private String aggregateIdentifier;
    private String someProperty;

    public MyAggregateRoot(String id) {
        apply(new MyAggregateCreatedEvent(id));
    }

    // constructor required for reconstruction
    protected MyAggregateRoot() {
    }

    protected void handle(DomainEventMessage eventMessage) {
        if (MyAggregateCreatedEvent.class.isAssignableFrom(eventMessage.getPayloadType())) {
            // make sure to always initialize the aggregate identifier
            this.aggregateIdentifier = ((MyAggregateCreatedEvent) eventMessage.getPayload()).getMyIdentifier();
            // do something with someProperty
        }
        // and more if-else-if logic here
    }

    public String getIdentifier() {
        return aggregateIdentifier;
    }

    @Override
    protected Iterable<? extends EventSourcedEntity> getChildEntities() {
        return Collections.emptyList();
    }
}                

As you see in the example above, the implementation of the handle() method can become quite verbose and hard to read. The AbstractAnnotatedAggregateRoot can help. The AbstractAnnotatedAggregateRoot is a specialization of the AbstractAggregateRoot that provides @EventSourcingHandler annotation support to your aggregate. Instead of a single handle() method, you can split the logic in separate methods, with names that you may define yourself. Just annotate the event handler methods with @EventSourcingHandler, and the AbstractAnnotatedAggregateRoot will invoke the right method for you.

public class MyAggregateRoot extends AbstractAnnotatedAggregateRoot {

    @AggregateIdentifier
    private String aggregateIdentifier;
    private String someProperty;

    public MyAggregateRoot(String id) {
        apply(new MyAggregateCreatedEvent(id));
    }

    // constructor needed for reconstruction
    protected MyAggregateRoot() {
    }

    @EventSourcingHandler
    private void handleMyAggregateCreatedEvent(MyAggregateCreatedEvent event) {
        // make sure identifier is always initialized properly
        this.aggregateIdentifier = event.getMyAggregateIdentifier();
        // do something with someProperty
    }
}                

@EventSourcingHandler annotated methods are resolved using specific rules. These rules are the same for the @EventHandler annotated methods, and are thoroughly explained in Section 6.2.2, “Annotated Event Handler”.

The AbstractAnnotatedAggregateRoot also requires that the field containing the aggregate identifier is annotated with @AggregateIdentifier. If you use JPA and have JPA annotations on the aggregate, Axon can also use the @Id annotation provided by JPA.

In some cases, especially when aggregate structures grow beyond just a couple of entities, it is cleaner to react on events being published in other entities of the same aggregate. However, since Event Handler methods are also invoked when reconstructing aggregate state, special precautions must be taken.

Since Axon 2.3, it is possible to apply() new events inside an Event Handler method. This makes it possible for an Entity B to apply an event in reaction to Entity A doing something. Axon will ignore the apply() invocation when replaying historic events.

You can also use the isLive() (if you extend the AbstractEventSourcedAggregateRoot), to check whether the aggregate is 'live'. Basically, an aggregate is considered live if it has finished replaying historic events. While replaying these events, isLive() will return false. Using this isLive() method, you can perform activity that should only be done when handling newly generated events.