Migration Paths
Axon Framework 5 introduces several architectural shifts that may require different migration strategies depending on your application’s complexity and the features you use. This section outlines the common migration tasks and provides detailed "paths" for specific components.
Whether you are performing a straightforward version bump or a deep architectural refactoring to embrace Dynamic Consistency Boundaries (DCB), the following sections will guide you through the process.
-
Base Migration Changes
-
Import and Package Changes
-
Module Restructuring
-
-
Specific Migration Paths
-
Message changes [@EventTag,@Event/@Command/@Query] (Coming soon)
-
Aggregate to Entity (Coming soon)
-
Event Processor configuration in AF5 (Coming soon)
-
Test fixtures (Coming soon)
-
Serializer to Converter configuration changes (Coming soon)
-
ConfigurerModule to ConfigurationEnhancers (Coming soon)
-
Message Interceptors in AF5 (Coming soon)
-
-
What is not yet there
-
Missing a Migration Path?
Base migration changes
Every user migrating from Axon Framework 4.x to 5.x will encounter a set of base changes. These primarily involve package renames and module restructurings.
Import and package changes
Many classes have been moved to better align with the new modular structure. The most notable change is the move of Spring-specific and monitoring components into their own extension namespaces, and the nesting of core messaging components under the org.axonframework.messaging package.
-
Framework
-
Extension
| Description | Changes (AF4 to AF5) |
|---|---|
Command Handler annotation |
to
|
Event Handler annotation |
to
|
Query Handler annotation |
to
|
Message Handler Interceptor annotation |
to
|
Configuration API |
to
|
Serialization API (replaced by Conversion) |
to
|
Command Handling Core |
to
|
Event Handling Core |
to
|
Query Handling Core |
to
|
Unit of Work |
to
|
Modelling (Aggregates to Entities) |
to
|
Target Entity Id annotation |
to
|
| Description | Changes (AF4 to AF5) |
|---|---|
Core Spring support |
to
|
Spring Boot auto-configuration |
to
|
Spring Boot Actuator support |
to
|
Dropwizard Metrics support |
to
|
Micrometer support |
to
|
OpenTelemetry support |
to
|
For an exhaustive list of all class-level renames and moves, please refer to the api-changes.md file in the root of the Axon Framework repository.
Module restructuring
Axon Framework 5 has been restructured into more focused modules. This allows for better dependency management and smaller deployment footprints. The following table provides an exhaustive list of the modules available in Axon Framework 5 and their Axon Framework 4 equivalents.
| Description | Axon 4 module name | Axon 5 module name |
|---|---|---|
New. Contains shared utilities, configuration basics, and common exceptions. |
N/A |
|
New. Contains the new |
N/A |
|
Remains the core messaging module. |
|
|
Contains the logic for entities (formerly aggregates) and repositories. |
|
|
Focused on event sourcing logic and event store implementations. |
|
|
Connectivity for Axon Server. |
|
|
Testing infrastructure and fixtures. |
|
|
New. Provides automated update support and migration utilities. |
N/A |
|
Core Spring Framework integration. |
|
|
Spring Boot auto-configuration support. |
|
|
Spring Boot starter for Axon. |
|
|
Dropwizard Metrics integration. |
|
|
Micrometer integration. |
|
|
OpenTelemetry tracing support. |
|
|
Users should update their dependency management (Maven/Gradle) to reflect these changes. Note that the modules in extensions have moved to a different group ID (org.axonframework.extensions.*) as well.
Axon Framework BOM
For ease of dependency management, it is highly recommended to use the Axon Framework Bill of Materials (BOM). This ensures that all Axon modules in your project use the same compatible version.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.axonframework</groupId>
<artifactId>axon-framework-bom</artifactId>
<version>${axon.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>What is not yet there
As Axon Framework 5.0 is the first step in this new major version, not all features from the 4.x lineage have been fully migrated or redesigned yet.
-
Saga & Deadline Overhaul: Sagas and Deadlines do not have a native "async-native" replacement yet. A full redesign is in progress.
-
Event Upcasters: Event upcasting is not yet available.
-
Snapshots: The snapshotting feature for entities is not yet available. Currently scheduled for 5.1.
-
Dead-Letter Queue (DLQ): Support for DLQs in event processors is not yet available.
-
Event Replaying: The ability to replay events for streaming event processors is not yet implemented.
-
Multiple Event Sources:
MultiStreamableEventSourcesupport is not yet available. Currently scheduled for 5.1. -
Annotated Features (Coming in 5.2.0):
-
Timeouts: Built-in timeout support for message handlers and processing contexts.
-
Interceptors: Declarative and annotated interceptor support for message handling components.
-
Exception Handling: Annotated exception handling support (
@ExceptionHandler).
-
-
Extensions: Specialized external extensions are not yet migrated to support Axon Framework 5.x yet. As these are community-driven, their availability may vary.
If your application relies heavily on these features, we recommend checking the release notes for future 5.x versions or contacting us for guidance.
Missing a migration path?
We aim to cover the most common migration scenarios in the following subsections. However, every application is unique.
If you find that your specific migration challenge is not addressed here, or if you encounter an undocumented breaking change, please:
-
Contact Us: Reach out via the Axon Community Forum.
-
Open an Issue: Let us know by opening a documentation issue on our GitHub repository.
Your feedback helps us make this guide better for everyone!