Axonframework: @TargetAggregateVersion @AggregateVersion documentation / examples ?

[benneq]

I'm trying to implement optimistic locking with Axon using event sourcing. But I can't find any reliable source of documentation / examples about how to correctly use @AggregateVersion and @TargetAggregateVersion.

Google Search for axon "@AggregateVersion" or axon "@TargetAggregateVersion" (you can also exchange axon for axon-framework or axonframework) doesn't give any useful information.

Within the Reference Guide ( https://docs.axonframework.org/ ) I couldn't find any useful examples.

---

I have the following questions:

1. Does Axon automatically increase the version counter?

   • If "yes": When does this happen exactly? How can I control it (prevent it or set a custom version number)?
   • If "no": Should I simply use apply(new MyEvent(command.getId(), command.getVersion() + 1)) and then set this.version = event.getVersion() within every event handler?

2. Do I have to use Long or can I use long for the aggregate's version?

3. How to return the version after processing a command using commandGateway.send? (In order to tell the user the new current version after he has modified the aggregate. So he has the correct version number for the next command.)

4. Best practices / example code: Should the resulting event object contain the version number? What about if my command applies multiple events?

---

Thanks in advance.

[benneq]

If anyone else is looking for those answers:

1. Axon automatically sets and increases the aggregate's @AggregateVersion field. There's no interaction with this field required: Just add it to your aggregate and you're done.

2. long and Long seem both to work fine.

3. I'm NOT sure if that's the best solution or just a workaround: Your Command objects contain @TargetAggregateVersion. Though you can simply return command.getVersion() + 1 from your @CommandHandler method. And then receive this value from commandGateway.send or commandGateway.sendAndWait.

4. Each method that is annotated with @EventSourcingHandler can inject some special arguments. For example: @SequenceNumber long version and @Timestamp Instant timestamp. There's no need to add a long version to your Event class. Axon automatically saves the timestamp and version counter along with your event data.

---

@Aggregate
public class MyAggregate {
    @AggregateIdentifier private String id;
    @AggregateVersion private long version;

    @CommandHandler
    public MyAggregate(CreateMyAggregateCommand command) {
        apply(new MyAggregateCreatedEvent(command.getId()));
    }

    @CommandHandler
    public void handle(ModifyMyAggregateCommand command) {
        apply(new MyAggregateModifiedEvent(command.getId()));
        return command.getVersion() + 1;
    }

    // ...
}

public class ModifyMyAggregateCommand {
    @TargetAggregateIdentifier private final String id;
    @TargetAggregateVersion private final long version;
    // ... constructor, getters
}

public class MyAggregateModifiedEvent {
    private String id;
    // ... constructor, getters
}

public MyQueryModelEventHandler {
    @EventSourcingHandler
    public void on(MyAggregateModifiedEvent event, @SequenceNumber long version, @Timestamp Instant timestamp) {
        // ...
    }
}

---

I still would like to see some clarification concerning 3..

[smcvb]

Thanks for filing your concern in regards to missing documentation around the @TargetAggregeteVersion/@AggregateVersion annotations and their usages, @benneq.

I'd however like to ask you if you could file it on the Reference Guide repository instead, as that is the place where we document our issues in regards to documentation.

Due to the fact this issue should be part of another repo, I'll be closing it for now.

[benneq]

I have to correct myself for 3.: Don't return command.getVersion() + 1!

Instead use return AggregateLifecycle.getVersion(). This will track how many events have been applied. So if your command generates an unknown number of events, you don't have to keep track of the version increase yourself.