event-versioning.md

Event Versioning

In the lifecycle of an Axon application events will typically change their format. As events are stored indefinitely the application should be able to cope with several versions of an event. This chapter will discuss what to keep in mind when creating your events, for backwards (and forwards) compatibility. It will also explain the upcasting process.

Event Upcasting

Due to the ever-changing nature of software applications it is likely that event definitions will also change over time. Since the Event Store is considered a read and append-only data source, your application must be able to read all events, regardless of when they were added. This is where upcasting comes in.

Originally a concept of object-oriented programming, where "a subclass gets cast to its superclass automatically when needed", the concept of upcasting can also be applied to event sourcing. To upcast an event means to transform it from its original structure to its new structure. Unlike OOP upcasting, event upcasting cannot be done in full automation because the structure of the new event is unknown to the old event. Manually written upcasters have to be provided to specify how to upcast the old structure to the new structure.

Upcasters are classes that take one input event of revision x and output zero or more new events of revision x + 1. Moreover, upcasters are processed in a chain, meaning that the output of one upcaster is sent to the input of the next. This allows you to update events in an incremental manner, writing an upcaster for each new event revision, making them small, isolated, and easy to understand.

Note

Perhaps the greatest benefit of upcasting is that it allows you to do non-destructive refactoring. In other words, the complete event history remains intact.

In this section we'll explain how to write an upcaster, describe the different (abstract) implementations of the Upcaster that come with Axon, and explain how the serialized representations of events affects how upcasters are written.

To allow an upcaster to see what version of serialized object they are receiving, the Event Store stores a revision number as well as the fully qualified name of the Event. This revision number is generated by a RevisionResolver, configured in the serializer. Axon provides several implementations of the RevisionResolver:

1. The AnnotationRevisionResolver checks for an @Revision annotation on the Event payload.

2. The SerialVersionUIDRevisionResolver uses the serialVersionUID as defined by Java Serialization API.

3. The FixedValueRevisionResolver always returns a predefined value. This is particularly useful when injecting the current application version.

   It would allow you to see which version of the application generated a specific event.

4. Maven users can use the MavenArtifactRevisionResolver to automatically use the project version.

   It is initialized using the groupId and artifactId of the project to obtain the version for.

   Since this only works in JAR files created by Maven, the version cannot always be resolved by an IDE.

   If a version cannot be resolved, null is returned.

Axon's upcasters do not work with the EventMessage directly, but with an IntermediateEventRepresentation. The IntermediateEventRepresentation provides functionality to retrieve all necessary fields to construct an EventMessage (and thus a upcasted EventMessage too), together with the actual upcast functions. These upcast functions by default only allow the adjustment of the event's payload, payload type and additions to the event's metadata. The actual representation of the events in the upcast function may vary based on the event serializer used or the desired form to work with, so the upcast function of the IntermediateEventRepresentation allows the selection of the expected representation type. The other fields, for example the message/aggregate identifier, aggregate type, timestamp etc. are not adjustable by the IntermediateEventRepresentation. Adjusting those fields is not the intended work for an upcaster. As such, those options are not provided by the provided IntermediateEventRepresentation implementations.

The basic Upcaster interface for events in the Axon Framework works on a Stream of IntermediateEventRepresentations and returns a Stream of IntermediateEventRepresentations. The upcasting process thus does not directly return the end result of the introduced upcast functions, but chains every upcasting function from one revision to another together by stacking IntermediateEventRepresentations. Once this process has taken place and the end result is pulled from them, that is when the actual upcasting function is performed on the serialized event.

Conversion Notice

Sometimes the event store can contain events in different serialized formats, since differing Serializer implementations where used.

During upcasting it is important to note what the format is of the IntermediateEventRepresentation, as it influences the upcaster solution provided. To validate if the intermediate representation supports a given type, you can invoke IntermediateEventRepresentation#canConvertDataTo(Class<?>).

Provided abstract Upcaster implementations

As described earlier, the Upcaster interface does not upcast a single event; it requires a Stream<IntermediateEventRepresentation> and returns one. However, an upcaster is usually written to adjust a single event out of this stream. More elaborate upcasting setups are also imaginable. For example from one event to multiple, or an upcaster which pulls state from an earlier event and pushes it in a later one. This section describes the currently provided (abstract) implementations of event upcasters which a user can extend to add their own desired upcast functionality.

• SingleEventUpcaster - a one-to-one implementation of an event upcaster. Extending from this implementation requires one to implement a canUpcast and doUpcast function, which respectively check whether the event at hand is to be upcasted, and if so how it should be upcasted. This is most likely the implementation to extend from, as most event adjustments are based on self contained data and are one to one.
• EventMultiUpcaster - a one-to-many implementation of an event upcaster. It is mostly identical to a SingleEventUpcaster, with the exception that the doUpcast function returns a Stream instead of a single IntermediateEventRepresentation. As such, this upcaster allows you to convert a single event to several events. This might be useful if you for example have figured out you want more fine grained events from a fat event.
• ContextAwareSingleEventUpcaster - a one-to-one implementation of an upcaster, which can store context of events during the process. Next to the canUpcast and doUpcast, the context aware upcaster requires one to implement a buildContext function, which is used to instantiate a context which is carried between events going through the upcaster. The canUpcast and doUpcast functions receive the context as a second parameter, next to the IntermediateEventRepresentation. The context can then be used within the upcasting process to pull fields from earlier events and populate other events. It thus allows you to move a field from one event to a completely different event.
• ContextAwareEventMultiUpcaster - a one-to-many implementation of an upcaster, which can store context of events during the process. This abstract implementation is a combination of the EventMultiUpcaster and ContextAwareSingleEventUpcaster, and thus services the goal of keeping context of IntermediateEventRepresentations and upcasting one such representation to several. This implementation is useful if you not only want to copy a field from one event to another, but have the requirement to generate several new events in the process.
• EventTypeUpcaster - a full upcaster implementation dedicated to changing the event type. The EventTypeUpcaster is an implementation of the SingleEventUpcaster with predefined canUpcast and doUpcast functions to be able to change an event from one event type to another. This can be used to for example change the class or package name of an event with ease. To create an EventTypeUpcaster, it is recommended to use the EventTypeUpcaster#from(String expectedPayloadType, expectedRevision) and EventTypeUpcaster.Builder#to(upcastedPayloadType, upcastedRevision) methods.

What's a part of the context in a Context-Aware Upcasters?

A context-aware upcaster allows you to collect state from previous events. As upcasters work on a stream of events, all that can ever belong to the context, is the state from that stream.

However, this "stream of events" is not identical at all times. For example, when an aggregate is event-sourced, the event stream consists of aggregate instance-specific events. Furthermore, the stream of events starts from the tracking token's position for a Streaming Event Processor. Hence, the context contains different state depending on what's included in the event stream.

Writing an Upcaster

The following Java snippets will serve as a basic example of a one-to-one upcaster (the SingleEventUpcaster).

Old version of the event:

@Revision("1.0")
public class ComplaintEvent {
    private String id;
    private String companyName;

    // Constructor, getter, setter...
}

New version of the event:

@Revision("2.0")
public class ComplaintEvent {
    private String id;
    private String companyName;
    private String description; // New field

    // Constructor, getter, setter...
}

Upcaster from 1.0 revision to 2.0 revision:

{% tabs %} {% tab title="Event serialized with XStream" %}

public class ComplaintEvent1_to_2Upcaster extends SingleEventUpcaster {

   private static final SimpleSerializedType TARGET_TYPE =
           new SimpleSerializedType(ComplaintEvent.class.getTypeName(), "1.0");

   @Override
   protected boolean canUpcast(IntermediateEventRepresentation intermediateRepresentation) {
      return intermediateRepresentation.getType().getName().equals(TARGET_TYPE.getName())
            && intermediateRepresentation.getType().getRevision().equals(TARGET_TYPE.getRevision());
   }

   @Override
   protected IntermediateEventRepresentation doUpcast(
           IntermediateEventRepresentation intermediateRepresentation
   ) {
      return intermediateRepresentation.upcastPayload(
              new SimpleSerializedType(TARGET_TYPE.getName(), "2.0"),
              org.dom4j.Document.class,
              document -> {
                 document.getRootElement()
                         .addElement("description")
                         .setText("no complaint description"); // Default value
                 return document;
              }
      );
   }
}

{% endtab %}

{% tab title="Event serialized with Jackson" %}

public class ComplaintEvent1_to_2Upcaster extends SingleEventUpcaster {
   // upcaster implementation...

   private static final SimpleSerializedType TARGET_TYPE =
           new SimpleSerializedType(ComplaintEvent.class.getTypeName(), "1.0");

   @Override
   protected boolean canUpcast(IntermediateEventRepresentation intermediateRepresentation) {
      return intermediateRepresentation.getType().getName().equals(TARGET_TYPE.getName())
            && intermediateRepresentation.getType().getRevision().equals(TARGET_TYPE.getRevision());
   }

   @Override
   protected IntermediateEventRepresentation doUpcast(
           IntermediateEventRepresentation intermediateRepresentation
   ) {
      return intermediateRepresentation.upcastPayload(
              new SimpleSerializedType(TARGET_TYPE.getName(), "2.0"),
              com.fasterxml.jackson.databind.JsonNode.class,
              event -> { 
                  ((ObjectNode) event).put("description", "no complaint description");
                  return event;
              }
      );
   }
}

{% endtab %} {% endtabs %}

Configuring an Upcaster

After choosing an upcaster type and constructing your first instance, it is time to configure it in your application. Important in the configuration is knowing that upcasters need to be invoked in order. Events tend to move through several format iterations, each with its own upcasting requirements. Since an upcaster only adjusts an event from one version to another, it is paramount to maintain the ordering of the upcasters.

The component in charge of that ordering is the EventUpcasterChain. The upcaster chain is what the EventStore uses to attach all the upcast functions to the event stream.

When configuring your upcasters, most scenarios will not require you to touch the EventUpcasterChain directly. Instead, consider the following snippets when it comes to registering upcasters:

{% tabs %} {% tab title="Axon Configuration API" %}

@Configuration
public class AxonConfig {
    // omitting other configuration methods...
    public void configureUpcasters(Configurer configurer) {
        // The method invocation order imposes the upcaster ordering
        configurer.registerEventUpcaster(config -> new ComplaintEvent0_to_1Upcaster())
                  .registerEventUpcaster(config -> new ComplaintEvent1_to_2Upcaster());
    }
}

{% endtab %}

{% tab title="Auto Configuration - @Order annotation" %} Axon honors Spring's Order annotation on upcasters. The numbers used in the annotation will dictate the ordering. The lower the number, the earlier it is registered to the upcaster chain:

@Component
@Order(0)
public class ComplaintEvent0_to_1Upcaster extends SingleEventUpcaster {
   // upcaster implementation...

}

@Component
@Order(1)
public class ComplaintEvent1_to_2Upcaster extends SingleEventUpcaster {
   // upcaster implementation...

}

The annotation can be placed both on the class itself, or on bean creation methods:

@Configuration
public class AxonConfig {
    // omitting other configuration methods...
    @Bean
    @Order(0)
    public SingleEventUpcaster complaintEventUpcasterOne() {
        return new ComplaintEvent0_to_1Upcaster();
    }
 
    @Bean
    @Order(1)
    public SingleEventUpcaster complaintEventUpcasterTwo() {
        return new ComplaintEvent0_to_1Upcaster();
    }
}

{% endtab %}

{% tab title="Auto Configuration - EventUpcasterChain bean" %} Adding an EventUpcasterChain bean to the Application Context will tell Axon to configure it for your event source:

@Configuration
public class AxonConfig {
    // omitting other configuration methods...
    @Bean
    public EventUpcasterChain eventUpcasterChain() {
        return new EventUpcasterChain(
                new ComplaintEvent0_to_1Upcaster(),
                new ComplaintEvent0_to_1Upcaster()
        );
    }
}

{% endtab %} {% endtabs %}