Upgrade to Micronaut Framework 4
by Sergio Del Amo CaballeroThis post is a migration guide to Micronaut framework 4.0.
You can read about What’s new in Micronaut Framework 4.0 and its breaking changes to learn more about this recent release.
Gradle Applications
Version update
Set micronautVersion
property in gradle.properties
.
micronautVersion=4.0.0-M2
Update Gradle to 8
Micronaut framework 4 applications generated via the Micronaut CLI or Micronaut Launch use Gradle 8.1.1
. Micronaut framework 3.x applications use Gradle 7.6. Upgrade your build from Gradle 7.x to 8.0.
Update Micronaut Gradle plugins to 4.x
Update Micronaut Gradle Plugin to 4.0.0-M2
.
Replace:
plugins {
id("io.micronaut.application") version "3.7.9"
With:
plugins {
id("io.micronaut.application") version "4.0.0-M2"
Update Shadow plugin
Update Shadow Gradle Plugin to 8.1.1
. Replace
Replace:
plugins {
id("com.github.johnrengelman.shadow") version "7.1.2"
With:
plugins {
id("com.github.johnrengelman.shadow") version "8.1.1"
Kotlin Gradle Plugins
If you write your Micronaut applications with Kotlin, you need to update your Gradle plugins.
kapt Gradle Plugin
Update kapt gradle plugin from 1.6.21
to 1.8.21
.
Micronaut Framework 4.0 supports Kotlin Symbol Processing (KSP). We recommend you migrate from kapt to ksp.
All-open Gradle Plugin
Update Kotlin All-Open Gradle plugin from 1.6.21
to 1.8.21
.
jvm Gradle plugin
Update Kotlin jvm
Gradle plugin from 1.6.21
to 1.8.21
.
Set source and target compatibility to Java 17
Micronaut Framework 4.0 sets the Java baseline to 17.
Update your Gradle build and set source and target compatibility.
java {
sourceCompatibility = JavaVersion.toVersion("17")
targetCompatibility = JavaVersion.toVersion("17")
Micronaut Framework BOM
The Micronaut Gradle plugin applies the Micronaut Bill of Materials (BOM). However, if you were applying the BOM directly to your build. You should use io.micronaut.platform:micronaut-platform
.
The Micronaut Platform BOM exists since Micronaut framework 4, and corresponds to the Micronaut framework 3 BOM which was published at io.micronaut:micronaut-bom
. In Micronaut framework 4, we provide both the Micronaut Platform BOM (io.micronaut.platform:micronaut-platform
) and the Micronaut Core BOM (io.micronaut:micronaut-core-bom
).
Maven Applications
Parent POM
Parent’s coordinate has changed.
Replace:
<parent>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-parent</artifactId>
With:
<parent>
<groupId>io.micronaut.platform</groupId>
<artifactId>micronaut-parent</artifactId>
Version update
Set micronaut.version
property in pom.xml
.
<parent>
<groupId>io.micronaut.platform</groupId>
<artifactId>micronaut-parent</artifactId>
<version>4.0.0-M2</version>
</parent>
<properties>
...
<micronaut.version>4.0.0-M2</micronaut.version>
</properties>
Set source and target compatibility to 17
Micronaut Framework 4.0 sets the Java baseline to 17.
Set in pom.xml
the following properties:
<properties>
...
<jdk.version>17</jdk.version>
<release.version>17</release.version>
...
</properties>
Environment Deduction Disabled by Default
Environment deduction is disabled by default in Micronaut framework 4. You can enable it by setting the micronaut.env.deduction
system property or the MICRONAUT_ENV_DEDUCTION
environment variable to true or changing your main
class.
public class Application {
@ContextConfigurer
public static class DeduceCloudEnvironmentConfigurer
implements ApplicationContextConfigurer {
@Override
public void configure(@NonNull ApplicationContextBuilder builder) {
builder.deduceCloudEnvironment(true);
}
}
public static void main(String[] args) {
Micronaut.run(Application.class, args);
}
}
YAML Configuration
Micronaut Framework 4.0 does not expose SnakeYAML as a transitive dependency.
If you use YAML for your application configuration, add the following dependency:
For Gradle:
dependencies {
...
runtimeOnly("org.yaml:snakeyaml")
}
For Maven:
<dependency>
<groupId>org.yaml</groupId>
<artifactId>snakeyaml</artifactId>
<scope>runtime</scope>
</dependency
JSON Serialization
Micronaut Framework 4.0 does not expose Micronaut Jackson Databind as a transitive dependency.
Thus, you must choose which serialization implementation you want.
How to use Micronaut Jackson Databind
To use Micronaut Jackson Databind with Gradle, add the following dependency:
dependencies {
...
implementation("io.micronaut:micronaut-jackson-databind")
}
Or to your Maven build:
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-jackson-databind</artifactId>
<scope>compile</scope>
</dependency>
How to use Micronaut Serialization
To use Micronaut Serialization with Gradle, add the following dependency:
dependencies {
...
annotationProcessor("io.micronaut.serde:micronaut-serde-processor")
implementation("io.micronaut.serde:micronaut-serde-jackson")
}
Or to your Maven build:
<dependency>
<groupId>io.micronaut.serde</groupId>
<artifactId>micronaut-serde-jackson</artifactId>
<scope>compile</scope>
</dependency>
</dependencies>
...
..
.
<annotationProcessorPaths>
...
<path>
<groupId>io.micronaut.serde</groupId>
<artifactId>micronaut-serde-processor</artifactId>
</path>
</annotationProcessorPaths>
Micronaut Validation
Micronaut framework 4.0 moves Micronaut Validation to its own module. You need to replace the usage of the old coordinate io.micronaut:micronaut-validation
.
To use Micronaut Validation with Gradle, add the following dependency:
dependencies {
...
annotationProcessor("io.micronaut.validation:micronaut-validation-processor")
implementation("io.micronaut.validation:micronaut-validation")
}
Or to your Maven build:
<dependency>
<groupId>io.micronaut.validation</groupId>
<artifactId>micronaut-validation</artifactId>
<scope>compile</scope>
</dependency>
</dependencies>
...
..
.
<annotationProcessorPaths>
...
<path>
<groupId>io.micronaut.validation</groupId>
<artifactId>micronaut-validation-processor</artifactId>
</path>
</annotationProcessorPaths>
Jakarta constraints
Replace the usage of javax.validation.constraints
with jakarta.validation.constraints
.
For example, replace:
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
with:
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
Websockets
Micronaut framework 4.0, io.micronaut:micronaut-http-server
no longer exposes micronaut-websocket
dependency transitively. To keep using [Micronaut WebSocket Support] add the following dependency to your application:
With Gradle:
implementation("io.micronaut:micronaut-websocket")
Or Maven
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-websocket</artifactId>
</dependency>
Jakarta Persistence Annotations
Replace the usage of javax.persistence
with jakarta.persistence
.
For example, replace:
import javax.persistence.GenerationType;
import javax.validation.constraints.NotNull;
import javax.persistence.Column;
import javax.persistence.Convert;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
with:
import jakarta.persistence.GenerationType;
import jakarta.validation.constraints.NotNull;
import jakarta.persistence.Column;
import jakarta.persistence.Convert;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
Retry Functionality
To use retry capabilities (@Retryable
, @Recoverable
), with Micronaut framework 4.0 you need to add the following dependency:
With Gradle:
implementation("io.micronaut:micronaut-retry")
With Maven:
<dependency>
<groupId>io.micronaut</groupId>
<artifactId>micronaut-retry</artifactId>
</dependency>
Micronaut Session
Micronaut framework 4.0 moves session capabilities to a new module, Micronaut Session. If you use session, replace the coordinates io.micronaut:micronaut-session
with io.micronaut.session:micronaut-session
.
Reactor Instrumentation moved to Reactor Module
Micronaut framework 4.0 moves Reactor instrumentation to Micronaut Reactor module. If you use Project Reactor, ensure you have the following dependency:
With Gradle:
implementation("io.micronaut.reactor:micronaut-reactor")
With Maven:
<dependency>
<groupId>io.micronaut.validation</groupId>
<artifactId>micronaut-validation</artifactId>
</dependency>