When to write an Upcaster for an Axon event?

Question

I'm using Axon Framework and Spring Boot, I have only added one field to an event and I'm not sure if I should write an upcaster and change the revision number or not.

As far as I know, I should only write an upcaster and change the revision number if I deleted or modified one of the event fields. Someone helps please, thanks

What I tried is I deleted all my event store tokens and spin up the application, which will automatically replay all events, and I didn't have any problems.

Answer 1

The rule of thumb when it comes to writing an Upcaster, is to validate whether the original format fits without changes into the new format.

This means that added fields may require an upcaster, if you cannot easily provide a default field for the new field.

This holds, as when you load the original version of the event, while the event object expects this new field to be present, your application simply needs a way to know what value that field should carry.

It is here where an upcaster may help. Let me give you an example too. First, we start with the original serialized format of an event called FlightDelayedEvent:

{
 "flightId": "123",
 "leg": {
   "from": "AMS",
   "to": "LAX"
 },
 "arrivalTime": "10:30"
}

We can see the event has an identifier for the flight, an arrival time for the flight, and a so-called "leg," which contains the from and to destinations of a flight.

However, the team decided the Leg object has to go, because (for example) we want to have fewer value objects in our events.

Knowing this, we can take a look at what the changed version would look like:

{
 "flightId": "123",
 "start": "AMS",
 "destination": "LAX",
 "arrivalTime": "10:30"
}

From the difference in the serialized format, we can already anticipate that the serializer would not be able to deserialize the old event if the expected format is the second. Hence, this scenario would call for an upcaster, to move the from and to fields that are in the leg object, into the destination and arrival fields.

So, if we circle back to your original question:

As far as I know, I should only write an upcaster and change the revision number if I deleted or modified one of the event fields.

This isn't necessarily the rule of thumb to look at if you ask me. Your best bet is to think about the serialized format you have right now, and what you want to change it to.

Hence, I would suggest you to look at your current serialized format and what you want it to be. If you need an extra hand with that, you can always update your question with the concrete serialized format you have right now and what it should be come.

And, I have a little side note based on your last sentence:

What I tried is I deleted all my event store tokens and spin up the application, which will automatically replay all events, and I didn't have any problems.

I would not recommend to delete your token_entry table ever to be honest. It may act as an replay, but Axon Framework doesn't know you are doing a replay in that case. If you want Axon Framework to perform a conscious replay (so that you can use the API as defined here), you should trigger a replay on the StreamingEventProcessor instance you want to replay.

To achieve that, you can use the API to trigger a reset, or simpler, connect your application AxonIQ Console to enable the Event Processor management dashboard.