# 事件版本控制 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` 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](/axon-framework/events/event-processors/streaming.md#tracking-tokens) position for a [Streaming Event Processor](/axon-framework/events/event-processors/streaming.md). 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: ```java @Revision("1.0") public class ComplaintEvent { private String id; private String companyName; // Constructor, getter, setter... } ``` New version of the event: ```java @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" %} ```java 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().equals(TARGET_TYPE); } @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" %} ```java 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().equals(TARGET_TYPE); } @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" %} ```java @Configuration public class AxonConfig { // ... 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: ```java @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: ```java @Configuration public class AxonConfig { // ... @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: ```java @Configuration public class AxonConfig { // ... @Bean public EventUpcasterChain eventUpcasterChain() { return new EventUpcasterChain( new ComplaintEvent0_to_1Upcaster(), new ComplaintEvent0_to_1Upcaster() ); } } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://axon-cn.ahoo.me/axon-framework/events/event-versioning.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.