Axon Framework 5.0 to Axoniq Framework Migration

Axon Framework 5.1 extracts several production components into a dedicated commercial artifact: Axoniq Framework (io.axoniq.framework). Users on Axon Framework 5.0 who used features like Axon Server connectivity, distributed messaging or the Axon Server Testcontainer for testing need to update their dependencies and package imports.

Production use of these components additionally requires a license you can obtain via the AxonIQ Platform. Smaller organizations may be eligible for complimentary access to these components, for more information reach out to our sales team.

The following table summarizes the components affected by the reorganization of features:

Component Axon Framework 5.0 module Axoniq Framework 5.1 module

Axon Framework BOM

org.axonframework:axon-framework-bom

io.axoniq.framework:axoniq-framework-bom

Axon Spring Boot Starter

org.axonframework.extensions.spring:axon-spring-boot-starter

io.axoniq.framework:axoniq-spring-boot-starter

Axon Server connector

org.axonframework:axon-server-connector

io.axoniq.framework:axon-server-connector

Distributed messaging

org.axonframework:axon-messaging

io.axoniq.framework:axoniq-distributed-messaging

Axon Server Testcontainer

org.axonframework:axon-test

io.axoniq.framework:axoniq-testcontainer

Dependency management

If you are using the Axon Framework BOM, you can replace it with the Axoniq Framework BOM in your dependency management to keep module versions aligned. The Axoniq Framework BOM includes all Axon Framework BOM dependencies, so you do not need to include both.

  • Maven

  • Gradle

<!--...-->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.axoniq.framework</groupId>
            <artifactId>axoniq-framework-bom</artifactId>
            <version>${version.axon}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        ...

    </dependencies>
</dependencyManagement>
<!--...-->

For usage with Gradle Version 4.x and below, apply the dependency-management-plugin like so:

buildscript {
  repositories {
    jcenter()
  }
  dependencies {
    classpath "io.spring.gradle:dependency-management-plugin:0.5.1.RELEASE"
  }
}

apply plugin: "io.spring.dependency-management"

After this, import the Axon BOM:

dependencyManagement {
  imports {
    mavenBom 'io.axoniq.framework:axoniq-framework-bom:<VERSION>'
  }
}

Beginning with Gradle version 5.0, you can also omit the dependency-management plugin and instead use the platform dependency DSL to import maven BOMs:

implementation(platform("io.axoniq.framework:axoniq-framework-bom:<VERSION>"))

If you were using the Axon Spring Boot Starter, you can use the Axoniq Spring Boot Starter as a drop-in replacement, since it includes the Axon Spring Boot Starter entirely.

  • Maven

  • Gradle

<!-- Old -->
<dependency>
    <groupId>org.axonframework.extensions.spring</groupId>
    <artifactId>axon-spring-boot-starter</artifactId>
</dependency>

<!-- Drop-In replacement -->
<dependency>
    <groupId>io.axoniq.framework</groupId>
    <artifactId>axoniq-spring-boot-starter</artifactId>
</dependency>
// Old
implementation 'org.axonframework.extensions.spring:axon-spring-boot-starter'

// Drop-In replacement
implementation 'io.axoniq.framework:axoniq-spring-boot-starter'

Licensing

The Axoniq Framework features are commercial offerings requiring a license for production use. Licenses can be obtained through the AxonIQ Platform. Once you have platform credentials, configure them in your application:

  • Spring Boot

  • Plain Java

axoniq.platform.credentials=<environment-id>:<access-token>
import org.axonframework.config.EventSourcingConfigurer;
import io.axoniq.platform.framework.AxoniqPlatformConfiguration;

// Create and configure your application
AxoniqPlatformConfiguration platformConfig = new AxoniqPlatformConfiguration(
        "<environment-id>",
        "<access-token>",
        "<application-name>"
);

EventSourcingConfigurer configurer = EventSourcingConfigurer.create()
    .componentRegistry(cr -> cr.registerComponent(
        AxoniqPlatformConfiguration.class,
        c -> platformConfig
    ));

// Build and start the configuration
org.axonframework.config.Configuration configuration = configurer.buildConfiguration();
configuration.start();

During evaluation, Axoniq Framework modules start without credentials and log a warning. Continued production use without a valid license is not permitted under the Axoniq Terms of Service.

For more information on pricing, visit our pricing information page.

Note that smaller organizations may be eligible for complimentary access to Axoniq Framework components. For details about that, reach out to our sales team.

Axon Server connector

The Axon Server connector module has moved to Axoniq Framework. To migrate you need to replace the Axon Framework 5.0 dependency with the Axoniq Framework 5.1 one:

  • Maven

  • Gradle

<!-- Remove -->
<dependency>
    <groupId>org.axonframework</groupId>
    <artifactId>axon-server-connector</artifactId>
</dependency>

<!-- Add -->
<dependency>
    <groupId>io.axoniq.framework</groupId>
    <artifactId>axon-server-connector</artifactId>
</dependency>
// Remove
implementation 'org.axonframework:axon-server-connector'

// Add
implementation 'io.axoniq.framework:axon-server-connector'

If you have switched to using the Axoniq Spring Boot Starter dependency, you can omit the dependency, since it includes the Axon Server connector as the default connector.

Along with the maven module move, also the package structure of the Axon Server connector changed. First of all, the root package changed from org.axonframework.axonserver.connector to io.axoniq.framework.axonserver.connector. Apart from that, we also introduced an io.axoniq.framework.axonserver.connector.api package for more clarity. Consult the table below on details about what moved where:

Axon Framework 5.0 Axoniq Framework 5.1 Most Notable changes

o.a.a.connector

i.a.f.a.connector

Root package renamed

o.a.a.connector.*

i.a.f.a.connector.api.*

AxonServerConfiguration, AxonServerConnectionManager, AxonServerException, ConnectionManager and TagsConfiguration moved to *.api subpackage

o.a.a.connector.*

i.a.f.a.connector.shared.*

ErrorCode and MetadataConverter moved to *.shared subpackage

o.a.a.connector.util.*

i.a.f.a.connector.shared.*

ExceptionConverter and GrpcExceptionParser moved to *.shared subpackage

o.a.a.connector.command.*

i.a.f.a.connector.api.command.*

all Exceptions moved to the *.api.command subpackage

o.a.a.connector.query.*

i.a.f.a.connector.api.query.*

all Exceptions moved to the *.api.query subpackage

Distributed messaging

DistributedCommandBus and DistributedQueryBus, along with their configuration records, have moved from axon-messaging to the dedicated axoniq-distributed-messaging module.

Add the new dependency:

  • Maven

  • Gradle

<dependency>
    <groupId>io.axoniq.framework</groupId>
    <artifactId>axoniq-distributed-messaging</artifactId>
</dependency>
implementation 'io.axoniq.framework:axoniq-distributed-messaging'

Along with the maven module move, also the package structure changed, so you need to update any use of the following packages:

Axon Framework 5.0 Axoniq Framework 5.1

org.axonframework.messaging.commandhandling.distributed

io.axoniq.framework.messaging.commandhandling.distributed

org.axonframework.messaging.queryhandling.distributed

io.axoniq.framework.messaging.queryhandling.distributed

Apart from that package move, the field names and method signatures of classes within those packages remain unchanged.

Axon Server testcontainer

AxonServerContainer has moved from axon-test to a dedicated axoniq-testcontainer module. To continue using it, replace the dependency and update the import:

  • Maven

  • Gradle

<!-- Remove (or reduce to test scope only if you use other axon-test features) -->
<dependency>
    <groupId>org.axonframework</groupId>
    <artifactId>axon-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- Add -->
<dependency>
    <groupId>io.axoniq.framework</groupId>
    <artifactId>axoniq-testcontainer</artifactId>
    <scope>test</scope>
</dependency>
// Remove (or reduce scope if you use other axon-test features)
testImplementation 'org.axonframework:axon-test'

// Add
testImplementation 'io.axoniq.framework:axoniq-testcontainer'

Update the imports:

Axon Framework 5.0 Axoniq Framework 5.1

org.axonframework.test.server.AxonServerContainer

io.axoniq.framework.testcontainer.AxonServerContainer

org.axonframework.test.server.AxonServerContainerUtils

io.axoniq.framework.testcontainer.AxonServerContainerUtils