Data Protection Module Migration

This guide covers how to migrate from Axon Data Protection 4.x to 5.x. Axon Data Protection 5.x has been redesigned to align with Axon Framework 5.x, bringing changes to module coordinates, the core API, and licensing.

See the Data Protection overview for the full reference, including guides on annotations, configuration, crypto engines, and advanced topics.

Module coordinate and package changes

The module coordinates have changed from 4.x to 5.x. Update your pom.xml dependency as follows:

Data Protection 4
Data Protection 5

<dependency>
    <groupId>io.axoniq.dataprotection</groupId>
    <artifactId>axon-data-protection-axon4</artifactId>
</dependency>

<dependency>
    <groupId>io.axoniq.framework</groupId>
    <artifactId>axoniq-data-protection</artifactId>
</dependency>

Additionally, the base package has changed from io.axoniq.dataprotection to io.axoniq.framework.dataprotection. Hence, you are required to update your imports accordingly.

Here’s an example NewCustomerEvent in version 4 and version 5 with the imports adjusted accordingly:

Data Protection 4
Data Protection 5

import io.axoniq.dataprotection.api.DataSubjectId;
import io.axoniq.dataprotection.api.PersonalData;

public class NewCustomerEvent {
    @DataSubjectId
    private int id;

    @PersonalData
    private String name;
}

import io.axoniq.framework.dataprotection.api.DataSubjectId;
import io.axoniq.framework.dataprotection.api.PersonalData;

public class NewCustomerEvent {
    @DataSubjectId
    private int id;

    @PersonalData
    private String name;
}

Serializer to converter

Axon Framework 5.x replaced the Serializer abstraction with the Converter API. In line with this change, the FieldEncryptingSerializer has been replaced by the FieldEncryptingConverter.

Where you previously configured a FieldEncryptingSerializer wrapping an Axon Serializer, you now configure a FieldEncryptingConverter wrapping an Axon Converter. The example below shows a serializer creation method and converter creation method, in v4 and v5 of the Data Protection module respectively. Note that these methods can be annotated with @Bean to make them Spring compliant!

Data Protection 4
Data Protection 5

import com.fasterxml.jackson.databind.ObjectMapper;
import io.axoniq.dataprotection.api.FieldEncryptingSerializer;
import io.axoniq.dataprotection.cryptoengine.CryptoEngine;
import org.axonframework.serialization.Serializer;
import org.axonframework.serialization.json.JacksonSerializer;

class AxonConfig {

    public Serializer serializer(CryptoEngine cryptoEngine,
                                 ObjectMapper objectMapper) {
        Serializer delegateSerializer = JacksonSerializer.builder()
                                                         .objectMapper(objectMapper)
                                                         .build();
        return new FieldEncryptingSerializer(cryptoEngine, delegateSerializer);
    }
}

import io.axoniq.framework.dataprotection.api.FieldEncryptingConverter;
import io.axoniq.framework.dataprotection.cryptoengine.CryptoEngine;
import org.axonframework.conversion.Converter;
import org.axonframework.conversion.DelegatingGeneralConverter;
import org.axonframework.conversion.GeneralConverter;
import org.axonframework.conversion.jackson.JacksonConverter;
import tools.jackson.databind.ObjectMapper;

class AxonConfig {

    public GeneralConverter converter(CryptoEngine cryptoEngine,
                                      ObjectMapper objectMapper) {
        Converter jacksonConverter = new JacksonConverter(objectMapper);
        FieldEncryptingConverter fieldEncryptingConverter =
                new FieldEncryptingConverter(cryptoEngine, jacksonConverter);
        return new DelegatingGeneralConverter(fieldEncryptingConverter);
    }
}

For more details on the Serializer-to-Converter migration in Framework, we refer to the dedicated Framework migration path.

License entitlement

Licensing for the Data Protection module changed compared to version 4. Hence, if you used the Data Protection module before, you are not able to reuse your previous license. Instead, you will have to request a new one from your Axoniq representative.

When you’re entirely new to this module, be sure to retrieve an active subscription, as detailed in the installation guide.